@odla-ai/cli 0.8.0 → 0.10.0

package/README.md

@@ -8,7 +8,7 @@
 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, provision o11y ingest credentials, and transfer local or
+deployment links, connect read-only Google Calendar mirrors, 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.
@@ -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.8.0 version
-npm i -D --save-exact @odla-ai/cli@0.8.0
+npm view @odla-ai/cli@0.10.0 version
+npm i -D --save-exact @odla-ai/cli@0.10.0
 ```
 
 ## Prerequisites
@@ -53,12 +53,19 @@ npm i -D --save-exact @odla-ai/cli@0.8.0
 npx odla-ai setup
 npx odla-ai init --app-id my-app --name "My App"
 npx odla-ai doctor
+npx odla-ai calendar status --env dev
+npx odla-ai calendar calendars --env dev
+npx odla-ai calendar connect --env dev
+npx odla-ai calendar resync --env dev
+npx odla-ai calendar disconnect --env dev --yes
 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 --push-secrets
 npx odla-ai smoke --env dev
 npx odla-ai secrets push --env dev
+npx odla-ai secrets set clerk_webhook_secret --env dev --stdin
+npx odla-ai secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY
 npx odla-ai security run . --env dev --ack-redacted-source
 npx odla-ai security github connect --env dev # infers owner/name from git origin
 npx odla-ai security plan --env dev
@@ -101,14 +108,20 @@ shown-once credential.
    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.
+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.
 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`.
-8. With `--write-dev-vars`, writes the local Worker values to `.dev.vars`; with
+7. For calendar, reads owner-visible connection status and, when needed, asks
+   the platform for a state-bound Google authorization URL and opens only the
+   exact Google OAuth endpoint (or a same-platform interstitial). The human completes consent there;
+   provision follows the exact attempt through initial sync. OAuth codes and
+   refresh tokens never enter the CLI, repo, chat, or app.
+8. Writes `.odla/credentials.local.json` with mode `0600`.
+9. 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.
 
@@ -131,6 +144,48 @@ 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`.
 
+### Read-only Google Calendar
+
+Calendar is a platform-custodied connector, not a Google credential stored by
+the application. Enable both `db` and `calendar`, configure calendar ids per
+environment, then run normal provision. The first run has two distinct human
+checkpoints: the odla device code establishes app-owner authority, and the
+subsequent server-issued Google page grants `calendar.events.readonly` consent.
+
+For parity with a static Google Appointment Schedule embed/link, set the public
+`bookingPageUrl` per environment. Provision applies it through the owner-only
+calendar settings route; it is public configuration, not a credential.
+
+`calendar status` returns the safe connection/sync projection; add `--json` for
+agent automation. Once connected, `calendar calendars` lists ids visible to the
+Google identity so the checked-in selection can be refined. `calendar connect`
+applies the checked-in booking-page setting and starts consent when the
+connection is absent, failed, disconnected, or degraded (so an agent can
+repair revoked credentials); a healthy connection is reused. A `needs_sync`
+connection already has provider credentials, so connect/provision resyncs it
+without requesting Google consent again; an existing authorization or initial
+sync is awaited instead of creating a duplicate attempt.
+`calendar resync` asks the hosted connector to sync immediately; `calendar
+disconnect --yes` stops watches and deletes this app/environment connection's
+encrypted platform token and cursors without purging retained mirror rows,
+which may therefore remain readable but stale. It does not revoke the shared
+user-to-Google-OAuth-project grant, because that could invalidate other odla
+connections for the same user. A future explicitly global revoke command would
+need cross-connection accounting and warning. Production resync requires
+`--yes`, as does a direct production connect. None of these commands accepts a
+Google authorization code, client secret, access token, or refresh token.
+
+The SDK uses the existing server-side db values (`ODLA_ENDPOINT`,
+`ODLA_TENANT`, `ODLA_API_KEY`), so calendar adds no Worker secret. Never expose
+`ODLA_API_KEY` to a browser. Trusted Worker code can initialize
+`@odla-ai/calendar`; browser code reads `$bookings` through `@odla-ai/db/client`
+under explicit rules or imports pure helpers from `@odla-ai/calendar/client`.
+
+These commands operate the current read/embed reconciliation slice. The CLI has
+no native slot-picker or create/reschedule/cancel command, and exposes no
+rolling-window/age-out, quota-backoff, retention/purge, or provider-derived
+mutation-id control. Public health remains aggregate rather than per calendar.
+
 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.2.2`, then
