[bigwolfeman]

Depends on #431, #432, #433, #454, #613 and #455. The branch sits on top of the host layer branch (#613), and one merge commit brings in the SDK branch (#455), so the Files tab also shows their commits until they merge. Review these two commits only:

• craft-cli: the craft developer CLI for plugins
• Merge pr/craft-plugin-sdk into pr/craft-cli, only to see how the conflicts were resolved. Cargo.toml and README.md keep both sides. Cargo.lock keeps the layer branch and gains the two SDK crates. The SDK code itself belongs to Add craft-plugin-sdk and craft-plugin-sdk-macros: the guest SDK for craft-abi 1 plugins #455.

Part of #414.

What

A new crate, craft-cli (crates/cli). It builds the program craft. The library is craft_cli and the binary is a thin wrapper, so every part has tests. The crate is native only: it runs cargo and watches files with notify. It has no wasm32 build and no wasm32 CI job.

Size: 12 source files (1924 lines), 297 lines of plugin templates, 3 test files (815 lines) and one captured command list (226 lines).

The subcommands:

• craft new <name> [--kind command,hook,effect,panel] [--dir DIR] [--id ID] [--sdk-path PATH] writes a plugin package: craft.toml, src/lib.rs with handlers and unit tests, Cargo.toml, .cargo/config.toml and a Cargo.lock. The package depends on craft-plugin-sdk by path. The default path is the crates/plugin-sdk of the craft-libs checkout the binary was built from. Cargo fixes that path at build time, so a copied binary needs --sdk-path. The .cargo/config.toml sets the linker flag for the wasm memory maximum, which the gate requires. The scaffold also has its own [workspace] table, so it builds the same inside or outside another repository.
• craft build [DIR] [--features F] [--out-name N] runs cargo build --release --target wasm32-unknown-unknown in the package, runs the install gate on the module and prints the report. It writes target/<name>.wasm only when the gate accepts the module. A rejected build deletes an older file of that name. Exit code 1 means rejected.
• craft check <WASM>... runs the install gate on each file and prints one line each: ACCEPTED, or REJECTED and one line per violation. Exit code 1 if any file is rejected or cannot be read. This is the subcommand for CI and scripts.
• craft inspect <WASM> [--json] prints the manifest, each op with the permission it needs, the permissions with their prompt level, the memory limits, imports, exports, custom sections and the gate result.
• craft run --headless <WASM> --invoke <ID> [JSON] installs the plugin into a real PluginManager and calls one contribution. The host has no document and no app commands. A command goes through the command registry. A hook or panel gets the JSON as its request. An effect is refused with the reason, because headless has no image source.
• craft watch [DIR] [--install-into FOLDER] builds, then rebuilds after each burst of changes to src/, craft.toml or Cargo.toml. It never watches target/. It copies each accepted module into the folder under a hidden name, then renames it, so a reader never sees a half-written file.
• craft dev <FOLDER> [--invoke ID [JSON]] loads every .wasm in the folder into the headless host and replaces a plugin in place when its file changes. A file that fails the gate is reported and the old version keeps running. The watcher is devfolder::DevFolder<T: DevTarget>, so an app can run it over its own plugin manager.
• craft bindgen --app NAME [--from FILE|-] [--out FILE] turns an app's command list into a Rust module of typed calls to craft_plugin_sdk::cmd::execute. Without --from it runs <NAME>-cli commands --json. The generator reads doc strings with craft_command::schema::from_doc, the code the apps use.

Changes from our staging copy

