@odla-ai/cli 0.7.1 → 0.9.0

package/llms.txt

@@ -1,6 +1,6 @@
 # @odla-ai/cli — LLM context
 
-> Agent-operable CLI for odla provisioning, scoped System AI administration, hosted security runs, Worker secrets, and smoke checks.
+> Agent-operable CLI for odla provisioning, System AI administration, commit-pinned GitHub security jobs, Worker secrets, and smoke checks.
 
 > ⚠️ **Early access — pre-1.0.** Agents work from bounded runbooks; humans
 > approve credentials, production changes, releases, and merges. APIs and exact
@@ -31,8 +31,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.7.1 version
-npm i -D --save-exact @odla-ai/cli@0.7.1
+npm view @odla-ai/cli@0.9.0 version
+npm i -D --save-exact @odla-ai/cli@0.9.0
 ```
 
 ## Prerequisites
@@ -61,7 +61,15 @@ 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 security run . --env dev --ack-redacted-source
+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/cli security run . --env dev --ack-redacted-source
+npx @odla-ai/cli security github connect --env dev # infers owner/name from git origin
+npx @odla-ai/cli security plan --env dev
+npx @odla-ai/cli security sources --env dev
+npx @odla-ai/cli security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
+npx @odla-ai/cli security status <job-id>
+npx @odla-ai/cli security report <job-id>
 npx odla-ai admin ai show
 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
@@ -129,7 +137,7 @@ when provisioning has not written `.odla/credentials.local.json`.
 
 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.1`, then
+`npm i -D --save-exact @odla-ai/security@0.2.2`, then
 `npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical`.
 The passive scan remains a separate binary: it makes no model calls and does
 not execute target code. After explicit redacted-source approval,
@@ -155,12 +163,79 @@ carries a bounded `Retry-After` only when the upstream supplied one. The CLI
 does not echo arbitrary response text or silently change the admin-selected
 model.
 Before installing the exact release, require
-`npm view @odla-ai/security@0.2.1 version` to succeed before installation. An
+`npm view @odla-ai/security@0.2.2 version` to succeed before installation. An
 exact-version `E404` means the release is unavailable, not that the security
 preflight passed, and does not prove the package name is absent. odla's own
 engineering environment uses an equivalent internal gate; customer projects
 should use the published `odla-security` command above.
 
