@odla-ai/cli 0.12.0 → 0.13.1

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
@@ -125,7 +125,9 @@ shown-once credential.
    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
@@ -151,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,
@@ -173,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.