@odla-ai/cli 0.8.0 → 0.10.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.8.0",
-  "description": "Agent-operable CLI for odla provisioning, System AI administration, commit-pinned GitHub security jobs, Worker secrets, and smoke checks.",
+  "version": "0.10.0",
+  "description": "Agent-operable CLI for odla provisioning, calendar consent and sync lifecycle, System AI administration, Worker secrets, security jobs, and smoke checks.",
   "license": "MIT",
   "homepage": "https://odla.ai/docs/packages/cli",
   "repository": {
@@ -60,7 +60,7 @@
   },
   "dependencies": {
     "@odla-ai/ai": "^0.3.3",
-    "@odla-ai/apps": "^0.7.1",
+    "@odla-ai/apps": "^0.8.0",
     "@odla-ai/db": "^0.6.2",
     "@odla-ai/security": "^0.2.2"
   },

package/skills/odla/SKILL.md

@@ -2,7 +2,7 @@
 name: odla
 description: >
   Build a new app on odla — a realtime database (odla-db) plus AI, Clerk auth,
-  and observability on Cloudflare, provisioned by @odla-ai/cli. Use when the user
+  read-only Google Calendar mirrors, and observability on Cloudflare, provisioned by @odla-ai/cli. Use when the user
   wants to create/scaffold an odla app, add odla-db/ai/auth/o11y to a repo, or
   "get started with odla". For moving an existing static or GitHub Pages site to
   odla, use the odla-migrate skill instead.
@@ -15,7 +15,7 @@ runbookOrder:
 
 You drive setup and building on **odla** — an agent-operable app platform on
 Cloudflare: a realtime graph database (**odla-db**), multi-provider **AI**,
-**Clerk** auth, and OpenTelemetry **observability**, all provisioned by the
+**Clerk** auth, read-only **Google Calendar** mirrors, and OpenTelemetry **observability**, all provisioned by the
 `@odla-ai/cli`. The human approves a couple of browser-only checkpoints; you do
 everything else.
 
@@ -48,6 +48,9 @@ State which path you're taking and what you'll build in one line; get a nod.
 4. Never `git add -A` without reading `git status` first. Never run
    `provision --rotate-keys` or `provision --rotate-o11y-token` unless the human
    explicitly asks.
+5. Google OAuth is a distinct human checkpoint. Never request, paste, print, or
+   store a Google authorization code/refresh token. Open only the state-bound
+   platform/Google consent URL returned by odla; calendar actions remain unavailable in the read-only slice.
 
 ## The flow
 
@@ -67,7 +70,9 @@ guessing which platform/credential steps need manual work. Then:
    prints; the human approves it at https://odla.ai/studio. It creates the app,
    enables services, issues or reuses configured credentials (db key + o11y
    ingest token when enabled), pushes schema + rules, writes `.dev.vars`, and
-   transfers Worker secrets through Wrangler stdin.
+   transfers Worker secrets through Wrangler stdin. With calendar enabled it
+   then prints a second, server-issued Google URL; the human grants read-only consent
+   and the CLI follows initial sync.
 4. **run** — `npx wrangler dev` (auto-loads `.dev.vars`); verify locally.
 5. **security** — run the passive `@odla-ai/security` odla profile; inspect
    every lead and keep critical candidate gating enabled. If the human approves
@@ -88,6 +93,10 @@ guessing which platform/credential steps need manual work. Then:
 
 `npx @odla-ai/cli doctor` is an offline config check anytime;
 `npx @odla-ai/cli smoke --env dev` verifies a live deployment.
+Use `calendar status --json` for safe connection/sync state and `calendar
+calendars --json` to discover ids after consent; update checked-in config and
+re-provision. Resync production only with `--yes`; disconnect always requires
+`--yes` and leaves retained rows potentially stale.
 
 The CLI owns deterministic platform work from `odla.config.mjs`: service
 enablement, credential issuance/storage, `.dev.vars`, and Wrangler secret

package/skills/odla/references/build.md

@@ -15,6 +15,13 @@ deny-all rules from the schema. To turn on auth/observability, add `"o11y"` to
 `services` and an `auth.clerk` block in `odla.config.mjs` (init leaves it
 commented).
 
+For a Google booking mirror, include both `"db"` and `"calendar"`. Configure
+`calendar.google.calendars` for every env (start with `"primary"`), optional
+match filters, and `attendeePolicy: "full" | "hashed"`. This release is
+read-only; do not add OAuth credentials or action scopes to config.
+For static Appointment Schedule parity, add the public per-env
+`bookingPageUrl`; it is link/embed configuration, never a credential.
+
 ## 2. Build the Worker shell
 
 `npm i` only the SDKs you need and use the local `references/sdks.md` as the