• The code compiled against the reviewed APIs of Add craft-command: command registry, call hooks and change feed #431, Add craft-plugin-abi: craft-abi 1 types, permission names and install gate #432, Add craft-ipc: local-socket server, client and discovery for Craft apps #433, Add craft-plugin-host engines: wasmi, optional wasmtime and browser engines for craft-abi 1 #454 and Add craft-plugin-host host layer: dispatch, store, lifecycle and contributions #613 with no source change. The CLI does not call Interceptor::before or CommandHost::take_plugin_gate_ids, because it never runs an app. HeadlessServices implements Services as it is on the layer branch.
• New subcommand check. Staging had no short, script-friendly gate command.
• The default SDK path changed from the staging layout (../../crates/plugin-sdk) to ../plugin-sdk, and its doc comment, --help text and the README say that it is fixed at build time and meant for a binary built inside the checkout. The CLI has no other path that assumes the staging layout.
• Cargo.toml uses the workspace fields and [lints] workspace = true. craft-plugin-host and craft-cli are new entries in [workspace.dependencies], since craft-plugin-host was not listed yet.
• Comments and test names that named internal tracker ids or a private "contract" document now read on their own or point at ABI.md. A ignore doc fence became text. craft inspect prints memory_mb 64, stack_kb unset and not Some(64). The agent notes file was rewritten as a short CLAUDE.md.
• The table maximum rule needs nothing new in the CLI. The scaffolded plugin has one funcref table, and wasm-ld writes it with a maximum equal to the minimum (90 entries). I read the table section of the built module to confirm that. The e2e test build_makes_a_wasm_the_gate_accepts fails if that ever changes. No fixture in this PR has a table, and the WAT plugins in tests/devfolder.rs have none. The scaffold has no format contribution, so the fs.picked rule does not apply to any template.

Why

A plugin author needs a way to go from an empty folder to a module the install gate accepts, and to see a change running without an app. Before this PR the only path was to write the Cargo config, the manifest and the build command by hand, and to wait for an app to load the result. The CLI uses the same gate and the same plugin host as the apps (craft_plugin_abi::check_package, PluginManager, the wasmi engine), so a pass in craft build or craft run --headless is the same check an app makes.

Dependencies