+For a server-side, commit-pinned review, connect one repository through odla's
+GitHub App. Contents and Metadata access are read-only; optional Checks write
+access publishes only a best-effort summary. The CLI infers `owner/name` from a
+safe GitHub HTTPS or SSH `origin`; pass `--repo owner/name` when it cannot. It
+opens GitHub's installation/authorization page and polls that exact odla
+attempt. Finish each browser stage within its displayed 15-minute window:
+
+```bash
+npx @odla-ai/cli security github connect --env dev
+npx @odla-ai/cli security plan --env dev
+npx @odla-ai/cli security sources --env dev
+npx @odla-ai/cli security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
+```
+
+The source job follows by default, renders the normalized report, and applies
+the same confirmed/candidate/incomplete gates; `--no-follow` only enqueues.
+`security status` and `security report` inspect prior jobs, while `security
+github disconnect --source <source-id> --env dev --yes` revokes the saved
+source without requiring a GitHub-side uninstall. A source id belongs to one
+app/environment; reconnect separately for another environment. Disconnect
+cancels nonterminal work, while terminal reports remain until normal expiry.
+The App is not subscribed to Push; an unexpectedly delivered Push event is
+ignored and never starts a job. Source jobs default to `cloudflare-app`;
+local-path jobs default to `odla`.
+
+Clients send only an opaque odla source id, ref, profile, and explicit redacted
+disclosure acknowledgement—never a PAT, installation id, provider key, or
+provider/model selection override. The CLI deliberately displays the read-only
+route identities in the consent preflight. odla.ai verifies access, pins the ref to a commit SHA,
+fetches the bounded snapshot server-side, and uses the admin-selected System AI
+routes. `security plan` shows both provider/model routes, exact policy
+revisions and bounds, prompt/redaction/report contracts, readiness, retention,
+and the no-execution boundary before consent. Each job requires
+`--plan-digest` and binds acknowledgement to that complete digest; any covered
+change requires a refreshed plan and acknowledgement.
+
+After validating that plan digest, the CLI fetches and prints the atomic
+server-authored execution intent for the exact app/environment, opaque source,
+ref (or default branch), profile, redacted disclosure, and plan digest. Its
+`executionDigest` is persisted with the job and sent back as
+`expectedExecutionDigest`; a changed selection fails with `intent_conflict`
+instead of running under generic consent. Repository display text is not digest
+authority.
+An omitted `--ref` is canonicalized to the source's current default-branch name
+during preview. A branch-default change before enqueue invalidates the intent
+instead of changing what the Workflow will acquire.
+
+GitHub read access is not disclosure consent. No raw archive, file body, or
+explicit source excerpt is deliberately persisted in the hosted report or
+Workflow checkpoints. The private report may keep bounded,
+best-effort credential-pattern-redacted model-derived prose and repository-relative paths for up to
+90 days; treat it as sensitive because it may reveal source semantics.
+Provider/GitHub terms are separate.
+
+The archive envelope is 16 MiB compressed, 48 MiB decompressed, 20,000 entries,
+10,000 files, 2 MiB per file, and 16 MiB aggregate file bytes. Links, special
+entries, unsafe redirects, duplicate paths, and escaping paths are rejected.
+The combined acquire/analyze step has zero automatic retries; after a terminal
+failure, correct the ref/access/archive shape or wait for service recovery and
+explicitly start a new job.
+
+Checks are optional, best-effort summaries, use fixed conclusion semantics, and
+are not the configurable CLI gate. Target code is not executed. Without an
+injected isolated executor, hosted inference cannot mechanically confirm a
+finding; critical candidates and incomplete coverage remain the operative
+gates, and a clean result is not proof of security.
+
 `admin ai show|models|set|credentials|credential set|usage|audit` manages platform-funded System
 AI (`o11y.triage`, `security.discovery`, `security.validation`). It uses a
 separate, mode-`0600` `.odla/admin-token.local.json` cache. Studio displays the
@@ -195,6 +270,22 @@ 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
@@ -284,37 +375,34 @@ If schema is present and rules are omitted, `defaultRules: "deny"` generates
 deny-all rules for every schema entity. That is the safe default for Workers
 that mediate reads and writes with an app key.
 
