@withandeo/cli 0.12.0 → 0.14.0

package/dist/main.js

@@ -1,7 +1,7 @@
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
-import { copyFile, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm } from "node:fs/promises";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { lstat, mkdtemp, readFile, readdir, realpath, rm } from "node:fs/promises";
+import { basename, join, relative, resolve, sep } from "node:path";
 import { homedir, hostname, tmpdir } from "node:os";
 import { createHash } from "node:crypto";
 import { AgentApiClient } from "./api.js";
@@ -16,6 +16,8 @@ import { captureCommand, runProjectCommand } from "./processes.js";
 import { createDefaultProfileBindings, } from "./profile-bindings.js";
 import { initializeStarter } from "./starter.js";
 import { normalizeAndeoEnvironment } from "./andeo-environment.js";
+import { DOC_TOPICS, readDocumentation, installDocumentation, installedSkillCheck } from "./documentation.js";
+import { capabilityPreflight } from "./capability-preflight.js";
 const packageMetadata = createRequire(import.meta.url)("../package.json");
 if (typeof packageMetadata.version !== "string" || packageMetadata.version.length === 0) {
     throw new Error("Andeo CLI package version is missing.");
@@ -94,6 +96,18 @@ async function execute(topic, options, cwd, runtime) {
     if (topic.startsWith("workflows "))
         return { value: await workflowCommand(topic.slice(10), cwd, options, runtime) };
     switch (topic) {
+        case "docs": {
+            const name = options.positionals[0];
+            if (!name)
+                return { value: { schema: "andeo.docs/v1", version: CLI_VERSION, topics: DOC_TOPICS } };
+            const content = await readDocumentation(name);
+            return options.json ? { value: { schema: "andeo.docs/v1", version: CLI_VERSION, topic: name, content } } : { raw: content };
+        }
+        case "capabilities": {
+            const context = await optionalContext(cwd);
+            const { client, projectId } = await sourceProjectAccess(cwd, context?.link ?? null, options, runtime, false);
+            return { value: await client.capabilities(projectId) };
+        }
         case "init":
             return { value: await initializeStarter({
                     cwd,
@@ -186,6 +200,32 @@ async function execute(topic, options, cwd, runtime) {
             return { value: await sourceChangeClose(cwd, options, runtime) };
         case "source connect":
             return { value: await sourceConnect(cwd, options, runtime) };
+        case "source policy show":
+        case "source policy set": {
+            const context = await optionalContext(cwd);
+            const access = await sourceProjectAccess(cwd, context?.link ?? null, options, runtime, false);
+            if (topic === "source policy show")
+                return { value: await access.client.sourcePolicy(access.projectId) };
+            const publication = requiredFlag(options, "publication");
+            if (!["preview-only", "default-branch"].includes(publication))
+                throw new CliError("source_publication_invalid", "Choose preview-only or default-branch.");
+            return { value: await access.client.sourcePolicy(access.projectId, { repositoryId: requiredFlag(options, "repository"),
+                    expectedRevision: Number(requiredFlag(options, "expected-revision")), enabled: publication === "default-branch",
+                    idempotencyKey: requiredFlag(options, "idempotency-key") }) };
+        }
+        case "vars list":
+        case "vars set":
+        case "vars unset": {
+            const context = await optionalContext(cwd);
+            const access = await sourceProjectAccess(cwd, context?.link ?? null, options, runtime, false);
+            const environment = requiredFlag(options, "environment");
+            if (environment !== "preview" && environment !== "production")
+                throw new CliError("environment_invalid", "Choose preview or production.");
+            const input = topic === "vars list" ? undefined : { name: requiredFlag(options, "name"),
+                expectedRevision: Number(requiredFlag(options, "expected-revision")),
+                ...(topic === "vars unset" ? { remove: true } : { value: new TextDecoder("utf8", { fatal: true }).decode(await readBoundedFile(resolve(cwd, requiredFlag(options, "file")), 4096)) }) };
+            return { value: await access.client.runtimeVars(access.projectId, environment, input) };
+        }
         case "source pull":
             return { value: await sourcePull(cwd, options, runtime) };
         case "source token":
@@ -814,7 +854,7 @@ async function sourceConnect(cwd, options, runtime) {
         buildCommand: context.config.commands.package,
         workingDirectory,
         artifactLatestPath,
-        autoPublishDefaultBranch: publication === "default-branch",
+        ...(options.flags.has("publication") ? { autoPublishDefaultBranch: publication === "default-branch" } : {}),
     });
     const remote = options.flags.get("remote") ?? "tender";
     await ensureGitRemote(gitRoot, remote, created.repository.remoteUrl, runtime);
@@ -1436,6 +1476,7 @@ async function linkProject(cwd, options, runtime) {
 }
 async function doctor(cwd, options, runtime) {
     const checks = [];
+    checks.push(await installedSkillCheck(runtime.homeDirectory));
     const nodeMajor = Number(process.versions.node.split(".")[0]);
     checks.push({
         name: "node",
@@ -1464,6 +1505,18 @@ async function doctor(cwd, options, runtime) {
             checks.push(project
                 ? { name: "project-access", status: project.role === "developer" ? "pass" : "fail", message: `${project.projectId} · ${project.role}` }
                 : { name: "project-access", status: "fail", message: "The linked project is outside this credential's scope." });
+            if (project && context.link) {
+                try {
+                    const capabilities = await client.capabilities(context.link.projectId);
+                    if (capabilities.schema !== "andeo.capabilities/v1" || capabilities.projectId !== context.link.projectId) {
+                        throw new Error("Capability discovery unavailable; update the platform before relying on this check.");
+                    }
+                    checks.push(...await capabilityPreflight(context.root, resolveArtifactDirectory(context), capabilities, runtime.environment.WRANGLER_ENV));
+                }
+                catch (error) {
+                    checks.push({ name: "capabilities", status: "warn", message: `Capability preflight incomplete: ${normalizeError(error).message}` });
+                }
+            }
         }
         catch (error) {
             checks.push({ name: "authentication", status: "fail", message: normalizeError(error).message });
@@ -1932,13 +1985,7 @@ async function installSkill(cwd, options, runtime) {
     if (!base) {
         throw new CliError("skill_target_invalid", "--agent must be codex or claude unless --directory is provided.");
     }
-    const target = resolve(base, "andeo/SKILL.md");
-    if (await pathExists(target) && !options.booleans.has("force")) {
-        throw new CliError("skill_exists", `A Andeo skill already exists at ${target}.`, `andeo skill install --agent ${agent} --force`);
-    }
-    await mkdir(dirname(target), { recursive: true });
-    await copyFile(skillPath(), target);
-    return { status: "installed", agent, path: target };
+    return { status: "installed", agent, ...await installDocumentation(base, options.booleans.has("force"), CLI_VERSION) };
 }
 async function readSkill() {
     return await readFile(skillPath(), "utf8");
@@ -1969,11 +2016,11 @@ function commandTopic(argv) {
         const topic = `preview ${argv[1]}`;
         return argv.includes("--help") || argv.includes("-h") ? { topic: "help", values: [topic] } : { topic, values: argv.slice(2) };
     }
-    if (parent === "auth" || parent === "delivery" || parent === "source" || parent === "skill" || parent === "config" || parent === "production" || parent === "workflows") {
+    if (parent === "auth" || parent === "delivery" || parent === "source" || parent === "vars" || parent === "skill" || parent === "config" || parent === "production" || parent === "workflows") {
         const child = argv[1];
         if (!child || child.startsWith("--"))
             return { topic: "help", values: [parent] };
-        if (parent === "source" && (child === "default" || child === "history" || child === "operation" || child === "change")) {
+        if (parent === "source" && (child === "default" || child === "history" || child === "operation" || child === "change" || child === "policy")) {
             const grandchild = argv[2];
             if (!grandchild || grandchild.startsWith("--"))
                 return { topic: "help", values: [`${parent} ${child}`] };
@@ -2032,6 +2079,8 @@ function assertAllowedOptions(topic, options) {
     const common = ["cwd", "json"];
     const authentication = ["api-url", "token-stdin", "profile"];
     const allowed = {
+        docs: common,
+        capabilities: [...common, ...authentication, "project"],
         "workflows list": [...common, ...authentication, "project", "environment", "limit", "offset"],
         "workflows runs": [...common, ...authentication, "project", "scope", "limit", "offset"],
         "workflows status": [...common, ...authentication, "project", "scope", "run"],
@@ -2082,6 +2131,11 @@ function assertAllowedOptions(topic, options) {
         "production releases": [...common, ...authentication, "project"],
         "production rollback": [...common, ...authentication, "project", "release", "expected-release", "expected-revision", "idempotency-key"],
         "source branches": [...common, ...authentication, "project"],
+        "source policy show": [...common, ...authentication, "project"],
+        "source policy set": [...common, ...authentication, "project", "repository", "publication", "expected-revision", "idempotency-key"],
+        "vars list": [...common, ...authentication, "project", "environment"],
+        "vars set": [...common, ...authentication, "project", "environment", "name", "file", "expected-revision"],
+        "vars unset": [...common, ...authentication, "project", "environment", "name", "expected-revision"],
         "source log": [...common, ...authentication, "project", "branch", "limit"],
         "source compare": [...common, ...authentication, "project", "base", "head"],
         "source default set": [
@@ -2136,6 +2190,7 @@ function assertAllowedOptions(topic, options) {
         throw new CliError("argument_unknown", `Option --${unexpected} is not valid for ${topic}.`, `tender-accounts ${topic} --help`);
     }
     const positionalLimits = {
+        docs: { minimum: 0, maximum: 1 },
         "auth create": { minimum: 1, maximum: 1 },
         "auth delete": { minimum: 1, maximum: 1 },
         "auth activate": { minimum: 1, maximum: 2 },
@@ -2241,6 +2296,10 @@ Choose background preview routing with preview-service-set --target-project PROJ
 Only non-secret JSON belongs in workflow params/events. Keep credentials in the connected service's native secrets.
 Account workflow entitlement is required for new starts. Run status is authoritative; list results are a timestamped projection.`;
     const topics = {
+        vars: "Usage: andeo vars <list|set|unset> --environment preview|production [options]\n\nManage saved non-secret runtime variables. Changes apply on the next delivery.",
+        "source policy": "Usage: andeo source policy <show|set> [options]\n\nInspect or update the administrator-authorized automatic publication policy.",
+        docs: "Usage: andeo docs [TOPIC] [--json]\n\nRead offline guidance bundled with this CLI. No login or checkout needed.\n\nExamples:\n  andeo docs --json\n  andeo docs workflows\n  andeo docs configuration-secrets --json",
+        capabilities: "Usage: andeo capabilities [--project PROJECT_ID] [--json]\n\nRead supported resources, account enablement/quotas and scoped permissions. Read-only and advisory; not proof of provisioning or remaining capacity. Requires the capability-discovery agent API.\n\nExamples:\n  andeo capabilities --json\n  andeo capabilities --project prj_... --json",
         init: "Usage: andeo init --name NAME [--slug SLUG] [--directory PATH] [--template shopify-customer-account] [--dry-run] [--json]\n\nCreate a new merchant-owned Shopify gateway and React portal in an empty directory.\n\nExamples:\n  andeo init --name \"Acme account\" --directory ./acme-account\n  andeo init --name \"Acme account\" --directory ./acme-account --dry-run --json",
         auth: "Usage: andeo auth <login|create|activate|deactivate|status|list|delete|logout> [options]",
         "auth login": "Usage: andeo auth login [--device] [--project PROJECT_ID] [--no-open] [--wait] [--force] [--json]\n\nCreate or refresh the default login. Browser-capable terminals use Authorization Code with PKCE. --device returns an agent-safe approval URL and code; add --wait to keep polling. Use auth create for named merchant profiles.",
@@ -2261,14 +2320,14 @@ Account workflow entitlement is required for new starts. Run status is authorita
         production: "Usage: andeo production <releases|rollback> [options]",
         "production releases": "Usage: andeo production releases [--project PROJECT_ID] [--json]\n\nList immutable production releases and rollback eligibility.",
         "production rollback": "Usage: andeo production rollback [--project PROJECT_ID] --release RELEASE_ID --expected-release CURRENT_ID --expected-revision N --idempotency-key KEY [--json]\n\nMerchant administrators restore a previously successful app release without building or uploading code.",
-        source: "Usage: andeo source <status|branches|log|compare|connect|pull|push|change|default|promote|history|operation> [options]\n\nUse standard Git through Andeo for a gateway or service project. Source changes never publish production directly.",
+        source: "Usage: andeo source <status|branches|log|compare|connect|policy|pull|push|change|default|promote|history|operation> [options]\n\nUse standard Git through Andeo for a gateway or service project. Default-branch changes follow the saved publication policy.",
         "source status": "Usage: andeo source status [--project PROJECT_ID] [--json]\n\nRead the managed repository, immutable build contract, and recent source builds. --project works before a checkout is linked.\n\nExamples:\n  andeo source status --project prj_... --json\n  andeo source status --json",
         "source branches": "Usage: andeo source branches [--project PROJECT_ID] [--json]\n\nList exact branch refs and identify Andeo's authoritative default separately from the provider's create-time default. Uses a short-lived read credential without persisting it.",
         "source log": "Usage: andeo source log [--project PROJECT_ID] [--branch BRANCH] [--limit 20] [--json]\n\nRead bounded commit history from one exact managed branch without requiring a checkout.",
         "source compare": "Usage: andeo source compare [--project PROJECT_ID] --base BRANCH --head BRANCH [--json]\n\nCompare exact managed refs and report identical, fast-forward, behind, diverged, or unrelated history plus a bounded file list.",
         "source default": "Usage: andeo source default set --branch BRANCH --expected-current BRANCH [--dry-run] [--json]",
         "source default set": "Usage: andeo source default set [--project PROJECT_ID] --branch BRANCH --expected-current BRANCH [--idempotency-key KEY] [--dry-run] [--no-wait] [--json]\n\nSet an existing branch as Andeo's authoritative default with compare-and-swap. This metadata-only operation cannot change production.",
-        "source promote": "Usage: andeo source promote [--project PROJECT_ID] --head BRANCH [--base BRANCH] --expected-current SHA [--idempotency-key KEY] [--dry-run] [--no-wait] [--json]\n\nPromote a successfully previewed head into the current default branch using an exact expected-SHA lease. Normal preview/publication policy applies to the resulting push; protected gateways remain preview-only.",
+        "source promote": "Usage: andeo source promote [--project PROJECT_ID] --head BRANCH [--base BRANCH] --expected-current SHA [--idempotency-key KEY] [--dry-run] [--no-wait] [--json]\n\nPromote a successfully previewed head into the current default branch using an exact expected-SHA lease. Normal preview/publication policy applies to the resulting push; automatic publication requires the saved opt-in policy.",
         "source history": "Usage: andeo source history replace --head BRANCH --expected-current SHA --confirm REPOSITORY_ID [--dry-run] [--json]",
         "source history replace": "Usage: andeo source history replace [--project PROJECT_ID] --head BRANCH [--target BRANCH] --expected-current SHA --confirm REPOSITORY_ID [--idempotency-key KEY] [--dry-run] [--no-wait] [--json]\n\nExceptional source migration only: archive the exact previous target, then replace it with an expected-SHA compare-and-swap. Automatic production publication is always suppressed.",
         "source operation": "Usage: andeo source operation <status|retry> --operation sop_... [--json]",
@@ -2279,7 +2338,12 @@ Account workflow entitlement is required for new starts. Run status is authorita
         "source change list": "Usage: andeo source change list [--state open|closed|all] [--json]\n\nList reviewed source changes for this exact linked project.",
         "source change show": "Usage: andeo source change show --change scr_... [--json]\n\nRead exact snapshot, preview, decision, and landing state.",
         "source change close": "Usage: andeo source change close --change scr_... [--json]\n\nClose an unlanded change without changing source or production.",
-        "source connect": "Usage: andeo source connect [--repo-name NAME] [--default-branch NAME] [--publication preview-only|default-branch] [--remote NAME] [--install-command COMMAND] [--working-directory PATH] [--artifact-path PATH] [--json]\n\nCreate or reconnect this linked project to Andeo-managed Git. Build and artifact commands come from tender-accounts.json. Protected gateways accept preview-only publication.",
+        "source connect": "Usage: andeo source connect [--repo-name NAME] [--default-branch NAME] [--publication preview-only|default-branch] [--remote NAME] [--install-command COMMAND] [--working-directory PATH] [--artifact-path PATH] [--json]\n\nCreate or reconnect this linked project to Andeo-managed Git. Use source policy set to change an existing publication policy.",
+        "source policy show": "Usage: andeo source policy show [--project PROJECT_ID] [--json]\n\nInspect the saved managed-source publication policy and revision.",
+        "source policy set": "Usage: andeo source policy set [--project PROJECT_ID] --repository SRC_ID --publication preview-only|default-branch --expected-revision N --idempotency-key KEY [--json]\n\nMerchant administrators enable or disable automatic publication of future default-branch changes after successful preview and production validation. Saving a policy does not publish an existing build. Manual uploads remain explicit.",
+        "vars list": "Usage: andeo vars list --environment preview|production [--project PROJECT_ID] [--json]\n\nList saved variable names and the configuration revision. Values are never returned.",
+        "vars set": "Usage: andeo vars set --environment preview|production --name NAME --file PATH --expected-revision N [--project PROJECT_ID] [--json]\n\nSave a non-secret runtime variable from a UTF-8 file. Applied on the next deployment. Use existing administrator Secrets controls for credentials.",
+        "vars unset": "Usage: andeo vars unset --environment preview|production --name NAME --expected-revision N [--project PROJECT_ID] [--json]\n\nRemove a variable from the next deployment's configuration.",
         "source pull": "Usage: andeo source pull [--project PROJECT_ID] [--remote NAME] [--dry-run] [--json]\n\nClone the exact connected Andeo-managed repository into an empty workspace, or fast-forward an existing clean matching checkout. The app is linked automatically and the short-lived Git credential is never persisted.\n\nExamples:\n  andeo source pull --project prj_... --dry-run --json\n  andeo source pull --project prj_... --json\n  andeo source pull --json",
         "source token": "Usage: andeo source token [--ttl-seconds N] [--json]\n\nIssue a short-lived read-only repository credential. It is shown once and is never stored by the CLI.",
         "source push": "Usage: andeo source push [--branch NAME] [--remote NAME] [--no-wait] [--json]\n\nPush the exact committed revision. Reviewed repositories upload a bounded Git bundle and never expose a write credential; the default branch remains protected. Dirty working-tree changes are excluded.",
@@ -2297,7 +2361,7 @@ Account workflow entitlement is required for new starts. Run status is authorita
     };
     if (topic && topics[topic])
         return topics[topic];
-    return `Andeo merchant developer CLI ${CLI_VERSION}\n\nCommands:\n  init              Create a new Shopify account starter\n  auth login        Create or refresh the default login\n  auth create       Create or re-authorize a named login\n  auth activate     Bind a named login to a directory tree\n  auth deactivate   Remove an exact directory binding\n  auth status       Validate one login or scoped credential\n  auth list         List local login profiles and bindings\n  auth delete       Revoke one named login\n  auth logout       Revoke the default or every login\n  link              Link this checkout to one permitted project\n  doctor            Check developer readiness\n  dev               Run the project-owned local dev command\n  check             Run project validation\n  build             Package and verify a portable artifact\n  upload            Retain a build for administrator publication\n  preview           Build and deploy an exact preview\n  preview entries   List eligible connected entry apps\n  preview open      Reopen an exact deployed preview\n  source status     Inspect Andeo-managed Git and recent builds\n  source branches   List exact managed branches and default policy\n  source compare    Compare two managed branches\n  source connect    Connect this linked project to managed Git\n  source pull       Clone or fast-forward the exact connected repository\n  source token      Issue a short-lived repository credential\n  source push       Push the exact commit without persisting a token\n  source promote    Fast-forward the default after successful preview checks\n  source history    Run guarded, archived source-history migration\n  workflows         Inspect and control app-defined background runs\n  tail              Stream logs for one exact linked project\n  delivery status   Read preview workflow state\n  delivery retry    Retry a failed preview workflow\n  skill install     Install the Andeo agent skill\n  config example    Print the project configuration contract\n\nThere is intentionally no production publish command.\nRun andeo <command> --help for examples.`;
+    return `Andeo merchant developer CLI ${CLI_VERSION}\n\nCommands:\n  docs              Read version-matched offline guides\n  capabilities      Inspect scoped support, enablement and permissions\n  init              Create a new Shopify account starter\n  auth login        Create or refresh the default login\n  auth create       Create or re-authorize a named login\n  auth activate     Bind a named login to a directory tree\n  auth deactivate   Remove an exact directory binding\n  auth status       Validate one login or scoped credential\n  auth list         List local login profiles and bindings\n  auth delete       Revoke one named login\n  auth logout       Revoke the default or every login\n  link              Link this checkout to one permitted project\n  doctor            Check developer readiness\n  dev               Run the project-owned local dev command\n  check             Run project validation\n  build             Package and verify a portable artifact\n  upload            Retain a build for administrator publication\n  preview           Build and deploy an exact preview\n  preview entries   List eligible connected entry apps\n  preview open      Reopen an exact deployed preview\n  source status     Inspect Andeo-managed Git and recent builds\n  source branches   List exact managed branches and default policy\n  source compare    Compare two managed branches\n  source connect    Connect this linked project to managed Git\n  source pull       Clone or fast-forward the exact connected repository\n  source token      Issue a short-lived repository credential\n  source push       Push the exact commit without persisting a token\n  source promote    Fast-forward the default after successful preview checks\n  source history    Run guarded, archived source-history migration\n  workflows         Inspect and control app-defined background runs\n  vars              Manage saved per-environment runtime variables\n  source policy     Inspect or change automatic publication\n  tail              Stream logs for one exact linked project\n  delivery status   Read preview workflow state\n  delivery retry    Retry a failed preview workflow\n  skill install     Install the Andeo agent skill\n  config example    Print the project configuration contract\n\nThere is intentionally no production publish command.\nRun andeo <command> --help for examples.`;
 }
 function normalizeError(error) {
     if (error instanceof CliApiError) {