@@ -43,6 +50,13 @@ Local credential files are `0600` and gitignored. Verify with
 anything unset. `--push-secrets` preflights the Wrangler config and login before
 issuing or rotating a shown-once credential.
 
+Calendar adds a second ⏸ checkpoint after the odla device approval: provision
+prints/opens a state-bound Google URL issued by the platform and waits while the human grants
+`calendar.events.readonly` and the hosted connector performs initial sync. The
+CLI never receives the Google callback code or tokens. Once connected, run
+`npx @odla-ai/cli calendar calendars --env dev --json`, refine the checked-in
+calendar ids if needed, re-provision, and verify `calendar status --json`.
+
 The CLI stops at the source boundary: it verifies but does not invent your
 application semantics. Do not use Studio to mint a routine o11y token. Manual
 Studio rotation is recovery-only;
@@ -61,6 +75,11 @@ means the namespace has no rule yet — add one in `src/odla/rules.mjs`
 (deliberately; e.g. `{ notes: { view: "auth.signedIn", create: "auth.signedIn" } }`),
 re-provision to push it, and retry.
 
+Calendar uses the same `ODLA_ENDPOINT`, `ODLA_TENANT`, and server-only
+`ODLA_API_KEY`; it adds no Worker secret. Keep `initCalendar` in trusted Worker
+code. Browser code uses db subscriptions under explicit rules or pure
+`@odla-ai/calendar/client` helpers, never the admin key.
+
 ## 5. Security preflight
 
 Install the passive harness and scan before any production secret or deploy:

package/skills/odla/references/sdks.md

@@ -31,6 +31,35 @@ Worker/admin side: `init({ appId: tenantId, adminToken: env.ODLA_API_KEY, endpoi
 The publishable key is public; `provision` stores it (`setAuth`). Rules evaluate
 the signed-in user's JWT as `auth` — e.g. `auth.signedIn`, `auth.email`.
 
+## @odla-ai/calendar — read-only Google booking mirror
+
+Calendar requires `services: ["db", "calendar"]` plus a `calendar.google`
+block. Normal provision opens a second, state-bound Google checkpoint issued by the platform for the
+human to grant `calendar.events.readonly`; Google tokens stay in the hosted
+connector and never become app/CLI secrets.
+
+```ts
+// Trusted Worker only — the admin key must never enter browser code.
+const calendar = initCalendar({
+  appId: env.ODLA_TENANT,
+  adminToken: env.ODLA_API_KEY,
+  endpoint: env.ODLA_ENDPOINT,
+});
+const next = await calendar.bookings.next("member@example.com");
+```
+
+Browser code may query `$bookings` with `@odla-ai/db/client` only under an
+explicit view rule, and may import pure formatting helpers from
+`@odla-ai/calendar/client`. Do not import `initCalendar` or expose
+`ODLA_API_KEY` in a browser. Provider actions are not part of the read-only
+slice; a `calendar_not_connected`/501 action response is not a reason to widen
+credentials or request a Google token.
+
+After consent, use `odla-ai calendar calendars --env dev --json` to discover
+selectable ids, edit the checked-in list, and optionally set a public per-env
+`bookingPageUrl` for Appointment Schedule embed/link mode. Re-provision, then verify with
+`calendar status --json` and `smoke`.
+
 ## @odla-ai/ai — inference (Claude / GPT / Gemini)
 
 ```ts

package/skills/odla-migrate/SKILL.md

@@ -2,13 +2,14 @@
 name: odla-migrate
 description: >
   Migrate a static site (e.g. GitHub Pages) to odla on Cloudflare in safe
-  phases, then add a database, Clerk login, and AI. Use when the user wants to
+  phases, then add a database, optional read-only calendar mirror, Clerk login, and AI. Use when the user wants to
   move a static or GitHub Pages site to Cloudflare/odla, or to add a backend,
   database, login/auth, or AI features to a static site via odla.
 runbookOrder:
   - references/phase-0-preflight.md
   - references/phase-1-static.md
   - references/phase-2-db.md
+  - references/phase-2b-calendar.md
   - references/phase-3-auth.md
   - references/phase-3b-user-sync.md
   - references/phase-4-ai.md
@@ -45,12 +46,16 @@ installed skill at `../odla/SKILL.md` instead.
    approved o11y rotation with `--push-secrets` so the Worker is updated in the
    same run. If the final Wrangler transfer fails, use the CLI's printed
    non-rotating `secrets push` retry; never rotate again just to retry delivery.
+7. Existing calendar embeds are public links, not proof of a booking. Preserve
+   them via `bookingPageUrl`; never claim reconciliation until the read-only
+   mirror is connected and the app correlates `$bookings` deliberately. Google
+   OAuth tokens never enter the repo, CLI, or chat.
 
 ## Phase state machine
 
 Phases run strictly in order; each has a verification gate:
 
