@swarmcraftai/cli 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to the SwarmCraft CLI are documented in this file.
 
+## 0.5.0
+
+- Adds deterministic `operate init`, `operate validate`, and `operate status` commands for local operational work, with Codex and Copilot guidance for Work, Automate, and Formalise.
+- Seeds and reconciles operational models, records, knowledge, and bounded automation guidance while preserving owner edits; initialization validates the result and creates a scoped local Git checkpoint without pushing.
+- Supports a private stdin session handoff from VS Code for Operate initialization, with session verification before workspace mutation and content-free, retryable activity reporting.
+- Validates approved operational formalisation and source digests when preparing Deep Discovery evidence, blocking stale or cancelled approvals.
+- Adds SwarmCraft-managed AI to one-shot workflows, including credit balance and stage estimates, measured per-call consumption, and resumable insufficient-credit outcomes. Customer-supplied Codex, Copilot, and custom providers remain supported.
+- Seeds versioned project environment requirements from structured build profiles and documents local-model execution through custom agent commands.
+- Requires the matching API credit, Managed AI, and Operate telemetry contracts; deploy the coordinated API and web release before publishing this client.
+
 ## 0.4.2
 
 - Reconciles generated repository skills through a monotonic, owner-preserving template-set contract before new one-shot runs, while retaining the recorded guidance for resumed runs.

package/README.md

@@ -1,5 +1,9 @@
 # SwarmCraft CLI
 
+When the reviewed discovery source selection includes `docs/discovery/sources/operation-formalisation.md`, package preparation also verifies the current operational approval, model identity and selected digests against that copied source. Missing, stale or cancelled approval blocks preparation with `DP_OPERATION_SOURCE_STALE`. This does not replace the existing curated-document, package-validation or upload-consent gates.
+
+Editor integration: `operate init --session-stdin` accepts a bounded JSON object with `apiBaseUrl` and `accessToken` through a private stdin pipe. The VS Code extension uses this to reuse its browser session. The CLI verifies the session before mutation and neither reads nor writes its saved session file in this mode. Never put credentials in shell command text. Normal terminal use continues to use `swarmcraft auth login`.
+
 SwarmCraft CLI prepares a local repository for a SwarmCraft project board and runs packet-based agent workflows from the terminal.
 
 Use it to authenticate with SwarmCraft, list available projects, seed workspace guidance files, materialize task packets, run one-shot implementation passes, resume or inspect runs, and create support bundles.
@@ -23,6 +27,7 @@ Deep Discovery uses the provider-neutral `@swarmcraft/discovery-package-contract
 - `src/workspace.ts` owns workspace validation and contained file/git operations. `src/runtime/workspace-paths.ts` rejects absolute, traversal, escaped run, manifest, log, and support-artifact targets.
 - `src/runtime/process.ts` provides shell-free argument-array execution. Only `runTrustedShellAgentCommand` may invoke a shell for a deliberately supplied custom-agent template; API content and credentials must never be interpolated into it.
 - `src/bootstrap.ts`, `src/discovery.ts`, and `src/oneShot.ts` compose the seed, immutable discovery-package, and packet execution workflows.
+- `src/operation/` owns Operate filesystem/Git preflight, shared-seed reconciliation, local inspection, and content-safe status; `src/commands/operate-commands.ts` owns its session validation, cancellation, output, and exit codes.
 - `src/workflows/agent-execution.ts` owns approved credential injection, trusted template quoting, and optional cost capture. `src/artifacts/run-manifest.ts` owns contained paths and atomic resume-manifest persistence.
 - `src/supportBundle.ts` exposes only allow-listed delegation facts and recursively redacts secret-bearing keys.
 
@@ -43,7 +48,7 @@ One-off use is also supported:
 npx @swarmcraftai/cli --help
 ```
 
-Public publishing is owned by the release workflow in `.github/workflows/publish-cli.yml`. Run the local package smoke before publishing:
+Public publishing is owned by the Azure pipeline in `azure-pipelines.cli-release.yml`, with staged npm publishing and final maintainer approval. See [the CLI release runbook](../../docs/runbooks/swarmcraft-cli-npm-release.md). Run the local package smoke before publishing:
 
 ```bash
 pnpm cli:release:smoke
@@ -87,11 +92,67 @@ swarmcraft status --run <run-id> --workspace <path> --delegation <delegation-id>
 swarmcraft delegation end --delegation <delegation-id>
 ```
 