Workspace crates: craft-command (#431), craft-plugin-abi (#432), craft-plugin-host (#613, with the engine PR #454). The scaffold needs craft-plugin-sdk (#455) at run time, and the e2e tests build it for wasm32. craft-ipc (#433) is a dependency of the host crate only.

New third-party packages. Cargo.lock grows by 185 lines: the crate and 17 packages. Licenses read from cargo metadata --format-version 1 --locked.

• Direct: clap 4 (not in main's lock. Add craft-command: command registry, call hooks and change feed #431 adds it for a dev tool, MIT OR Apache-2.0), notify 8.2.1 (CC0-1.0), getrandom 0.2.17 (already locked, MIT OR Apache-2.0), wasmparser 0.262.0 (not in main's lock. Add craft-plugin-abi: craft-abi 1 types, permission names and install gate #432 adds it, Apache-2.0 WITH LLVM-exception OR Apache-2.0 OR MIT). Dev: tempfile (in main's lock) and wat (not in main's lock. Add craft-plugin-abi: craft-abi 1 types, permission names and install gate #432 adds it).
• New through clap: clap_derive 4.6.7, anstream 1.0.0, anstyle-parse 1.0.0, anstyle-query 1.1.5, anstyle-wincon 3.0.11, colorchoice 1.0.5, is_terminal_polyfill 1.70.2, once_cell_polyfill 1.70.2, all MIT OR Apache-2.0. utf8parse 0.2.2 is Apache-2.0 OR MIT. strsim 0.11.1 is MIT.
• New through notify: notify-types 2.2.0 (MIT OR Apache-2.0), inotify 0.11.5 and inotify-sys 0.1.8 (ISC, Linux), kqueue 1.2.1 and kqueue-sys 1.1.2 (MIT, BSD and macOS), objc2-core-services 0.3.2 (Zlib OR Apache-2.0 OR MIT, macOS).
• notify is the one non-obvious license: CC0-1.0 is a public domain dedication. There is no deny.toml in the repo, so I could not check it against a written policy. Say so in review if CC0 is not accepted. The alternative is a polling-only watcher, since devfolder already rescans on a timer and the events only make it faster.

Checks

Run on branch pr/craft-cli, with -j4 and one target directory. Test runs used CARGO_PROFILE_DEV_DEBUG=0.

• cargo fmt --check -p craft-cli: exit 0.
• cargo clippy -p craft-cli --all-targets -j4 -- -D warnings: exit 0. The same with --target x86_64-pc-windows-gnu and --target aarch64-apple-darwin: exit 0.
• cargo clippy --workspace --all-targets -j4 --locked -- -D warnings: exit 0.
• cargo test -p craft-cli -j4 --locked: 42 passed, 0 failed, 0 ignored. By file: unit tests 5, tests/bindgen.rs 8, tests/devfolder.rs 6, tests/e2e.rs 23, doc tests 0. The first e2e run took 21.7 s, which includes compiling the SDK for wasm32. The e2e tests run the real craft binary and real cargo.
• By hand, from a directory outside the repo (/tmp), with the debug binary:
  • craft new hello --kind command,hook,panel,effect: created ./hello (command, hook, panel, effect).
  • craft build (with CARGO_BUILD_JOBS=4): cargo Finished release profile in 9.40s, then gate: ACCEPTED, plugin: dev.local.hello "hello" version 0.1.0, ops: 3 declared, 4 contributions, memory 0: initial 5 pages = 0.3 MiB, maximum 1024 pages = 64 MiB, wrote ./target/hello.wasm. The module is 152,187 bytes.
  • craft check target/hello.wasm: target/hello.wasm: ACCEPTED, exit 0.
  • craft run --headless target/hello.wasm --invoke say '{"name":"Ada"}': {"greeting": "hello, Ada"}, [call end] completed.
  • craft dev <folder> --invoke say '{"name":"Bo"}' loaded the plugin as generation 1 and printed hello, Bo.

Not run:

• GitHub CI. The new workflow .github/workflows/cli.yml has not run. It runs fmt, clippy and tests on ubuntu-latest with the wasm32 target installed, and it copies the action pins from ipc.yml and plugin-sdk.yml.
• Tests on Windows or macOS. Only clippy ran for those two targets. The file watcher is notify with its inotify, kqueue and Windows backends, and only the inotify path has run here.
• craft watch by hand. The e2e test edit_rebuild_reload_loop_changes_what_the_plugin_answers drives it: edit, rebuild, reload as generation 2, then a compile error that leaves generation 2 running. I did not run the subcommand in a terminal.
• craft bindgen against a live <app>-cli. The tests use a saved command list (tests/fixtures/filmcraft-commands.json, 45 commands captured from an app) and compile the generated module into a plugin for wasm32.
• cargo test --workspace, and --target wasm32-unknown-unknown for the other crates. This PR changes no other crate. The root Cargo.toml gets two lines and the lock file grows.
• A build of craft-cli for wasm32. It cannot work, and no CI job asks for it. Existing CI jobs check one crate each (-p craft-<name>), so none builds this crate.
• craft new with the default SDK path from an installed binary (cargo install). That case needs --sdk-path, and I did not run it.

Not in this PR

• Launching an app to host the plugin, craft bindgen from a running app over Craft Link, and running the data plane from the command line.
• Developer mode inside the apps. devfolder::DevFolder is the piece they can reuse.
• Publishing craft-plugin-sdk to a registry. Until then the scaffold uses a path dependency.

[FredApps]

Scoped review of CLI build/watch/dev-folder paths at b029d9ede01388901932f1df64ffe75167f20f8b; inherited SDK/host dependencies remain separately reviewed. No local builds or tests run; current hosted checks do not establish passing validation.

[P2] Reconcile ownership when a watched file changes plugin ID or is renamed. DevFolder::scan overwrites known[path].plugin_id after installing the new file without removing its previous_id. Saving plugin B over the path that previously held A leaves A loaded permanently, and deleting the path later removes only B. There is a related normal rename failure: rename a.wasm to b.wasm without changing its plugin ID; the scan installs b first, then sees a gone and removes that same ID, leaving b recorded as loaded while the plugin is actually absent (and its unchanged stamp prevents reload). Reconcile the full path-to-ID set before applying removals/replacements, or explicitly reject duplicate/changed ownership with safe handling. Add tests for both changing the manifest ID at one path and renaming a loaded file.

Remaining CLI subcommands and stack integration still need full review before approval.