@odla-ai/cli 0.9.0 → 0.10.1

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,13 +29,17 @@ 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.9.0 version
-npm i -D --save-exact @odla-ai/cli@0.9.0
+npm view @odla-ai/cli@0.10.1 version
+npm i -D --save-exact @odla-ai/cli@0.10.1
 ```
 
 ## Prerequisites
 
 - Node.js 20 or newer (`node --version`).
+- An existing odla account that has signed in at least once. For any command
+  that may need a fresh device grant, pass `--email <account>` or set
+  `ODLA_USER_EMAIL`. This value identifies who may review the request; it is not
+  a password or session credential, and an agent must never ask for either.
 - 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>.
@@ -53,10 +57,15 @@ npm i -D --save-exact @odla-ai/cli@0.9.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 provision --email owner@example.com --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
@@ -68,7 +77,7 @@ npx odla-ai security sources --env dev
 npx odla-ai security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
 npx odla-ai security status <job-id>
 npx odla-ai security report <job-id>
-npx odla-ai admin ai show
+npx odla-ai admin ai show --email owner@example.com
 npx odla-ai admin ai models
 npx odla-ai admin ai set security --discovery-provider anthropic --discovery-model claude-opus-4-8 --validation-provider openai --validation-model gpt-5.5 --enabled
 npx odla-ai admin ai credentials
@@ -96,21 +105,30 @@ When using `--push-secrets`, create the Worker and its Wrangler config first.
 The CLI checks that config and `wrangler whoami` before it issues or rotates a
 shown-once credential.
 
-1. Gets an `odla_dev_...` token by device handshake, or reuses
-   `ODLA_DEV_TOKEN` / `.odla/dev-token.json`.
+1. Gets an `odla_dev_...` token by email-bound device handshake, or reuses
+   `ODLA_DEV_TOKEN` / `.odla/dev-token.json`. A fresh handshake requires
+   `--email <account>` or `ODLA_USER_EMAIL`; the matching existing account must
+   sign in, review the exact code, and approve it. Opening the URL alone does
+   not claim the request.
    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.
+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.
 
@@ -127,12 +145,74 @@ 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.
 
+### Device-grant security and recovery
+
+The account email sent during a fresh handshake is a non-secret identity hint,
+not proof of identity. Unknown or never-signed-in accounts never produce a
+claimable Studio request, and the public start/poll shape intentionally does not
+reveal whether an account exists. The signed-in matching user must explicitly
+review the exact code before it becomes pending, and only one claimed pending
+or approved-but-uncollected request can be active for that user.
+
+Developer grants are tracked by id, owner, label, scopes, creation/expiry,
+last use, and revocation state. The plaintext token is delivered once to the
+polling client and is never available from the inventory. Every signed-in user
+can inspect and revoke their own grants under **Your agent credentials** in
+Studio; platform admins additionally see the global token inventory and
+metadata-only attempt evidence. Future requests with a revoked token fail.
+Deleting
+`.odla/dev-token.json` or `.odla/admin-token.local.json` removes the local copy
+but does not revoke a token already copied elsewhere, so use Studio revocation
+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
 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
@@ -283,7 +363,8 @@ approval), and prod-named envs require `--yes`, matching `secrets push`.
 
 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
@@ -335,7 +416,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",
@@ -346,6 +427,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

@@ -25,11 +25,27 @@ Agnacl, but none should mention or special-case Agnacl.
 
 - 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.
+- A fresh handshake must require the existing account email via `--email` or
+  `ODLA_USER_EMAIL`. Email is an identity hint, never a password or bearer
+  credential; agents must not request either from the human.
+- Unknown and never-signed-in accounts must not yield a claimable request, but
+  the public response must not disclose account existence.
+- The approval code must be printed in a copyable, server-supplied verification
+  URL. Opening it must not claim the request; the matching signed-in user must
+  explicitly review that exact code before approval controls appear.
+- Only one claimed pending or approved-but-uncollected request may be active per
+  user. Unclaimed issued codes must not occupy that slot.
 - 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.
+- Minted developer tokens must have a metadata-only inventory (owner, label,
+  scopes, created/expires/last-used/revoked state), immediate owner revocation,
+  and global admin incident response. Plaintext is shown only once and never
+  returned by inventory.
+- Handshake attempts must retain bounded metadata-only attribution using a
+  keyed requester fingerprint rather than a raw IP, with independent issue and
+  poll rate limits. Agents and developer tokens must not read this admin trail.
 
 ## Safe Provisioning
 
@@ -44,6 +60,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.