-Interactive login conceals password input. When MFA is enrolled, the same command securely prompts for the current authenticator code and offers a recovery-code fallback; secrets do not need to be placed in the command line.
+## Operate Locally
+
+Operate is a starting path for operational work, not a third application-generation route. The seeded `swarmcraft-work` skill completes useful work and maintains terminology, knowledge, systems, and domain records. `swarmcraft-automate` considers bounded repeatability, including after one suitable task; `swarmcraft-formalise` prepares a reviewed application opportunity. Seeding all three does not execute them, approve automation, upload evidence, or transfer record ownership to a generated app.
+
+```bash
+swarmcraft auth login
+swarmcraft operate init --workspace /path/to/repository --agent-provider codex
+swarmcraft operate init --workspace /path/to/existing-repository --agent-provider copilot --adopt
+swarmcraft operate validate --workspace /path/to/repository --json
+swarmcraft operate status --workspace /path/to/repository --json
+```
+
+`operate init` creates a new directory/Git repository or reconciles an existing Operate seed. A nonempty unseeded directory requires `--adopt`. It previews the shared seed before writing, rejects nested Git roots, unsafe filesystem links, staged changes to affected files, owner-edited generated-file conflicts, and unsupported versions. Unrelated dirty and staged work is preserved. All three Operate skills are seeded; start with Work. After validation it commits only exact seed content and approved removals as `SwarmCraft: Initialize or reconcile Operate`. Owner-edited records and ignored data are excluded; unchanged retries create no empty commit. Git identity, signing or hook failures leave files available with `OPERATE_SEED_COMMIT_FAILED`; fix Git and rerun. It never pushes, executes an agent, or writes to third-party systems.
+
+Initialization validates the saved CLI session against `GET /auth/me` before creating or modifying the target. Expired sessions use the existing refresh flow. The API origin comes from the saved session; there is no workspace-controlled API override. Credentials remain in the existing owner-only session file. Initial session/connectivity failure leaves the target untouched.
+
+Seed activities are reported through `POST /telemetry/operate-events` with closed classifications and a random occurrence UUID. The UUID and new/adopted classification are stored in ignored `.swarmcraft/runs/operate-init.json` so rerunning initialization reuses the same occurrence. Reporting failure produces a visible warning and does not undo local work; rerun initialization to retry. There is no background uploader or server registration. `--client-surface vscode-extension` is available for extension delegation.
+
+Validation and status are offline and use `@swarmcraft/operation-contract` for model/record checks, reviewed knowledge links, and formalisation digests. They also report ignored authoritative files and tracked raw/scratch files without exposing file contents or ignore patterns. Inventory is capped at 20,000 paths, individual text reads at 2 MB, and loaded evidence at 20 MB. Output includes only safe codes, capabilities, version, and evidence states. Discovery/project presence indicates local artifacts, not verified server connectivity. Automation presence does not imply approved readiness; repeatability remains `NOT_ASSESSED`.
+
+Both commands accept `--json`. Exit codes are 0 for success, 2 for sign-in required, 3 for invalid/missing operation evidence, 4 for workspace/option/conflict failures, 5 for session-verification connectivity failure, and 130 for cancellation. After interruption, rerun initialization to reconcile; seed state is written last and owner edits are preserved.
+
+## Agent Providers And Local Models
+
+SwarmCraft does not require a particular hosted model. The CLI delegates each packet stage to the selected Codex or GitHub Copilot CLI, and `--agent-command` can override the default provider command to select any model that the underlying agent supports. This includes local models served by Ollama.
+
+Before starting a local-model run, start Ollama and pull an agent-capable coding model. Local models used through GitHub Copilot CLI must support tool calling and streaming; a large context window is strongly recommended. Model capability and output quality vary, so begin with one task and a bounded request count.
+
+Run GitHub Copilot CLI against a local Ollama model without a GitHub-hosted model request:
+
+```bash
+swarmcraft one-shot \
+  --project <project-id> \
+  --workspace <path> \
+  --agent-provider copilot \
+  --agent-command 'COPILOT_PROVIDER_BASE_URL=http://localhost:11434/v1 COPILOT_MODEL=qwen3-coder:30b COPILOT_OFFLINE=true copilot --allow-all-tools --no-ask-user -p {command}' \
+  --task-limit 1 \
+  --max-agent-requests 1
+```
+
+Run Codex CLI directly against Ollama:
+
+```bash
+swarmcraft one-shot \
+  --project <project-id> \
+  --workspace <path> \
+  --agent-provider codex \
+  --agent-command 'codex exec --sandbox workspace-write --oss --local-provider ollama --model qwen3-coder:30b {command}' \
+  --task-limit 1 \
+  --max-agent-requests 1
+```
+
+Replace `qwen3-coder:30b` with a locally installed model name from `ollama list`. The CLI intentionally gives agent subprocesses a restricted environment, so local, non-secret provider settings are included in the trusted command template above. Never place API keys or other secrets in `--agent-command`; for authenticated providers, use `--agent-env-file` with `--agent-api-key-env-name`.
+
+## Command Workflows
+
+SwarmCraft Setup is the supported macOS and Windows foundation path before using this experienced terminal client. Interactive CLI login remains the explicit AAA V2 email fallback: it conceals password input, prompts for optional policy-required TOTP step-up, and keeps the restricted recovery-code path out of command history. GitHub, Google, and passkey sign-in remain browser-owned web and VS Code flows.
 
 `swarmcraft init` validates the workspace git state, seeds the shared SwarmCraft repo guidance files, materializes non-done task packets, links those packets back to SwarmCraft, and prints the next commands.
 