-## API reference (generated from dist/index.d.ts, v0.7.1)
+## API reference (generated from dist/index.d.ts, v0.9.0)
 
 ```ts
 import { SecurityReport, PlatformSecurityRun } from '@odla-ai/security';
+import { HostedSecurityJob, GitHubConnectionStatus, GitHubSecuritySource, HostedSecurityIntentResponse, HostedSecurityPlan, HostedSecurityReport, HostedSecurityJobStatus } from '@odla-ai/security/hosted';
+export { GitHubConnectionAttempt, GitHubConnectionStatus, GitHubSecuritySource, HostedSecurityCounts, HostedSecurityCoverage, HostedSecurityIntent, HostedSecurityIntentResponse, HostedSecurityJob, HostedSecurityJobStatus, HostedSecurityPlan, HostedSecurityPlanRoute, HostedSecurityReport, HostedSecurityReportFinding, HostedSecurityRoute } from '@odla-ai/security/hosted';
 
+/** Injectable side-effect boundaries used to run and test the command dispatcher. */
+interface CliDependencies {
+    fetch?: typeof fetch;
+    openUrl?: (url: string) => Promise<void>;
+    pollWait?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    readGitOrigin?: (cwd: string) => Promise<string>;
+    confirm?: (message: string) => Promise<boolean>;
+    stdout?: Pick<typeof console, "log" | "error">;
+}
 /**
- * Parse CLI arguments and dispatch to the matching command — the entry point
- * `bin.ts` invokes. `argv` defaults to `process.argv.slice(2)`; the first
- * positional selects the command and the rest are parsed into flags (supporting
- * `--flag value`, `--flag=value`, boolean `--flag`, `--no-flag`, and repeated
- * flags collected into arrays).
+ * Parse CLI arguments and dispatch the matching odla command.
  *
- * Recognized commands: `version`/`-v`/`--version` and `help`/`-h`/`--help` print
- * and return; `init` scaffolds a project (requires `--app-id` and `--name`);
- * `doctor` validates config offline; `capabilities` prints the responsibility
- * boundary; `admin ai` reads/updates purpose-specific platform AI policies,
- * transfers write-only credentials, and reads metadata-only attributed usage
- * through separate short-lived exact-scope device grants;
- * `security run` performs an explicitly acknowledged, app-attributed hosted
- * reasoning pass; `provision` runs the full provision (including optional secret
- * rotation, local vars, and deployed secret push); `smoke` checks a live env;
- * `setup` and `skill install` install the bundled offline runbooks for Claude
- * Code, Codex, Cursor, Copilot, Gemini, and `AGENTS.md`-aware agents; and
- * `secrets push` pipes the env's configured db/o11y secrets into the Worker via
- * Wrangler (requires `--env`). Throws on an unknown command/subcommand, unsupported option, extra
- * positional argument, missing required value, or a dispatched command error.
+ * The dispatcher covers project setup, platform AI administration, hosted and
+ * local security, provisioning, smoke checks, skill installation, and secret
+ * pushes. It rejects unknown commands, unsupported options, extra positionals,
+ * missing values, and errors returned by the selected command.
  *
- * @param argv Argument vector without the node/script prefix (default
- *   `process.argv.slice(2)`).
+ * @param argv Argument vector without the node/script prefix.
+ * @param dependencies Optional side-effect overrides for embedding and tests.
  */
-declare function runCli(argv?: string[]): Promise<void>;
+declare function runCli(argv?: string[], dependencies?: CliDependencies): Promise<void>;
 
 /** One exact platform scope obtainable through the admin device flow. */
 type ScopedPlatformScope = "platform:ai:policy:read" | "platform:ai:policy:write" | "platform:ai:credential:read" | "platform:ai:credential:write" | "platform:ai:usage:read" | "platform:ai:audit:read" | "platform:security:self";
@@ -383,10 +471,10 @@ declare function adminAi(options: AdminAiOptions): Promise<void>;
 /** Stable, machine-readable division of work between the CLI, coding agent,
  * human operator, and Studio. Printed by `odla-ai capabilities --json`. */
 declare const CAPABILITIES: {
-    readonly cli: readonly ["register the app and enable configured services per environment", "issue, persist, and explicitly rotate configured service credentials", "write local Worker values and push deployed Worker secrets through Wrangler stdin", "push db schema/rules and configure platform AI, auth, and deployment links", "validate config offline and smoke-test a provisioned db environment", "run app-attributed hosted security discovery and independent validation without provider keys", "let admins manage system AI policy and credentials, inspect attributed usage, and read immutable admin changes through separate short-lived capability-only approvals"];
+    readonly cli: readonly ["register the app and enable configured services per environment", "issue, persist, and explicitly rotate configured service credentials", "write local Worker values and push deployed Worker secrets through Wrangler stdin", "store tenant-vault secrets (including the Clerk webhook secret and reserved Clerk secret key) write-only from stdin or an env var", "push db schema/rules and configure platform AI, auth, and deployment links", "validate config offline and smoke-test a provisioned db environment", "run app-attributed hosted security discovery and independent validation without provider keys", "connect/revoke source-read-only GitHub sources and drive commit-pinned hosted security jobs without PATs or provider keys", "let admins manage system AI policy and credentials, inspect attributed usage, and read immutable admin changes through separate short-lived capability-only approvals"];
     readonly agent: readonly ["install and import the selected odla SDKs", "wrap the Worker with withObservability and choose useful telemetry", "make application-specific schema, rules, auth, UI, and migration decisions"];
-    readonly human: readonly ["approve the odla device code and one-off third-party logins", "consent to production changes with --yes", "request destructive credential rotation explicitly", "review application semantics, security findings, releases, and merges", "approve redacted-source disclosure before hosted security reasoning"];
-    readonly studio: readonly ["view telemetry and environment state", "perform manual credential recovery when the CLI's local shown-once copy is unavailable", "configure system AI purposes and view app/environment/run-attributed usage"];
+    readonly human: readonly ["approve the odla device code and one-off third-party logins", "consent to production changes with --yes", "request destructive credential rotation explicitly", "review application semantics, security findings, releases, and merges", "approve redacted-source disclosure before hosted security reasoning", "approve GitHub App repository access separately from redacted-snippet disclosure"];
+    readonly studio: readonly ["view telemetry and environment state", "perform manual credential recovery when the CLI's local shown-once copy is unavailable", "configure system AI purposes and view app/environment/run-attributed usage", "connect/revoke GitHub security sources and inspect ref-to-SHA jobs, routes, retention, coverage, and normalized reports"];
 };
 type Output = Pick<typeof console, "log">;
 /** Print the stable responsibility boundary for humans or agent tooling. */
@@ -659,6 +747,47 @@ interface SecretsPushOptions {
  */
 declare function secretsPush(options: SecretsPushOptions): Promise<void>;
 
+/**
+ * Inputs for one write-only tenant-vault transfer (`secrets set` /
+ * `secrets set-clerk-key`). Values may come only from a named environment
+ * variable or stdin, so a producer command can be piped straight into the
+ * vault without the secret ever being displayed or stored on disk.
+ */
+interface SecretsSetOptions {
+    configPath: string;
+    env: string;
+    /** Vault secret name (`secrets set` only; `$`-prefixed names are reserved). */
+    name?: string;
+    fromEnv?: string;
+    stdin?: boolean;
+    /** Explicit consent for a prod-named env (and for sk_live_ into a non-prod env). */
+    yes?: boolean;
+    /** Developer token override; defaults to $ODLA_DEV_TOKEN, the cached token, or a device handshake. */
+    token?: string;
+    open?: boolean;
+    interactive?: boolean;
+    openApprovalUrl?: (url: string) => Promise<void>;
+    fetch?: typeof fetch;
+    readStdin?: () => Promise<string>;
+    stdout?: Pick<typeof console, "log" | "error">;
+}
+/**
+ * Store one named secret in the env's tenant vault (the same write-only slot
+ * Studio's Secrets panel fills), e.g. `clerk_webhook_secret` for synced auth.
+ * The value is encrypted at rest and can be read back only by that tenant's
+ * app API key — never by this CLI, Studio, or the developer token.
+ */
+declare function secretsSet(options: SecretsSetOptions): Promise<void>;
+/**
+ * Store the app's Clerk secret key under the reserved `$clerk_secret` slot so
+ * odla-db can resolve the app's users (invites, member lookups). Reserved
+ * secrets are never readable by app keys; the dedicated endpoint is the only
+ * way to set one. Guards against instance/env mismatches: an sk_test_ key
+ * never belongs in a prod-named env, and an sk_live_ key entering a non-prod
+ * env requires `--yes` (live users would sync into a non-prod tenant).
+ */
+declare function secretsSetClerkKey(options: SecretsSetOptions): Promise<void>;
+
 /** Built-in security coverage profile selected for a hosted reasoning run. */
 type HostedSecurityProfile = "odla" | "cloudflare-app" | "generic";
 /** Exact attribution and authorization need supplied to a lazy token callback. */
@@ -714,6 +843,130 @@ interface HostedSecurityResult {
  */
 declare function runHostedSecurity(options: RunHostedSecurityOptions): Promise<HostedSecurityResult>;
 
+/**
+ * The hosted-security client surface. The WIRE types live in @odla-ai/security/hosted — one
+ * definition shared with the dashboard and the server that produces them. Re-exported here so
+ * this module stays the single import path for the rest of the CLI.
+ *
+ * What remains below is what is genuinely the CLI's own: transport controls (platform origin,
+ * token, fetch, AbortSignal) that no other client shares.
+ */
+
+/** Common authenticated transport controls for hosted-security requests. */
+interface HostedSecurityRequestOptions {
+    platform: string;
+    token: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}
+/** Options for browser-mediated connection of one exact GitHub repository. */
+interface ConnectGitHubSecuritySourceOptions extends HostedSecurityRequestOptions {
+    appId: string;
+    env: string;
+    /** Exact owner/name repository requested before GitHub approval. */
+    repository: string;
+    /** false prints but does not launch the install URL. Defaults to true. */
+    open?: boolean;
+    openInstallUrl?: (url: string) => Promise<void>;
+    /** Poll interval. The server attempt expiry remains authoritative. */
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    wait?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    now?: () => number;
+    stdout?: Pick<typeof console, "log">;
+}
+/** Options for listing GitHub sources or reading the plan for one app environment. */
+interface ListGitHubSecuritySourcesOptions extends HostedSecurityRequestOptions {
+    appId: string;
+    env: string;
+}
+/** Inputs for fetching the server-authored execution preview before enqueue. */
+interface GetHostedSecurityIntentOptions extends HostedSecurityRequestOptions {
+    appId: string;
+    env: string;
+    sourceId: string;
+    ref?: string;
+    profile?: "odla" | "cloudflare-app" | "generic";
+}
+/** Options for revoking odla access to one saved GitHub source. */
+interface DisconnectGitHubSecuritySourceOptions extends HostedSecurityRequestOptions {
+    appId: string;
+    sourceId: string;
+}
+/** Options for enqueueing a commit-pinned hosted security review. */
+interface StartHostedSecurityJobOptions extends HostedSecurityRequestOptions {
+    appId: string;
+    env: string;
+    sourceId: string;
+    ref?: string;
+    profile?: "odla" | "cloudflare-app" | "generic";
+    clientRequestId?: string;
+    /** Versions shown in the disclosure preflight. The server rejects stale consent. */
+    expectedPolicyVersions: {
+        discovery: number;
+        validation: number;
+    };
+    /** Digest copied from the plan the app owner explicitly reviewed. */
+    expectedPlanDigest: `sha256:${string}`;
+    /** Digest copied from the exact server-authored source/ref/profile preview. */
+    expectedExecutionDigest: `sha256:${string}`;
+    /** Explicit disclosure acknowledgement; GitHub read access alone is not consent. */
+    sourceDisclosureAck?: "redacted";
+}
+/** Options for reading one hosted security job or its report. */
+interface GetHostedSecurityJobOptions extends HostedSecurityRequestOptions {
+    appId: string;
+    jobId: string;
+}
+/** Options for listing hosted security jobs in one app environment. */
+interface ListHostedSecurityJobsOptions extends HostedSecurityRequestOptions {
+    appId: string;
+    env: string;
+}
+/** Polling controls for following one hosted job to a terminal state. */
+interface FollowHostedSecurityJobOptions extends GetHostedSecurityJobOptions {
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    wait?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    now?: () => number;
+    onUpdate?: (job: Readonly<HostedSecurityJob>) => void;
+}
+
+/** Begin GitHub App installation, launch its server-issued GitHub URL, and
+ * poll the exact attempt until the callback has connected a source. */
+declare function connectGitHubSecuritySource(options: ConnectGitHubSecuritySourceOptions): Promise<GitHubConnectionStatus>;
+/** List repository sources the current app owner connected for one environment. */
+declare function listGitHubSecuritySources(options: ListGitHubSecuritySourcesOptions): Promise<GitHubSecuritySource[]>;
+/** Revoke odla's use of one saved source without requiring a GitHub-side App
+ * uninstall. The server marks the source deleted and rejects new jobs. */
+declare function disconnectGitHubSecuritySource(options: DisconnectGitHubSecuritySourceOptions): Promise<void>;
+/** Parse an HTTPS, ssh://, or git@github.com origin without retaining embedded
+ * credentials. Only github.com owner/name remotes are accepted. */
+declare function repositoryFromGitRemote(remoteInput: string): string;
+/** Read the current repository's origin without invoking a shell. */
+declare function inferGitHubRepository(cwd?: string, readOrigin?: (cwd: string) => Promise<string>): Promise<string>;
+
+/** Fetch the atomic processing-plan and source/ref/profile execution preview. */
+declare function getHostedSecurityIntent(options: GetHostedSecurityIntentOptions): Promise<HostedSecurityIntentResponse>;
+
+/** Read the admin-selected routes, budgets, readiness, disclosure boundary,
+ * and digest that must be acknowledged when a hosted review is enqueued. */
+declare function getHostedSecurityPlan(options: ListGitHubSecuritySourcesOptions): Promise<HostedSecurityPlan>;
+/** Enqueue a commit-pinned server-side review. The server resolves sourceId to
+ * its saved GitHub App installation; clients cannot choose an installation or
+ * pass a PAT. */
+declare function startHostedSecurityJob(options: StartHostedSecurityJobOptions): Promise<HostedSecurityJob>;
+/** Read one bounded hosted job status without an archive or explicit source excerpt. */
+declare function getHostedSecurityJob(options: GetHostedSecurityJobOptions): Promise<HostedSecurityJob>;
+/** List bounded, newest-first job metadata for an app environment. */
+declare function listHostedSecurityJobs(options: ListHostedSecurityJobsOptions): Promise<HostedSecurityJob[]>;
+/** Poll one exact job until it reaches a terminal state. */
+declare function followHostedSecurityJob(options: FollowHostedSecurityJobOptions): Promise<HostedSecurityJob>;
+/** Fetch the bounded normalized report projection for a completed hosted job. */
+declare function getHostedSecurityReport(options: GetHostedSecurityJobOptions): Promise<HostedSecurityReport>;
+/** Return whether a hosted job status can no longer transition. */
+declare function isTerminalHostedSecurityStatus(status: HostedSecurityJobStatus): boolean;
+
 /** Agent harnesses with a first-class local adapter. */
 declare const AGENT_HARNESSES: readonly ["claude", "codex", "cursor", "copilot", "gemini", "agents"];
 /** A supported coding-agent harness. `agents` is the portable `AGENTS.md` adapter. */
@@ -793,5 +1046,5 @@ declare function installSkill(options?: SkillInstallOptions): SkillInstallResult
  */
 declare function smoke(options: SmokeOptions): Promise<void>;
 
-export { AGENT_HARNESSES, type AdminAiOptions, type AgentHarness, type AgentHarnessSelector, CAPABILITIES, type HarnessInstallResult, type HostedSecurityProfile, type HostedSecurityResult, type HostedSecurityTokenRequest, type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type RunHostedSecurityOptions, SYSTEM_AI_PURPOSES, type ScopedPlatformTokenOptions, type SecretsPushOptions, type SkillInstallOptions, type SkillInstallResult, type SmokeOptions, type SystemAiPurpose, adminAi, doctor, getScopedPlatformToken, initProject, installSkill, printCapabilities, provision, redactSecrets, runCli, runHostedSecurity, secretsPush, smoke };
+export { AGENT_HARNESSES, type AdminAiOptions, type AgentHarness, type AgentHarnessSelector, CAPABILITIES, type CliDependencies, type ConnectGitHubSecuritySourceOptions, type DisconnectGitHubSecuritySourceOptions, type FollowHostedSecurityJobOptions, type GetHostedSecurityIntentOptions, type GetHostedSecurityJobOptions, type HarnessInstallResult, type HostedSecurityProfile, type HostedSecurityResult, type HostedSecurityTokenRequest, type ListGitHubSecuritySourcesOptions, type ListHostedSecurityJobsOptions, type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type RunHostedSecurityOptions, SYSTEM_AI_PURPOSES, type ScopedPlatformTokenOptions, type SecretsPushOptions, type SecretsSetOptions, type SkillInstallOptions, type SkillInstallResult, type SmokeOptions, type StartHostedSecurityJobOptions, type SystemAiPurpose, adminAi, connectGitHubSecuritySource, disconnectGitHubSecuritySource, doctor, followHostedSecurityJob, getHostedSecurityIntent, getHostedSecurityJob, getHostedSecurityPlan, getHostedSecurityReport, getScopedPlatformToken, inferGitHubRepository, initProject, installSkill, isTerminalHostedSecurityStatus, listGitHubSecuritySources, listHostedSecurityJobs, printCapabilities, provision, redactSecrets, repositoryFromGitRemote, runCli, runHostedSecurity, secretsPush, secretsSet, secretsSetClerkKey, smoke, startHostedSecurityJob };
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.7.1",
-  "description": "Agent-operable CLI for odla provisioning, scoped System AI administration, hosted security runs, Worker secrets, and smoke checks.",
+  "version": "0.9.0",
+  "description": "Agent-operable CLI for odla provisioning, System AI administration, commit-pinned GitHub security jobs, Worker secrets, and smoke checks.",
   "license": "MIT",
   "homepage": "https://odla.ai/docs/packages/cli",
   "repository": {
@@ -62,7 +62,7 @@
     "@odla-ai/ai": "^0.3.3",
     "@odla-ai/apps": "^0.7.1",
     "@odla-ai/db": "^0.6.2",
-    "@odla-ai/security": "^0.2.1"
+    "@odla-ai/security": "^0.2.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/skills/odla/SKILL.md

@@ -74,7 +74,14 @@ guessing which platform/credential steps need manual work. Then:
    redacted source disclosure, follow with
    `npx @odla-ai/cli security run . --env dev --ack-redacted-source` for
    app-attributed discovery + independent validation. Never request provider
-   keys; the platform selects the routes and returns bounded role grants.
+   keys; the platform selects the routes and returns bounded role grants. For
+   repeatable server-side review, run `security github connect --env dev`
+   (human approves source-read-only GitHub access), `security plan --env dev`,
+   `security sources --env dev`, then `security run --source <id> --ref <ref>
+   --env dev --plan-digest <digest-from-security-plan>
+   --ack-redacted-source`.
+   The source job follows, reports, and gates by default. Never request a PAT or
+   treat GitHub read approval as redacted-snippet disclosure consent.
 6. **ship** ⏸ — after adding `prod`, run `npx @odla-ai/cli provision --dry-run`,
    show the human, then `npx @odla-ai/cli provision --yes --push-secrets` and
    `npx wrangler deploy`.

package/skills/odla/references/build.md

@@ -66,12 +66,12 @@ re-provision to push it, and retry.
 Install the passive harness and scan before any production secret or deploy:
 
 Before installing the exact release, first verify
-`npm view @odla-ai/security@0.2.1 version`. An exact-version `E404` means the
+`npm view @odla-ai/security@0.2.2 version`. An exact-version `E404` means the
 release is unavailable and blocks this preflight; it is not a clean scan and
 does not prove the package name is absent.
 
 ```
