@odla-ai/cli 0.4.0 → 0.5.0

package/README.md

@@ -1,14 +1,15 @@
 # @odla-ai/cli
 
-> ⚠️ **Experimental — an agentic-coding experiment.** This package is built and
-> operated by autonomous coding agents as an experiment in agentic loops. APIs
-> change without notice and nothing here is production-hardened. **Use at your
-> own risk.**
+> ⚠️ **Early access — pre-1.0.** Agents work from bounded runbooks; humans
+> approve credentials, production changes, releases, and merges. APIs and exact
+> package availability can change. Review the documented guarantees and
+> limitations; this software is MIT-licensed and provided without warranty.
 
 Project-neutral provisioning CLI for odla apps. It creates and validates an
 `odla.config.mjs`, then uses that config to register an app, enable services,
 push odla-db schema/rules, configure platform AI, configure Clerk auth, record
-deployment links, and write local runtime credentials.
+deployment links, provision o11y ingest credentials, and transfer local or
+deployed Worker secrets without printing them.
 
 It does not know about any specific app. App identity, environments, services,
 schema, rules, auth, AI provider, and links all come from config.
@@ -26,7 +27,8 @@ For a project you keep working in, install it as a dev dependency so the
 shorter `npx odla-ai` form works and the version is pinned by your lockfile:
 
 ```bash
-npm i -D @odla-ai/cli
+npm view @odla-ai/cli@0.5.0 version
+npm i -D --save-exact @odla-ai/cli@0.5.0
 ```
 
 ## Prerequisites
