@odla-ai/cli 0.11.2 → 0.13.0

package/README.md

@@ -8,13 +8,13 @@
 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 per-app BYOK AI, configure Clerk auth, record
-deployment links, connect read-only Google Calendar mirrors, provision o11y ingest credentials, and transfer local or
+deployment links, compose declared npm capability integrations, connect Google Calendar booking, provision o11y ingest credentials, and transfer local or
 deployed Worker secrets without printing them. It also gives platform admins a
 scoped System AI control surface and gives app owners a provider-key-free
 hosted security command.
 
 It does not know about any specific app. App identity, environments, services,
-schema, rules, auth, AI provider, and links all come from config.
+schema, rules, integrations, auth, AI provider, and links all come from config.
 
 ## Install
 
@@ -29,8 +29,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 view @odla-ai/cli@0.10.2 version
-npm i -D --save-exact @odla-ai/cli@0.10.2
+npm view @odla-ai/cli@0.13.0 version
+npm i -D --save-exact @odla-ai/cli@0.13.0
 ```
 
 ## Prerequisites
@@ -114,13 +114,20 @@ shown-once credential.
    including from scripted and agent-driven shells; only CI, SSH sessions, and
    display-less hosts skip the launch. Pass `--open` to force it anyway, or
    `--no-open` to suppress it. Browser launch is best-effort; the printed URL
-   and code always remain the fallback.
+   and code always remain the fallback and agents must relay that URL to the
+   human. The started handshake is persisted privately under `.odla/`, so a
+   run killed before approval loses nothing: rerunning resumes the same code.
+   Outside an interactive terminal the approval wait is capped (90 seconds by
+   default; `--wait <seconds>` overrides), and a still-pending handshake exits
+   with code 75 — approve at the URL, then re-run to collect the token.
 2. Creates the platform app if needed.
 3. Enables configured services in every configured environment. Calendar
    config is normalized per env and fixed to Google read-only access.
 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.
+5. Collision-checks and merges declared integration schema/rule fragments,
+   pushes the composed database contract, and creates integration seeds only
+   when their natural-key rows are absent.
 6. Configures platform AI and stores provider keys in the tenant vault when the
    configured key env var is set.
 7. For calendar, reads owner-visible connection status and, when needed, asks
@@ -146,6 +153,39 @@ 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.
 
+### Application capability integrations
+
+An integration is an npm capability composed into an app, not a hosted
+platform service. Put data-only descriptors under `integrations` in
+`odla.config.mjs`; do not add their ids to `services`.
+
+```js
+import { createCrmIntegration } from "@odla-ai/crm";
+import { crm } from "./src/crm.js";
+
+export default {
+  app: { id: "my-app", name: "My App" },
+  services: ["db"],
+  integrations: [createCrmIntegration(crm, { basePath: "/api/crm" })],
+  links: { dev: "https://dev.example.com" },
+};
+```
+
+Descriptors are consumed structurally, so capability packages do not depend
+on the CLI. `provision --dry-run` names every integration and its namespace,
+seed, and probe counts. Provision accepts an app-authored namespace/rule that
+is byte-for-byte structurally identical to an integration fragment, which
+makes existing manually merged apps migratable; conflicting definitions fail
+before credentials or network mutations. A guarded seed requires a
+declared-unique natural key, is queried first, and is created only when absent.
+A concurrent create fails uniqueness instead of overwriting runtime owner edits.
+
+`doctor` remains offline: it checks the composed schema, complete rule coverage,
+and seed targets. `smoke` remains read-only: after the normal db checks it runs
+each descriptor's anonymous route probe against `links.<env>`. Installing the
+package, mounting its routes in the Worker, and supplying app authorization are
+source-code responsibilities for the agent/developer.
+
 ### Device-grant security and recovery
 
 The account email sent during a fresh handshake is a non-secret identity hint,
@@ -168,8 +208,9 @@ when compromise or accidental approval is possible.
 
 `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
+odla-db schema with the tenant key, compares the fully composed schema entities,
+runs a count aggregate against the first entity, and executes declared
+integration route probes without credentials. It fails early with a clear message
 when provisioning has not written `.odla/credentials.local.json`.
 
 ### Read-only Google Calendar

package/REQUIREMENTS.md

@@ -6,7 +6,8 @@ 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,
+  app id/name, envs, platform URL, db endpoint, services, app-capability
+  integrations, 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
@@ -14,7 +15,8 @@ Agnacl, but none should mention or special-case Agnacl.
 - 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
+  the CLI owns it. That includes service enablement, integration schema/rule
+  composition and guarded seeds, 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
@@ -76,6 +78,11 @@ Agnacl, but none should mention or special-case Agnacl.
   credential in browser code.
 - Schema pushes must be explicit and visible in dry-run.
 - If rules are omitted, schema-derived deny-all rules are the safe default.
+- App-capability descriptors are structural config data, not hosted services:
+  merge their schema/rules with collision checks, accept identical pre-merged
+  definitions, require declared-unique natural keys, and create seeds only
+  when absent so owner edits survive every rerun and concurrent creates fail
+  instead of overwriting them.
 
 ## App Scaffolding Gaps
 
@@ -85,7 +92,8 @@ Agnacl, but none should mention or special-case Agnacl.
   `@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
+  public-config fetch, composed db schema presence, a simple db aggregate/query,
+  anonymous integration route probes against the configured deployment link, 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.