-npm i -D --save-exact @odla-ai/security@0.2.1
+npm i -D --save-exact @odla-ai/security@0.2.2
 npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical
 ```
 
@@ -87,6 +87,21 @@ disclosure under the configured providers' retention/residency terms):
 npx @odla-ai/cli security run . --env dev --ack-redacted-source
 ```
 
+For a repeatable commit-pinned job after the human approves the read-only
+GitHub App:
+
+```
+npx @odla-ai/cli security github connect --env dev
+npx @odla-ai/cli security plan --env dev
+npx @odla-ai/cli security sources --env dev
+npx @odla-ai/cli security run --source <source-id> --ref main --env dev --plan-digest <digest-from-security-plan> --ack-redacted-source
+```
+
+The CLI infers the repository from a safe GitHub origin, never requests a PAT
+or provider key, follows the job and applies the gate by default. GitHub read
+approval does not replace the explicit redacted-source acknowledgement. Target
+code is not executed and a clean report is not proof of security.
+
 Do not ask for Anthropic/OpenAI/Google keys. The CLI obtains app-owner auth;
 the platform fixes separate discovery/validation grants to the admin-configured
 routes, attributes usage to this app/env/run, and retains no source or prompts

package/skills/odla/references/sdks.md

@@ -70,12 +70,12 @@ Run the passive CLI in local/CI development; do not import it into the running
 Worker:
 
 Before installing the exact release, require