-  P0 preflight -> P1 static-on-cloudflare -> P2 database -> P3 login
+  P0 preflight -> P1 static-on-cloudflare -> P2 database -> P2b calendar (optional) -> P3 login
   -> P4 ai (optional) -> P5 prod + DNS cutover
 
 `MIGRATION.md` at the user's repo root is the durable state: create it in
@@ -100,6 +105,7 @@ Read the current phase's file when you enter it — not before:
 - references/phase-0-preflight.md
 - references/phase-1-static.md
 - references/phase-2-db.md
+- references/phase-2b-calendar.md (optional: preserve an embed and add authoritative read-only reconciliation)
 - references/phase-3-auth.md
 - references/phase-3b-user-sync.md (optional: mirror Clerk users into $users)
 - references/phase-4-ai.md

package/skills/odla-migrate/references/phase-2-db.md

@@ -10,8 +10,8 @@ in the browser in interactive terminals).
 
 ## Steps
 
-1. Require `npm view @odla-ai/cli@0.8.0 version` to succeed, then run
-   `npm i -D --save-exact @odla-ai/cli@0.8.0` and `npm i @odla-ai/db`.
+1. Require `npm view @odla-ai/cli@0.10.0 version` to succeed, then run
+   `npm i -D --save-exact @odla-ai/cli@0.10.0` and `npm i @odla-ai/db`.
 2. `npx @odla-ai/cli init --app-id <id> --name "<Name>" --env dev --services db`
    Review `odla.config.mjs`. Keep `envs: ["dev"]` — prod is Phase 5. Set
    `links.dev` to the URL the Phase 1 `wrangler deploy` **actually printed** —

package/skills/odla-migrate/references/phase-2b-calendar.md

@@ -0,0 +1,42 @@
+# Phase 2b — Google Calendar (optional, read-only)
+
+Use this phase only when the existing site has a Google Appointment Schedule
+link/embed or locally reported meeting state. Keep the old booking experience
+working while adding an authoritative read-only mirror.
+
+Human obligations: review attendee-data retention and complete the second,
+server-issued Google consent page. They never paste an OAuth code or token.
+
+1. Inventory the old behavior. Distinguish a public appointment-page link from
+   actual event create/reschedule/cancel APIs. Do not promise more than exists.
+2. Require `npm view @odla-ai/calendar@0.1.0 version` to succeed, then install
+   `npm i --save-exact @odla-ai/calendar@0.1.0` as a runtime dependency. An
+   exact-version `E404` blocks this phase; do not substitute a git checkout or
+   another version. Add `"calendar"` beside
+   `"db"` in services and configure:
+   - `calendar.google.calendars.dev` (start with `"primary"`);
+   - optional summary/organizer/attendee match filters;
+   - deliberate `attendeePolicy: "full" | "hashed"`;
+   - the old public Appointment Schedule URL as `bookingPageUrl.dev` when
+     preserving the embed/link. It is public configuration, not a secret.
+3. Run `doctor`, then `provision --dry-run`. Show the human the calendars,
+   attendee policy, public booking page, and read-only scope.
+4. Run normal dev provision. After odla device approval, pause again while the
+   human grants Google `calendar.events.readonly`; the CLI follows initial sync.
+5. Run `calendar calendars --env dev --json`, refine the checked-in ids, and
+   re-provision. Verify `calendar status --env dev --json` and `smoke --env dev`.
+6. Put `initCalendar` only in trusted Worker code. Browser code may keep using
+   the public `bookingPageUrl`, query `$bookings` through explicit db rules, or
+   import pure helpers from `@odla-ai/calendar/client`. Never expose
+   `ODLA_API_KEY`.
+7. Replace self-reported meeting state only after an explicit, tested
+   application-to-booking correlation exists. A matching attendee email may be
+   sufficient for some apps; do not silently regress later workflow statuses.
+
+This slice cannot create, reschedule, or cancel Google events. A static picker
+continues to be Google's sealed UI; odla supplies configuration, mirror reads,
+and reconciliation.
+
+Gate: the old embed/link still works, status is healthy, the selected calendars
+match config, `$bookings` smoke succeeds, no Google credential exists in local
+files, and `MIGRATION.md` records the disclosure/correlation decision.

package/skills/odla-migrate/references/phase-3b-user-sync.md

@@ -8,9 +8,10 @@ build the mirror yourself — the platform does it. This phase enables it.
 Goal: signed-in users appear as rows in the app's `$users`, kept in sync with
 Clerk (create/update/delete). Dev first, then prod.
 