@@ -261,11 +316,28 @@ 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.
 
+`secrets set <name> --env <env>` stores one named secret in that env's tenant
+vault — the same write-only slot Studio's Secrets panel fills (for example
+`clerk_webhook_secret` for synced auth). The value may come only from
+`--from-env <NAME>` or `--stdin`, so a producer command pipes straight into the
+vault without the secret ever appearing on argv, in output, or in an agent's
+transcript; it is encrypted at rest and readable back only by that tenant's
+app API key, never by the CLI, Studio, or the developer token. `$`-prefixed
+names are platform-reserved. `secrets set-clerk-key --env <env>` stores the
+app's Clerk secret key in the reserved `$clerk_secret` slot so the platform can
+resolve the app's users (invites, member lookups); reserved secrets are never
+readable by app keys. It refuses an `sk_test_` key for a prod-named env and
+requires `--yes` to put an `sk_live_` key into a non-prod env, since live users
+would sync into a non-prod tenant. Both commands authenticate with the
+developer token (`$ODLA_DEV_TOKEN`, the cached token, or a fresh device
+approval), and prod-named envs require `--yes`, matching `secrets push`.
+
 ## 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
+schema/rules/auth/AI/calendar configuration, owner-safe consent orchestration,
+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
@@ -317,7 +389,7 @@ export default {
   dbEndpoint: process.env.ODLA_ENDPOINT ?? process.env.ODLA_DB_ENDPOINT ?? "https://db.odla.ai",
   app: { id: "my-app", name: "My App" },
   envs: ["dev"], // add "prod" deliberately; provisioning it requires --yes
-  services: ["db", "ai", "o11y"],
+  services: ["db", "ai", "o11y", "calendar"],
   db: {
     schema: "./src/odla/schema.mjs",
     rules: "./src/odla/rules.mjs",
@@ -328,6 +400,21 @@ export default {
     provider: process.env.ODLA_AI_PROVIDER ?? "anthropic",
     keyEnv: "ANTHROPIC_API_KEY",
   },
+  calendar: {
+    google: {
+      calendars: { dev: ["primary"] },
+      bookingPageUrl: {
+        dev: "https://calendar.google.com/calendar/appointments/schedules/…",
+      },
+      match: {
+        summaryPrefix: "Intro", // optional
+        organizerSelf: true,    // default true
+        requireAttendees: true, // default true
+      },
+      attendeePolicy: "full", // or "hashed"
+      // This CLI release always requests calendar.events.readonly.
+    },
+  },
   auth: {
     // Publishable key (public). Created + pulled by the Clerk CLI (`npx clerk`);
     // See the installed odla-migrate phase 3. Inline `pk_…` or "$ENV_VAR".

package/REQUIREMENTS.md

@@ -44,6 +44,20 @@ Agnacl, but none should mention or special-case Agnacl.
   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.
+- Calendar projects must require db, apply one normalized config per env, and
+  use the existing db app key rather than introducing an application-held
+  Google credential.
+- Google consent must be a separate, state-bound platform checkpoint. The CLI may
+  print/open and poll an opaque attempt, but must never receive an OAuth code,
+  access token, or refresh token.
+- Read-only calendar intent must request only
+  `calendar.events.readonly`; scope elevation belongs in a later explicit flow.
+- Calendar connect/status/discovery/resync/disconnect must be resumable and
+  machine-readable. Disconnect must be explicit and disclose that retained
+  mirror rows can remain stale.
+- A public per-env `bookingPageUrl` must be validated and applied independently
+  of connector config so static Appointment Schedule embeds need no Google/app
+  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.