-`npm view @odla-ai/security@0.2.1 version` to succeed before installing it. An
+`npm view @odla-ai/security@0.2.2 version` to succeed before installing it. An
 exact-version `E404` means the release is unavailable, not that the preflight
 passed, and does not prove the package name is absent.
 
 ```
-npm i -D --save-exact @odla-ai/security@0.2.1
+npm i -D --save-exact @odla-ai/security@0.2.2
 npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical
 ```
 

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.7.1 version` to succeed, then run
-   `npm i -D --save-exact @odla-ai/cli@0.7.1` and `npm i @odla-ai/db`.
+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`.
 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-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/phase-5-cutover.md

@@ -24,10 +24,10 @@ instance, never a second Clerk app per env; final go/no-go at each step.
    `secrets push --env prod --yes` only to retry the transfer (see
    references/secrets-map.md).
 3. Build, then run the passive pre-cutover security gate:
-   first require `npm view @odla-ai/security@0.2.1 version` to succeed. An
+   first require `npm view @odla-ai/security@0.2.2 version` to succeed. An
    exact-version `E404` means the release is unavailable and blocks cutover;
    it is not a clean scan and does not prove the package name is absent. Run
-   `npm i -D --save-exact @odla-ai/security@0.2.1` followed by
+   `npm i -D --save-exact @odla-ai/security@0.2.2` followed by
    `npx odla-security scan . --profile odla --out .odla/security/pre-cutover --fail-on high --fail-on-candidates critical`.
    Review `REPORT.md`; a candidate is a lead, not confirmation, and a baseline
    requires a concrete reason, owner, and expiry.
@@ -35,6 +35,12 @@ instance, never a second Clerk app per env; final go/no-go at each step.
    with `npx @odla-ai/cli security run . --env prod --ack-redacted-source`.
    The platform owns provider credentials and attributes the bounded,
    independent-model run to this app; never request provider keys locally.
+   For a repeatable commit-pinned review, the human can first approve
+   `security github connect --env prod`, then the agent runs `security plan`,
+   lists `security sources`, and runs `security run --source <id> --ref <ref>
+   --env prod --plan-digest <digest-from-security-plan>
+   --ack-redacted-source`. Never request a PAT; GitHub read approval is not
+   snippet-disclosure consent.
 4. `npx wrangler deploy` (first prod deploy). Verify
    `/api/health` and the parity paths on the prod workers.dev URL.
 5. `npx @odla-ai/cli smoke --env prod`.

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`,