-Repository seeding uses the same monotonic template-set contract as the VS Code extension. A newer CLI adds missing skills and updates unchanged generated guidance, preserves owner edits as conflicts, removes only unchanged retired files, and never downgrades guidance written by a newer client. The CLI leaves these repository changes uncommitted for normal review. New one-shot runs reconcile before agent execution; resumed runs retain their existing run guidance rather than reseeding midway through the run.
+Repository seeding uses the same monotonic template-set contract as the VS Code extension. A newer CLI adds missing skills and updates unchanged generated guidance, preserves owner edits as conflicts, removes only unchanged retired files, and never downgrades guidance written by a newer client. Project seeding leaves these changes uncommitted for normal review; Operate initialization instead creates a scoped local checkpoint. New one-shot runs reconcile before agent execution; resumed runs retain their existing run guidance rather than reseeding midway through the run.
 
 The task contract is a clean cutover from the earlier project-ticket format. Upgrade the API, CLI, and VS Code extension together; old `ticketId` packet files and `--ticket` flags are not accepted. Preserve any owner-authored notes, remove the retired generated packet files, and run `swarmcraft init` again to materialize current `taskId` packets from the board.
 
@@ -107,6 +168,14 @@ Run diagnostics contain only schema version, phase, error class, timestamps, cou
 
 `swarmcraft one-shot` bootstraps the workspace, runs the doing lane through the selected agent provider, syncs packet updates back to SwarmCraft, writes `.swarmcraft/runs/<run-id>/manifest.json`, streams progress to the terminal, writes agent logs under `.swarmcraft/runs/<run-id>/logs/`, and moves accepted work to `done` by default. With checking off, the driver ignores the reusable implementation skill's normal checking handoff, syncs its evidence, moves the task directly to `done`, commits when requested, and continues. Before synchronization, the CLI reloads the server-authoritative board and retries bounded optimistic-revision conflicts, allowing one-shot to run while the VS Code extension is open and observing the same packets. Customer one-shots should normally pair this with `--commit-policy done` so each completed task creates a local commit. Use `--checking on` or `--reviewing on` only for internal validation runs that deliberately need those extra lanes.
 
+Choose `--agent-provider managed` to use SwarmCraft-managed AI. The CLI shows the current
+credit balance and estimated stage range before starting, then consumes measured credits one
+provider call at a time. Provider credentials, model selection, prices, and settlement remain on
+the API; prompts, repository source, and provider responses are not written to billing records.
+If the next bounded call cannot be funded, the local run is marked blocked and can be resumed
+after credits are added. Codex, Copilot, and custom customer-supplied providers remain outside
+the Managed AI fee.
+
 For interface-bearing packets, the generated `swarmcraft-do` contract owns design conformance even when checking is off: it resolves the owner-controlled locator, uses applicable system capabilities, covers relevant states, runs existing required design commands, and records exact evidence in packet notes. A failing required deterministic design gate must leave doing incomplete. One-shot does not install design tooling, infer authority to mutate the design system, or treat unavailable visual evidence as passing.
 
 Useful safety and support commands: