@odla-ai/cli 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @odla-ai/cli
+
+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.
+
+It does not know about any specific app. App identity, environments, services,
+schema, rules, auth, AI provider, and links all come from config.
+
+## Install
+
+No install needed — the package ships a single `odla-ai` binary, so npx can run
+it directly:
+
+```bash
+npx @odla-ai/cli init --app-id my-app --name "My App"
+```
+
+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
+```
+
+## Prerequisites
+
+- Node.js 20 or newer (`node --version`).
+- odla apps usually deploy as Cloudflare Workers. If you have never used
+  Cloudflare:
+  1. Create a free account at <https://dash.cloudflare.com/sign-up>.
+  2. You do not need to install anything: `npx wrangler login` opens the
+     browser once to link your account, `npx wrangler dev` runs a Worker
+     locally, and `npx wrangler deploy` ships it.
+  3. The `.dev.vars` file this CLI writes with `provision --write-dev-vars` is
+     wrangler's local secrets file — `wrangler dev` picks it up automatically.
+     It is chmod `0600` and gitignored; never commit it or paste its contents
+     into `wrangler.toml`.
+
+## Commands
+
+```bash
+npx odla-ai init --app-id my-app --name "My App"
+npx odla-ai doctor
+npx odla-ai provision --dry-run
+npx odla-ai provision --write-dev-vars
+npx odla-ai smoke --env dev
+npx odla-ai version
+```
+
+`init` writes:
+
+- `odla.config.mjs`
+- `src/odla/schema.mjs`
+- `src/odla/rules.mjs`
+- `.gitignore` entries for local credentials
+
+`provision` performs the standard safe setup flow:
+
+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
+   the code is displayed. Pass `--open` to force browser launch from a
+   non-interactive shell, or `--no-open` to suppress it. Browser launch is
+   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.
+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.
+
+`smoke` verifies a provisioned environment from local credentials. It fetches
+the platform public config, checks the configured AI provider, fetches the live
+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`.
+
+## Config
+
+```js
+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"],
+  db: {
+    schema: "./src/odla/schema.mjs",
+    rules: "./src/odla/rules.mjs",
+    defaultRules: "deny",
+  },
+  ai: {
+    provider: process.env.ODLA_AI_PROVIDER ?? "anthropic",
+    keyEnv: "ANTHROPIC_API_KEY",
+  },
+  auth: {
+    clerk: {
+      dev: "$CLERK_PUBLISHABLE_KEY",
+      prod: "$CLERK_PUBLISHABLE_KEY",
+    },
+  },
+  links: {
+    dev: "https://dev.example.com",
+    prod: "https://example.com",
+  },
+};
+```
+
+`db.schema` and `db.rules` may be inline objects, JSON files, or JS modules
+exporting `default`, `schema` / `SCHEMA`, or `rules` / `RULES`.
+
+If schema is present and rules are omitted, `defaultRules: "deny"` generates
+deny-all rules for every schema entity. That is the safe default for Workers
+that mediate reads and writes with an app key.

package/REQUIREMENTS.md

@@ -0,0 +1,55 @@
+# CLI Requirements From the Agnacl Rebuild
+
+These are requirements for a generic odla-ai npm CLI. They came from rebuilding
+Agnacl, but none should mention or special-case Agnacl.
+
+## Core Contract
+
+- A project must declare intent in a checked-in config file:
+  app id/name, envs, platform URL, db endpoint, services, schema, rules, auth,
+  AI provider/model, deployment links, and local credential paths.
+- The CLI must validate that contract without network calls.
+- The CLI must show a dry-run plan before creating platform state or writing
+  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.
+
+## Human Approval
+
+- Provisioning must default to device-handshake auth, never a platform admin
+  secret in chat or config.
+- The approval code must be printed in a copyable URL.
+- Interactive provisioning should launch the browser to the approval page when
+  possible. `--open` should force launch; `--no-open` should suppress it.
+- Cached developer tokens must be mode `0600`, gitignored, and reused until
+  expiry.
+
+## 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.
+- Schema pushes must be explicit and visible in dry-run.
+- If rules are omitted, schema-derived deny-all rules are the safe default.
+
+## App Scaffolding Gaps
+
+- A future `scaffold worker --kg` command should create the generic runtime
+  wiring now hand-written in this rebuild:
+  `getEnv`, platform public-config fetch, Clerk JWT verification,
+  `@odla-ai/db` initialization, `@odla-ai/ai initFromPlatform`, and
+  `@odla-ai/kg writeFragment` seed/ingest helpers.
+- `smoke` should verify:
+  public-config fetch, db schema presence, a simple db aggregate/query, and AI
+  config resolution. Tenant-vault key availability is still a follow-up because
+  checking it requires knowing the provider secret name and deliberately
+  touching the secret read path.
+- A future `inspect` command should scan an existing app and report likely auth,
+  DB, AI, and graph surfaces before migration.
+
+## LLM Ergonomics
+
+- Every command must produce machine-readable enough output for an LLM to decide
+  the next action from stdout alone.
+- Failures should name the exact config key or external capability missing.
+- The package must ship `llms.txt` so agents can use it without reading source.