Plugin system with example Immich plugin

.gitignore

@@ -27,3 +27,5 @@ node_modules/
 .cookies/
 
 .claude/
+
+*.har

CONTRIBUTING.md

@@ -160,10 +160,33 @@ For `musl` binaries, use `Dockerfile.build-musl`
 
 ### Building the Docker
 
+For local development, use the helper script that handles the complete build process:
+
+``` sh
+scripts/build_docker_local [platform]
+```
+
+This script:
+1. Builds musl binaries using Docker buildx
+2. Renames them to the versioned format expected by the Dockerfile
+3. Builds the Docker image tagged as `icloudpd_dev`
+
+Default platform is `linux/amd64`. Other options: `linux/arm64`, `linux/arm/v7`
+
+Example:
+``` sh
+scripts/build_docker_local linux/amd64
+docker run --rm icloudpd_dev icloudpd --version
+docker run --rm icloudpd_dev icloudpd --plugins-list
+```
+
+Alternatively, you can build manually (requires renaming binaries to versioned format):
+
 ``` sh
-docker build -t icloudpd_dev_ .
+docker build -t icloudpd_dev .
 ```
-Note: command packs existing musl binaries from dist folder
+Note: command packs existing musl binaries from dist folder with versioned names
+(e.g., `icloud-1.32.2-linux-musl-amd64`, `icloudpd-1.32.2-linux-musl-amd64`)
 
 ### Developing Documentation
 

Dockerfile.build-musl

@@ -38,6 +38,7 @@ COPY scripts scripts/
 COPY binary_dist binary_dist/
 COPY pyproject.toml .
 COPY src src/
+COPY plugins plugins/
 # staticx must be installed after scons
 # staticx gives error: Error relocating /tmp/staticx-pyi-9b5nvfi_/_cffi_backend.cpython-312-x86_64-linux-musl.so: PyNumber_Long: symbol not found, so not using for musl
 RUN \

README.md

@@ -67,7 +67,44 @@ To independently create and authorize a session (and complete 2SA/2FA validation
 icloudpd --username my@email.address --password my_password --auth-only
 ```
 > [!TIP]
-> This feature can also be used to check and verify that the session is still authenticated. 
+> This feature can also be used to check and verify that the session is still authenticated.
+
+## Plugins
+
+icloudpd includes a plugin system that allows you to extend functionality by hooking into the download process. Plugins can respond to events like file downloads, process photos after they're downloaded, and integrate with external services.
+
+### Using Plugins
+
+Enable a plugin with the `--plugin` flag:
+
+```bash
+icloudpd --directory /photos --username me@example.com --plugin immich
+```
+
+Each plugin adds its own CLI arguments. Use `--help` to see available options:
+
+```bash
+icloudpd --plugin immich --help
+```
+
+### Built-in Plugins
+
+- **[Immich](plugins/immich/README.md)** - Integrates with [Immich](https://immich.app) photo management. Automatically registers downloaded photos, creates stacks for size variants, syncs favorites, and organizes photos into albums.
+
+- **[Demo](src/icloudpd/plugins/demo.py)** - Demonstrates the plugin system's capabilities. Use as a reference when building your own plugins:
+  ```bash
+  icloudpd --plugin demo --demo-verbose --recent 5
+  ```
+
+### Building Your Own Plugins
+
+For developers interested in creating custom plugins, see the [Plugin Development Guide](docs/plugins.md) which covers:
+
+- Available hooks and when they're called
+- How to accumulate and process photo data
+- Best practices and common gotchas
+- Testing your plugin
+- Complete code examples
 
 ## Contributing
 

docs/index.md

@@ -17,5 +17,6 @@ size
 raw
 webui
 nas
+plugins
 reference
 ```