@@ -46,10 +48,13 @@ npm i -D @odla-ai/cli
 ## Commands
 
 ```bash
+npx odla-ai setup
 npx odla-ai init --app-id my-app --name "My App"
 npx odla-ai doctor
+npx odla-ai capabilities --json
+# install SDKs, write the Worker, and create wrangler.jsonc before secret push
 npx odla-ai provision --dry-run
-npx odla-ai provision --write-dev-vars
+npx odla-ai provision --write-dev-vars --push-secrets
 npx odla-ai smoke --env dev
 npx odla-ai secrets push --env dev
 npx odla-ai skill install
@@ -63,8 +68,16 @@ npx odla-ai version
 - `src/odla/rules.mjs`
 - `.gitignore` entries for local credentials
 
+New configs contain only the `dev` environment. Add `prod` explicitly after
+the development flow is healthy; `provision` refuses to mutate `prod` or
+`production` without `--yes` and supports `--dry-run` for review.
+
 `provision` performs the standard safe setup flow:
 
+When using `--push-secrets`, create the Worker and its Wrangler config first.
+The CLI checks that config and `wrangler whoami` before it issues or rotates a
+shown-once credential.
+
 1. Gets an `odla_dev_...` token by device handshake, or reuses
    `ODLA_DEV_TOKEN` / `.odla/dev-token.json`.
    In an interactive terminal it opens the approval page in your browser when
@@ -73,14 +86,28 @@ npx odla-ai version
    best-effort; the printed URL and code always remain the fallback.
 2. Creates the platform app if needed.
 3. Enables configured services in every configured environment.
-4. Mints or reuses each env's odla-db app key.
+4. Mints or reuses each env's configured service credentials: an odla-db app
+   key for `db` and an ingest token for `o11y`.
 5. Pushes the configured schema and rules.
 6. Configures platform AI and stores provider keys in the tenant vault when the
    configured key env var is set.
 7. Writes `.odla/credentials.local.json` with mode `0600`.
-
-Pass `--rotate-keys` to mint fresh db keys. Pass `--no-write-credentials` to
-skip writing the local credentials file.
+8. With `--write-dev-vars`, writes the local Worker values to `.dev.vars`; with
+   `--push-secrets`, transfers the configured service secrets to the matching
+   deployed Worker environment over Wrangler stdin.
+
+Plain reruns are idempotent. Pass `--rotate-o11y-token` only when deliberately
+invalidating and replacing the o11y token; combine it with `--push-secrets` so
+the replacement reaches the Worker in the same run. `--rotate-keys` remains the
+broader credential rotation. Production mutation or secret transfer requires
+`--yes`. Pass `--no-write-credentials` to skip writing the local credentials
+file; it cannot be combined with an operation that would issue a shown-once
+credential.
+
+Rotation and Wrangler secret replacement are not a distributed transaction.
+The CLI preflights Wrangler first and persists the replacement before pushing;
+if that final push still fails, follow the printed `secrets push --env ...`
+retry. Do not run the rotation flag again.
 
 `smoke` verifies a provisioned environment from local credentials. It fetches
 the platform public config, checks the configured AI provider, fetches the live
@@ -88,23 +115,68 @@ odla-db schema with the tenant key, compares expected schema entities, and runs
 a count aggregate against the first entity. It fails early with a clear message
 when provisioning has not written `.odla/credentials.local.json`.
 
-`secrets push --env <env>` moves the env's odla-db key from
-`.odla/credentials.local.json` into the deployed Worker by piping it over
-stdin to `wrangler secret put ODLA_API_KEY` — the value never appears on
-argv, in output, or in an agent's transcript. It preflights `wrangler whoami`
-and the presence of a wrangler config file. The env `prod`/`production`
-targets the top-level wrangler environment (no `--env` flag is passed to
-wrangler) and requires `--yes`; every other env maps to wrangler's
-`--env <name>`. `--dry-run` prints a redacted plan without spawning anything.
-
-`skill install` copies the Claude Code skills bundled with this package
-(currently `odla-migrate`, the phased GitHub Pages → odla migration
-procedure) into the project's `.claude/skills/`, or into `~/.claude/skills/`
-with `--global`. Re-runs are idempotent; a locally modified skill file is
-never overwritten without `--force`. The skill's reference runbook is served
-at <https://odla.ai/llms-migrate.txt>; the human companion — "Moving your site
-to odla" (accounts, the approval code, costs) — lives in the odla docs after
-sign-in.
+The bundled build/migration skills add a passive pre-ship gate with
+`@odla-ai/security`: after the exact-version availability check, run
+`npm i -D --save-exact @odla-ai/security@0.1.0`, then
+`npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical`.
+This is a separate binary, not a hidden `odla-ai` subcommand; it makes no model
+calls and does not execute target code.
+Before installing the exact release, require
+`npm view @odla-ai/security@0.1.0 version` to succeed before installation. An
+exact-version `E404` means the release is unavailable, not that the security
+preflight passed, and does not prove the package name is absent. odla's own
+engineering environment uses an equivalent internal gate; customer projects
+should use the published `odla-security` command above.
+
+`secrets push --env <env>` is the narrower recovery/retry command. It moves the
+configured env's odla-db key and/or o11y ingest token from
+`.odla/credentials.local.json` into the deployed Worker by piping each value
+over stdin to `wrangler secret put`; values never appear on argv, in output, or
+in an agent's transcript. It preflights `wrangler whoami` and the presence of a
+wrangler config file. The env `prod`/`production` targets the top-level
+wrangler environment (no `--env` flag is passed to Wrangler) and requires
+`--yes`; every other env maps to `wrangler --env <name>`. `--dry-run` prints a
+redacted plan without spawning anything. For the normal path, use
+`provision --write-dev-vars --push-secrets` so service enablement, credential
+issuance, local config, and deployed secret transfer stay one composition.
+
+## Who does what
+
+If a change is deterministic from `odla.config.mjs`, the CLI owns it: app and
+service enablement, credential issuance and local persistence, `.dev.vars`,
+schema/rules/auth/AI configuration, and Wrangler secret transfer. The coding
+agent owns application semantics: installing `@odla-ai/o11y`, wrapping the
+Worker with `withObservability`, and choosing useful spans, metrics, errors, and
+LLM-usage records. The human owns the device approval, production consent, and
+explicit destructive rotation. Studio is where people view telemetry and
+perform manual recovery; its token control is not the normal setup path.
+Run `npx odla-ai capabilities` for the human-readable contract or add `--json`
+when an agent or tool needs to branch on it without scraping prose.
+
+`setup` (and `skill install`) installs one complete offline runbook bundle at
+`.agents/skills/`, then adds thin native adapters for Claude Code
+(`.claude/skills/`), Codex, Cursor (`.cursor/rules/`), GitHub Copilot
+(`.github/copilot-instructions.md`), Gemini CLI (`GEMINI.md`), and portable
+`AGENTS.md` agents. The default is `--agent all`; select one or more with
+`--agent claude,codex` or repeated `--agent` flags. A global install supports
+the native Claude and Codex roots only.
+
+Existing `AGENTS.md`, `GEMINI.md`, and Copilot instructions are preserved. The
+installer appends a bounded odla-managed section, is idempotent, refuses
+symlink-redirection and locally changed managed content, and lets `--force`
+replace only odla-owned content. The local bundle includes build, migration,
+and observability-debug procedures plus every reference they need; agents do
+not need online docs or access to odla's private service source after setup.
+
+After running setup, the whole prompt can be: “Set up odla in this repo using
+the installed local odla runbook. Decide whether this is a new app or an
+existing site to migrate, then drive it end to end. Ask me only for the device
+approval and other human-only checkpoints.”
+
+For programmatic callers, `installSkill()` keeps `targetDir`, `written`, and
+`unchanged` as one unambiguous primary-root view: the latter two contain paths
+relative to `targetDir` only. Use the additive absolute `writtenPaths` and
+`unchangedPaths` fields to inspect every shared-bundle and adapter artifact.
 
 `doctor` also lints for common footguns: permission rules that are literally
 `"true"` (public writes always warn; a public `view` warns unless the
@@ -122,8 +194,8 @@ export default {
   platformUrl: process.env.ODLA_PLATFORM_URL ?? "https://odla.ai",
   dbEndpoint: process.env.ODLA_ENDPOINT ?? process.env.ODLA_DB_ENDPOINT ?? "https://db.odla.ai",
   app: { id: "my-app", name: "My App" },
-  envs: ["prod", "dev"],
-  services: ["db", "ai"],
+  envs: ["dev"], // add "prod" deliberately; provisioning it requires --yes
+  services: ["db", "ai", "o11y"],
   db: {
     schema: "./src/odla/schema.mjs",
     rules: "./src/odla/rules.mjs",
@@ -135,6 +207,8 @@ export default {
     keyEnv: "ANTHROPIC_API_KEY",
   },
   auth: {
+    // Publishable key (public). Created + pulled by the Clerk CLI (`npx clerk`);
+    // See the installed odla-migrate phase 3. Inline `pk_…` or "$ENV_VAR".
     clerk: {
       dev: "$CLERK_PUBLISHABLE_KEY",
       prod: "$CLERK_PUBLISHABLE_KEY",

package/REQUIREMENTS.md

@@ -13,6 +13,13 @@ Agnacl, but none should mention or special-case Agnacl.
   credentials.
 - The CLI must treat platform registry and odla-db as separate endpoints. They
   may be the same in some deployments, but generated configs must not imply it.
+- If a platform or credential change is deterministic from `odla.config.mjs`,
+  the CLI owns it. That includes service enablement, service-specific credential
+  issuance/persistence, local runtime values, and deployed Worker secret
+  transfer. `odla-ai capabilities --json` must expose this boundary to agents.
+- Source semantics remain with the coding agent: package installation, Worker
+  instrumentation, and application-specific signals/rules. Humans approve
+  identity, production mutation, and explicit destructive rotation.
 
 ## Human Approval
 
@@ -26,9 +33,17 @@ Agnacl, but none should mention or special-case Agnacl.
 
 ## Safe Provisioning
 
-- Re-runs must be idempotent: reuse existing app registration and local db keys.
-- Key rotation must be explicit (`--rotate-keys`).
-- Local runtime files (`.dev.vars`, local credentials) must be gitignored.
+- Re-runs must be idempotent: reuse existing app registration and local service
+  credentials. A missing local shown-once token must fail safely instead of
+  rotating a possibly live credential.
+- Credential rotation must be explicit: `--rotate-o11y-token` for only o11y or
+  `--rotate-keys` for the broader credential set.
+- `--push-secrets` must preflight Wrangler configuration and login before any
+  shown-once issuance or destructive rotation, then pipe values over stdin.
+- Local runtime files (`.dev.vars`, token cache, local credentials), including
+  configured custom in-repository paths, must be mode `0600` where applicable
+  and gitignored.
+- O11y-only projects must not create or require an odla-db key.
 - Schema pushes must be explicit and visible in dry-run.
 - If rules are omitted, schema-derived deny-all rules are the safe default.