@backifydev/cli 0.3.4 → 0.3.5

package/README.md

@@ -1,6 +1,250 @@
-# @backifydev/cli
-
+# @backifydev/cli
+
+## Source-bound worker build provenance
+
+The opt-in protected CI workflow creates one worker build with OIDC-signed evidence.
+Use **backify workload provenance verify --policy ... --report ... --bundle ...
+--trusted-root ...** with reviewed source, workflow, application and image pins.
+Independent rebuilds and base-supplier signatures are optional stronger checks;
+policy-required evidence and invalid signatures still fail closed. The baseline
+does not claim reproduction or supplier authentication. This does not authorize
+deployment or change existing HCR v1 installation behavior. See the
+[build provenance guide](../../docs/worker-build-provenance.md).
+
+## Local runtime and hosted containers
+
+Use runtime install --version vX.Y.Z --sha256 <reviewed-hash> [--archive <zip>]
+and runtime doctor for an explicitly reviewed self-contained local HCR. Native
+PostgreSQL tools are a separate prerequisite. The source includes a Windows/macOS/
+Linux CI matrix; published release assets remain an operator release step.
+
+The full-stack scaffold includes a Dockerfile and a same-origin production HTTP
+server. ship accepts this container path for both Backify Cloud and customer Azure;
+CI builds an immutable registry digest and publishes to Preview, not directly live.
+Production promotion retains optional independent approval. See
+[provider configuration and rollout](../../docs/hosting-provider-config.md).
+
+## Immutable worker artifact planning
+
+`backify workload artifact-plan --organization <UUID> --app <UUID> --environment <UUID> --deployment <UUID> --source-commit <commit> --image <registry/repository@sha256:digest> --jobs-file worker-jobs.json --entry src/worker.ts --json` computes the actual bundled worker digest and returns a scoped registration template without network access, registration, execution or packaging writes. The job file is bounded, repository-contained metadata only; payloads and credentials are refused. Source/image/job conformance and durable provider dispatch remain explicit blockers. See the [worker artifact guide](../../docs/worker-artifacts.md).
+
+## Explicit local development identity
+
+Declare auth intent and run dev --identity-users local-users.json --backend-port
+3000 with reviewed repository-contained user profiles. identity users|issue|clear
+--local --json uses the authenticated operator session; issue additionally requires
+--user <reviewed-UUID>. Issuance deliberately returns a private five-minute local
+credential, not a production JWT or operator/workload token. Do not log or commit
+its output. No anonymous login, cookie, roles or production fallback is created.
+See [local identity boundaries and profile format](../../docs/local-development.md).
+
+## Read-only local data inspection
+
+`backify inspect events --local --json` reports only status counts and the latest
+100 event metadata rows. The Events panel uses the same authenticated loopback API;
+neither view reveals payloads, producer keys or lease receipts. The local broker
+persists leases, attempts and deduplication across worker restarts in private
+snapshots. It remains a single-worker local emulator, not a production cloud queue.
+
+In full mode, enabled declared events instead use an owned dedicated PostgreSQL
+inbox after explicit review of the HCR SQL asset and --apply-migrations approval.
+Old snapshot records keep their IDs, keys and receipts and drain locally; native
+payloads/receipts are never copied into snapshots. Combined inspection remains
+metadata-only. Missing initialized schema or ownership is never recreated on
+restart. Native emission acceptance preserves process-local hooks without firing
+them for duplicate keys; hooks are not distributed subscriptions.
+
+The authenticated dashboard includes Data, Jobs, Events and Logs panels. Native inspection
+uses actual scoped PostgreSQL/filesystem providers; unavailable providers are not
+replaced with empty emulator responses. Row pages, file metadata and explicit
+text/binary previews are bounded. Credential-named row fields are redacted and
+all data is rendered as text. No data editing/deletion controls are added.
+
+Use `backify inspect tables|rows|buckets|objects|preview|events --local --json` for stable
+operator-facing JSON. Row inspection needs `--table`; objects/preview need
+`--bucket`, and preview also needs `--key`. Optional `--limit`/`--offset`
+page rows/objects; `--prefix` filters object metadata. Arbitrary SQL, writes,
+cloud fallback and unchecked pagination are rejected. See the
+[local guide](../../docs/local-development.md) for bounds and browser/native tests.
+
+
+## Authenticated workload packaging
+
+An explicit `auth` declaration now configures request-scoped end-user verification
+in packaged HTTP/worker hosts. Plans report a read-only public-trust directory,
+`BACKIFY_APPLICATION_AUTH_TRUST_FILE` and independently pinned organization,
+application and environment IDs. Missing or mismatched scope/trust fails startup;
+corrupt or stale mounted rotations fail requests closed. Issuer enrollment, fleet
+installation and production rollout remain blockers; no keys or tokens are bundled.
+New authenticated artifacts also require BACKIFY_APPLICATION_AUTH_STATE_FILE and
+a separate writable private persistent directory. Use workload trust-state plan,
+then workload trust-state initialize with --confirm, absolute --trust-file and
+--state-file, independently pinned --organization/--application/--environment,
+and the reviewed --revision. Initialization refuses existing state; bootstrap never
+recreates missing state. Journal rollback/mutation and corruption fail closed even
+after a process restart. Lock/volume recovery and Windows ACLs remain operator duties.
+See [application identity](../../docs/application-identity.md).
+
+
+## Operator public-trust polling
+
+Use `backify workload trust-sync plan|once|run --configuration <absolute-json>`
+outside workloads. Review `plan` first; `once` and `run` require `--confirm`.
+The strict configuration pins scope/agent and management issuer/audience/public key,
+and supplies distinct absolute credential/public-output/private-journal paths.
+Initialize the operator journal explicitly with the reviewed trust-state workflow;
+do not reuse a workload journal or mount management credentials in applications.
+
+Plans do not read credentials, network or write. Polling rereads the private token,
+verifies versioned signed delivery, atomically publishes public-only trust, and
+uses serial bounded backoff and SIGINT/SIGTERM shutdown. Missing state, rollback,
+mutations and retained locks fail closed; failed publication retains evidence.
+Windows ACLs remain an operator duty. Eligible polls can trigger public-document
+renewal only with the separate, explicitly initialized opt-in control-plane ledger.
+The CLI never generates issuer trust, rotates keys, renews agent credentials,
+installs fleet services or makes deployment production-ready.
+See [configuration and recovery limits](../../docs/application-identity.md#signed-operator-trust-delivery).
+
+Local development supports --mode lightweight and --mode full. PostgreSQL engine
+or migration intent selects full mode automatically. Full mode starts isolated
+native PostgreSQL/HCR services; set --hcr-path/BACKIFY_LOCAL_HCR_PATH for an approved
+HCR artifact and --postgres-bin/BACKIFY_LOCAL_POSTGRES_BIN for PostgreSQL tools.
+Review pending SQL before passing --apply-migrations. --hcr-port/--database-port
+configure service ports; the existing --port configures the local dashboard.
+Missing prerequisites fail explicitly, and shutdown preserves local data.
+See [full-fidelity local services](../../docs/architecture/local-full-fidelity.md).
+
+Native jobs require paired --job-artifacts <reviewed-json> and --job-worker
+<repository-relative-packaged-directory>. First review and approve both jobs SQL
+assets with --apply-migrations; restarts retain data without repeating approval.
+The bundle must be a separately packaged worker matching the reviewed SHA-256
+and current normalized manifest. Native admission selects full mode and never
+falls back to the snapshot executor. Canonical enqueue, acknowledged backend
+schedules and manual operator dispatch execute through independent pinned Node
+processes against the real queue. Native cancellation is pending-only; native
+UUID retry creates one stable new run per scoped failed source/current worker
+artifact, preserving original payloads/pins/history. Replay does not repeat a
+completed retry; retry a newly failed UUID for another attempt. Original legacy rows/payloads/pins remain retained;
+explicit failed-row retry creates a new native run. Worker-declared schedules are
+discovered before backend import through the bounded hcr-schedules-v1 protocol.
+Support is pinned in the immutable bundle header, not mutable artifact metadata;
+older bundles retain explicit legacy-backend-declarations-only scheduling.
+Discovery enables SDK job registration only and never invokes handlers. It is not
+an OS sandbox or hosted scheduler. Auth-enabled workers now require an additional
+--job-auth <reviewed-json> pinning repository-relative public trust/private existing
+antirollback state, exact scope, revision and trust byte digest. Fresh local ownership
+adopts the reviewed scope; retained scope conflicts refuse without changing data.
+Mounts are rechecked before execution; local identity fixtures cannot be mixed in.
+Explicit --job-trust-sync <reviewed-json> enables signed active-worker trust renewal
+in the CLI supervisor. Management configuration/credentials are never forwarded
+to application processes. Exact publication digests and owned IPC update existing
+mounts only; watch reload retains accepted pins, while whole CLI restart requires
+reviewing current auth descriptor bytes/revision. Identical shared historical mounts
+follow one configuration; separate mounts may specify trustSyncFile. Existing valid
+trust survives management outages, expiry remains fail-closed, and shutdown aborts
+owned polling. This does not renew management credentials or install a fleet.
+Explicit --job-history
+<reviewed-json> admission activates up to fifteen unique original workers alongside
+the current worker. Supply each original artifactVersion, workerDirectory and
+manifestFile, plus authFile when its original manifest enables auth. The original
+portable manifest digest and actual bundle must match, all versions must also be
+reviewed in --job-artifacts, and resources/issuer scope must remain compatible with
+the current owned application. Retired source/migrations are not imported/applied.
+Receipts stay original-pinned; historical schedule declarations are not resynced.
+Current dispatch/retry/discovery stay current-worker owned. Exact duplicate old-pin
+acknowledgement can recover a lost schedule checkpoint, but never create new old
+runs or repin history. Active workers share bounded concurrency; metadata omits
+paths/trust mounts. This is not signed cloud/fleet activation or an OS sandbox.
+See [reviewed workflow and limits](../../docs/local-development.md#reviewed-independent-native-jobs).
+
 Set up, connect, record requests, and ship a Backify application repository. CLI 0.3.0 adds the connected AI delivery workflow.
+
+## Full-stack starter
+
+In an empty folder, run backify scaffold --app app_xxxxx --name my-application
+with the application ID supplied by Backify. It writes a React/Vite frontend, Hono
+HTTP server, declaration-only scheduled worker, tests and current project guidance.
+It never installs dependencies, provisions resources or overwrites existing source.
+Identical output is idempotent; linked paths, existing applications, modified
+instructions and conflicting files fail before generated files are written.
+Use compatible workspace builds until these source-only CLI/SDK additions are released.
+Run npm install, npm test, npm run typecheck, npm run build and npm run dev in the
+generated project. The same-origin /api proxy avoids exposing workload tokens to React.
+The liveness endpoint is public; private business APIs require trusted end-user
+authorization, which is deliberately not fabricated by this starter.
+See [local workflow and browser verification](../../docs/local-development.md).
+
+## Independent OCI workloads
+
+Explicit canonical job producers use optional BACKIFY_JOB_ARTIFACT_SHA256 and
+BACKIFY_JOB_BINDING host configuration. The target worker digest is independent
+of the HTTP bundle digest. A binding without a pin refuses before application
+code loads. Plans keep deploymentReady false and require reviewed HCR worker
+bindings plus the additive producer SQL; packaging never installs SQL or
+automatically activates registered artifacts. Unconfigured enqueue and legacy
+schedules remain unchanged. See [durable jobs](../../docs/hcr-jobs.md).
+
+backify workload plan --kind http|worker emits a non-mutating JSON plan. Workers
+require --entry pointing to a declaration-only module. backify workload package
+also requires --base-image with an approved digest-pinned Node 22+ image reference;
+it writes an isolated generated context without replacing customer Dockerfiles.
+Bundle/artifact pins, private mounted workload credentials and unsupported-provider
+checks fail closed. This does not build images, enroll identities or deploy apps.
+See [workload contracts and limits](../../docs/architecture/oci-workloads.md).
+
+## Local full-stack workflow
+
+The current source includes portable YAML validation, isolated server workers,
+source/manifest watching, persistent local state, job/schedule inspection and an
+authenticated loopback dashboard:
+
+~~~sh
+backify validate --json
+backify dev --open
+backify dev --frontend web --frontend-port 5173 --backend-port 3000 --json
+backify dev --frontend web --frontend-adapter static --frontend-port 5173 --json
+backify status --local --json
+backify jobs list --local
+backify jobs run --local --name daily-report
+backify logs --local
+backify test --json
+~~~
+
+Declare a Node entrypoint in backify.yaml. The SDK local runtime is installed before
+application code loads. The CLI adds .backify/ to the ignore file; never commit its
+records, files or queued payloads. Local mode does not use cloud credentials.
+Full mode starts separate PostgreSQL/HCR services and applies only explicitly
+approved SQL. Lightweight mode retains the document emulator. Optional --frontend
+supervises an already-installed Vite frontend inside the repository; --backend-port
+injects PORT, which application servers must honor. Vite keeps the application
+configuration/HMR but cannot disable mandatory strict filesystem checks or private
+state/secret exclusions. Canonical-path checks also refuse linked/junction access.
+No frontend receives runtime
+credentials. JSON dev lifecycle uses stdout; child diagnostics use stderr. Agents
+may stop an IPC-launched CLI with backify-stop. See [local development and limits](../../docs/local-development.md).
+These additions have not been published to npm.
+
+For encrypted development secrets, declare capabilities.secrets, create a key in
+an existing private directory outside the repository, and supply values only via stdin:
+
+~~~sh
+backify secrets local init --key-file /private/backify-local.key
+backify secrets local set SERVICE_TOKEN --key-file /private/backify-local.key --stdin
+backify secrets local list --key-file /private/backify-local.key
+backify dev --local-secrets-key /private/backify-local.key
+~~~
+
+The ignored vault contains authenticated AES-256-GCM ciphertext only. The external
+key stays outside builds/snapshots; plaintext reaches only the backend through IPC.
+SDK logs redact values, but arbitrary console output/application writes do not.
+Retained vaults fail closed without their key. Restart/rebuild to reload changes.
+Windows private ACLs remain the operator's responsibility. Non-empty local vaults
+with packaged native job workers refuse until a reviewed worker secret broker exists.
+The opt-in static adapter requires index.html rather than Vite/package installation
+and provides protected assets, nested live reload and public backend configuration;
+it does not compile source or implement SSR. See the linked local guide for limits.
+
+## Connected delivery
 
 ```sh
 npx @backifydev/cli init --app app_xxxxx