-Human obligation: create a Clerk webhook endpoint and paste its signing secret
-(`whsec_…`) into Studio (write-only). That plus the Phase-3 `clerk auth login`
-are the only human Clerk steps.
+Human obligation: create a Clerk webhook endpoint and get its signing secret
+(`whsec_…`) into the tenant vault — piped through `secrets set` when a command
+can print it, or pasted into Studio (both write-only). That plus the Phase-3
+`clerk auth login` are the only human Clerk steps.
 
 ## How `$users` fills — two paths
 
@@ -37,12 +38,18 @@ Enable it here.
    Clerk dashboard → Webhooks → Add Endpoint. (`whsec_` is a real secret — never
    print/commit it; it is the only thing you paste, and it goes into the vault,
    not chat.)
-2. **Store the secret in the tenant vault** as `clerk_webhook_secret`, write-only,
-   via Studio's secret UI (`odla.ai/studio` → the app → the env → secrets). The server
-   decrypts it only to verify inbound events (svix HMAC over `id.timestamp.body`).
+2. **Store the secret in the tenant vault** as `clerk_webhook_secret`, write-only.
+   If any command can print the `whsec_` (Clerk CLI, Svix API), pipe it without
+   it ever being displayed:
+   `<command that prints whsec_…> | npx @odla-ai/cli secrets set clerk_webhook_secret --env dev --stdin`.
+   Otherwise a human pastes it into Studio's secret UI (`odla.ai/studio` → the
+   app → the env → secrets) — same write-only slot. The server decrypts it only
+   to verify inbound events (svix HMAC over `id.timestamp.body`).
 3. **(Optional) `sk_…`** — the webhook payload already carries email/name/image,
-   so the basic mirror needs only `whsec_`. Add the Clerk backend key `sk_…` to
-   the vault only if you later need to resolve data the webhook doesn't send.
+   so the basic mirror needs only `whsec_`. Add the Clerk backend key only if
+   you later need to resolve data the webhook doesn't send (invites, member
+   lookups): `npx @odla-ai/cli secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY`
+   stores it in the reserved `$clerk_secret` slot, write-only.
 
 ## Verify
 

package/skills/odla-migrate/references/secrets-map.md

@@ -5,8 +5,8 @@
 | Value | Lives in | Handling |
 |---|---|---|
 | Clerk publishable key (`pk_test_`/`pk_live_`) | registry, via provision → setAuth | public by design; the one value a human may paste into chat; fine inline in odla.config.mjs |
-| Clerk webhook secret (`whsec_…`) | tenant vault (`clerk_webhook_secret`) | only for auth mode "full"; entered in Studio, never wrangler, never chat |
-| Clerk secret key (`sk_test_`/`sk_live_`) | not used in this journey | never ask for it |
+| Clerk webhook secret (`whsec_…`) | tenant vault (`clerk_webhook_secret`) | only for auth mode "full"; piped with `secrets set clerk_webhook_secret --env <env> --stdin`, or entered in Studio; never wrangler, never chat |
+| Clerk secret key (`sk_test_`/`sk_live_`) | not needed for this journey | if a later feature needs user resolution/invites, pipe it with `secrets set-clerk-key --env <env>` (reserved `$clerk_secret`, write-only); never chat |
 | LLM provider key | tenant vault | env var in the HUMAN's shell for one provision run; never wrangler vars, never git, never chat |
 | `odla_sk_…` (tenant db key) | wrangler secret `ODLA_API_KEY` + `.odla/credentials.local.json` (0600) + `.dev.vars` | present when db is enabled; move it only with the pipeline below |
 | `odla_dev_…` (developer token) | `.odla/dev-token.json` (0600) | ~24h lifetime, provision-time only; never deployed |
@@ -42,6 +42,20 @@ Manual fallback (identical mechanics, if the CLI is unavailable):
 (For prod, use `c.envs.prod.dbKey` and drop `--env` — the top-level
 wrangler env is prod.)
 
+## Moving a tenant-vault secret (never through the transcript)
+
+`secrets set` fills the same write-only vault slot as Studio's Secrets panel,
+reading the value only from stdin or a named env var — never argv — so a
+producer command pipes straight into the vault:
+
+    <command that prints the value> | npx @odla-ai/cli secrets set clerk_webhook_secret --env dev --stdin
+    npx @odla-ai/cli secrets set-clerk-key --env dev --from-env CLERK_SECRET_KEY
+
+The value cannot be read back by the CLI, Studio, or the developer token —
+only by that tenant's app API key (reserved `$` secrets not even then). Studio
+remains the fallback when no producer command exists (a human copies from the
+Clerk dashboard between two browser tabs). Prod-named envs require `--yes`.
+
 ## Standing rules
 
 - Never `cat`, `head`, `grep -v`, or otherwise display `.dev.vars`,