@wujiland/cli 0.0.0-stage → 1.0.0

package/dist/commands/login.js

@@ -0,0 +1,59 @@
+// inca login, inca whoami (06-cli.md §3).
+import { fetchAccessToken, loadToken, readJwt, storeToken } from "../auth.js";
+import { CliError, EXIT, str, usage } from "../context.js";
+import { managerAccount, managerClient } from "../manager.js";
+import { GITHUB_USER, configPath, parseHttpsUrl, parseManagerUrl, readCliConfig, writeCliConfig } from "../store.js";
+import { CLI_VERSION } from "../version.js";
+import { SLUG } from "./create.js";
+const iso = (exp) => (exp === null ? null : new Date(exp * 1000).toISOString());
+export async function login(ctx) {
+    const { deps } = ctx;
+    const existing = await readCliConfig(deps);
+    const managerFlag = str(ctx.flags, "manager");
+    if (managerFlag === undefined && !existing)
+        throw usage("The first login names the manager.", "inca login --manager https://manager.<domain> --github-user <account>");
+    const { url, domain } = parseManagerUrl(managerFlag ?? existing.manager_url);
+    let githubUser = str(ctx.flags, "github-user") ?? existing?.github_user;
+    if (githubUser === undefined) {
+        const answer = await deps.prompt("GitHub account that owns the app repos: ");
+        if (answer === null)
+            throw usage("Name the GitHub account.", "inca login --github-user <account>");
+        githubUser = answer.trim();
+    }
+    if (!GITHUB_USER.test(githubUser))
+        throw usage(`${JSON.stringify(githubUser)} is not a GitHub account name.`);
+    const next = { ...(existing ?? {}), manager_url: url, github_user: githubUser };
+    const broker = str(ctx.flags, "broker");
+    if (broker !== undefined)
+        next.broker_url = parseHttpsUrl(broker, "--broker");
+    const infra = str(ctx.flags, "infra");
+    if (infra !== undefined)
+        next.infra_dir = infra;
+    const app = str(ctx.flags, "app");
+    if (app !== undefined && !SLUG.test(app))
+        throw usage(`${JSON.stringify(app)} is not an app slug.`);
+    const target = app === undefined ? url : `https://${app}.${domain}`;
+    // The keychain entry names the host, so a token is only ever loaded for the host it was issued for.
+    const account = `access:${new URL(target).hostname}`;
+    ctx.progress(`Signing in to ${target} through cloudflared (a browser opens).`);
+    const token = await fetchAccessToken(deps, target);
+    await storeToken(deps, account, token);
+    await writeCliConfig(deps, next);
+    const { exp } = readJwt(token);
+    return {
+        data: { manager: url, github_user: githubUser, signed_in_to: target, keychain: { service: "inca", account }, token_expires_at: iso(exp), cli_config: configPath(deps.home) },
+        human: [`Signed in to ${target}; token in the keychain (inca/${account}), expires ${iso(exp) ?? "unknown"}.`, `Manager: ${url}. GitHub account: ${githubUser}.`],
+    };
+}
+export async function whoami(ctx) {
+    const m = await managerClient(ctx.deps);
+    const who = await m.call("GET", "/api/v1/whoami");
+    const health = await m.call("GET", "/healthz");
+    const { exp } = readJwt(await loadToken(ctx.deps, managerAccount(m.url)));
+    if (typeof who.email !== "string")
+        throw new CliError(EXIT.OUTSIDE, "MANAGER_SHAPE", "whoami returned no email.");
+    return {
+        data: { email: who.email, token_expires_at: iso(exp), cli_version: CLI_VERSION, manager: m.url, manager_version: health.version, registry_schema: health.registry_schema },
+        human: [`${who.email} (token expires ${iso(exp) ?? "unknown"})`, `cli ${CLI_VERSION}, manager ${health.version} at ${m.url}`],
+    };
+}

package/dist/commands/ops.d.ts

@@ -0,0 +1,21 @@
+import type { Ctx, Outcome, Pending } from "../context.js";
+import type { ManagerClient } from "../manager.js";
+export type PendingRow = {
+    id: number;
+    app_slug: string;
+    worker_name: string | null;
+    kind: string;
+    detail: string;
+    opened_at: string;
+};
+export declare function pendingFrom(rows: PendingRow[]): Pending[];
+/** The slug from the argument, else from inca.config.yaml in this directory. */
+export declare function slugFrom(ctx: Ctx): Promise<string>;
+export declare function ls(ctx: Ctx): Promise<Outcome>;
+/** Declared secret names with no `<PREFIX>_<NAME>` GitHub secret, per environment (06-cli.md §5 warnings). */
+export declare function secretsWithoutValue(ctx: Ctx, m: ManagerClient, slug: string, declared: string[], envs: ("uat" | "prod")[]): Promise<Pending[]>;
+export declare function status(ctx: Ctx): Promise<Outcome>;
+export declare function versions(ctx: Ctx): Promise<Outcome>;
+export declare function rollback(ctx: Ctx): Promise<Outcome>;
+export declare function logs(ctx: Ctx): Promise<Outcome>;
+export declare function accessShow(ctx: Ctx): Promise<Outcome>;

package/dist/commands/ops.js

@@ -0,0 +1,178 @@
+// Commands that only read or act through the manager: ls, status, versions, rollback, logs, access show.
+import { access as fsAccess } from "node:fs/promises";
+import { join } from "node:path";
+import { plan, planHash } from "@wujiland/config";
+import { CONFIG_FILE, loadApp } from "../app.js";
+import { CliError, EXIT, confirmPlain, envFlag, str, usage } from "../context.js";
+import { appRepo, ghFor, prefixFor, secretNames } from "../github.js";
+import { managerClient } from "../manager.js";
+import { SLUG } from "./create.js";
+const NEXT = {
+    "access-apply": (r) => `Man Hay applies the Access change in inca-infra (inca access request ${r.app_slug} writes it), then inca status ${r.app_slug}`,
+    "access-removal": () => "Man Hay applies the Access removal in inca-infra",
+    "secret-missing": (r) => `inca env push --env ${r.worker_name?.endsWith("-uat") ? "uat" : "prod"}, then inca deploy`,
+    "migration-approval": (r) => `Approve the migration through the manager (POST /api/v1/apps/${r.app_slug}/migrations/approvals), then deploy again`,
+    "redeploy-for-audience": (r) => `inca deploy --env ${r.worker_name?.endsWith("-uat") ? "uat" : "prod"}`,
+};
+export function pendingFrom(rows) {
+    return rows.map((r) => {
+        let detail = r.detail;
+        try {
+            detail = JSON.parse(r.detail);
+        }
+        catch {
+            // detail stays the raw text
+        }
+        const d = detail;
+        const next = typeof d?.next === "string" ? d.next : (NEXT[r.kind]?.(r) ?? null);
+        const message = typeof d?.message === "string" ? d.message : `${r.kind} on ${r.worker_name ?? r.app_slug}: ${typeof r.detail === "string" ? r.detail : JSON.stringify(r.detail)}`;
+        return { kind: r.kind, message, next };
+    });
+}
+/** The slug from the argument, else from inca.config.yaml in this directory. */
+export async function slugFrom(ctx) {
+    const given = ctx.positionals[0];
+    if (given !== undefined) {
+        if (!SLUG.test(given))
+            throw usage(`${JSON.stringify(given)} is not an app slug.`);
+        return given;
+    }
+    try {
+        await fsAccess(join(ctx.deps.cwd, CONFIG_FILE));
+    }
+    catch {
+        throw usage("Name the app, or run this in its repository.");
+    }
+    return (await loadApp(ctx.deps.cwd)).config.name;
+}
+export async function ls(ctx) {
+    const m = await managerClient(ctx.deps);
+    const r = await m.call("GET", "/api/v1/apps");
+    return {
+        data: { apps: r.apps },
+        human: r.apps.length ? r.apps.map((a) => `${a.slug.padEnd(24)} ${a.status.padEnd(14)} pending ${a.pending}  ${a.description}`) : ["No apps."],
+    };
+}
+/** Declared secret names with no `<PREFIX>_<NAME>` GitHub secret, per environment (06-cli.md §5 warnings). */
+export async function secretsWithoutValue(ctx, m, slug, declared, envs) {
+    if (!declared.length)
+        return [];
+    const gh = await ghFor(ctx.deps, m.config.github_user);
+    const have = await secretNames(gh, appRepo(slug));
+    const out = [];
+    for (const env of envs) {
+        for (const name of declared) {
+            if (!have.has(`${prefixFor(env)}${name}`)) {
+                out.push({ kind: "secret-no-github-value", message: `${name} is declared but ${prefixFor(env)}${name} has no GitHub secret; the ${env} deploy will not write it.`, next: `inca env push --env ${env}` });
+            }
+        }
+    }
+    return out;
+}
+export async function status(ctx) {
+    const slug = await slugFrom(ctx);
+    const m = await managerClient(ctx.deps);
+    const r = await m.call("GET", `/api/v1/apps/${slug}`);
+    const local = ctx.positionals[0] === undefined ? await loadApp(ctx.deps.cwd) : null;
+    const human = [`${slug}: ${String(r.app.status)}`];
+    const drift = {};
+    for (const w of r.workers) {
+        const live = (w.live_versions ?? []).filter((v) => v.percentage > 0).map((v) => v.version_id);
+        const lastOk = r.deploys.find((d) => d.worker_name === w.name && d.result === "ok");
+        if (local)
+            drift[w.env] = lastOk ? lastOk.plan_sha256 !== planHash(plan(local.config, w.env, { domain: m.domain, team: "" })) : null;
+        human.push(`  ${w.name} (${w.hostname})`, `    live ${live.join(", ") || "none"}; last deploy ${w.last_deploy_at ?? "never"}${w.rollback_floor ? `; rollback floor ${w.rollback_floor}` : ""}`, `    access declared ${w.access.declared}, applied ${w.access.applied?.mode ?? w.access.applied?.error ?? "unknown"}${w.access.audience_stale ? " (AUDIENCE_STALE)" : ""}`, `    storage ${w.resources.map((x) => `${x.kind}:${x.binding}=${x.status}`).join(", ") || "none"}`, ...(drift[w.env] ? ["    DRIFT: this config differs from the last deploy"] : []));
+    }
+    const pending = pendingFrom(r.pending);
+    if (local)
+        pending.push(...(await secretsWithoutValue(ctx, m, slug, local.config.secrets ?? [], ["uat", "prod"])));
+    return { data: { slug, app: r.app, workers: r.workers, deploys: r.deploys, drift: local ? drift : null }, human, pending };
+}
+export async function versions(ctx) {
+    const slug = await slugFrom(ctx);
+    const env = envFlag(ctx, { required: false });
+    const m = await managerClient(ctx.deps);
+    const r = await m.call("GET", `/api/v1/apps/${slug}/versions?env=${env}`);
+    return {
+        data: { slug, env, ...strip(r) },
+        human: [
+            `${r.worker}: live ${r.live.join(", ") || "none"}${r.floor ? `; floor ${r.floor.version_id}` : ""}`,
+            ...r.versions.map((v) => `  ${r.live.includes(v.id) ? "*" : " "} ${v.id}  ${v.created_on ?? ""}${r.floor?.version_id === v.id ? "  (floor)" : ""}`),
+        ],
+    };
+}
+const strip = (r) => {
+    const { ok: _ok, ...rest } = r;
+    return rest;
+};
+export async function rollback(ctx) {
+    const slug = await slugFrom(ctx);
+    const env = envFlag(ctx, { required: true });
+    const m = await managerClient(ctx.deps);
+    let target = str(ctx.flags, "to");
+    if (target === undefined) {
+        const r = await m.call("GET", `/api/v1/apps/${slug}/versions?env=${env}`);
+        const sorted = [...r.versions].sort((a, b) => (b.created_on ?? "").localeCompare(a.created_on ?? ""));
+        const at = sorted.findIndex((v) => v.id === r.live[0]);
+        const prev = at >= 0 ? sorted[at + 1] : undefined;
+        if (!prev)
+            throw new CliError(EXIT.NOT_FOUND, "NO_PREVIOUS_VERSION", `${r.worker} has no version before the live one.`);
+        target = prev.id;
+    }
+    await confirmPlain(ctx, `Roll ${slug} (${env}) back to ${target}?`);
+    const r = await m.call("POST", `/api/v1/apps/${slug}/rollback`, { env, version_id: target });
+    return { data: { slug, env, worker: r.worker, live: r.live, note: r.note }, human: [`${r.worker} now serves ${r.live}.`, ...(r.note ? [r.note] : [])] };
+}
+export async function logs(ctx) {
+    const slug = ctx.positionals[0];
+    if (!SLUG.test(slug))
+        throw usage(`${JSON.stringify(slug)} is not an app slug.`);
+    const env = envFlag(ctx, { required: false });
+    const follow = ctx.flags.follow === true;
+    if (follow && ctx.json)
+        throw usage("--follow streams; --json prints one document. Use one.");
+    const interval = Number(str(ctx.flags, "interval") ?? "15");
+    if (!Number.isFinite(interval) || interval < 5)
+        throw usage("--interval is at least 5 seconds.");
+    const m = await managerClient(ctx.deps);
+    const q = (since) => {
+        const p = new URLSearchParams({ env });
+        for (const k of ["since", "until", "level", "request"]) {
+            const v = k === "since" && since ? since : str(ctx.flags, k);
+            if (v !== undefined)
+                p.set(k, v);
+        }
+        return `/api/v1/apps/${slug}/logs?${p}`;
+    };
+    const first = await m.call("GET", q());
+    if (!follow) {
+        return { data: { slug, env, worker: first.worker, since: first.since, until: first.until, events: first.events }, human: first.events.map((e) => JSON.stringify(e)) };
+    }
+    for (const e of first.events)
+        ctx.deps.stdout(`${JSON.stringify(e)}\n`);
+    let since = first.until;
+    for (;;) {
+        await ctx.deps.sleep(interval * 1000);
+        const next = await m.call("GET", q(since));
+        for (const e of next.events)
+            ctx.deps.stdout(`${JSON.stringify(e)}\n`);
+        since = next.until;
+    }
+}
+export async function accessShow(ctx) {
+    const slug = await slugFrom(ctx);
+    const m = await managerClient(ctx.deps);
+    const r = await m.call("GET", `/api/v1/apps/${slug}/access`);
+    const pending = pendingFrom(r.pending);
+    const human = [];
+    for (const w of r.workers) {
+        const differs = w.declared !== w.applied.mode;
+        human.push(`${w.host}: declared ${w.declared}, applied ${w.applied.mode}${w.applied.bypass_paths.length ? ` (bypass ${w.applied.bypass_paths.join(", ")})` : ""}${differs ? "  DIFFERS" : ""}`);
+        if (w.audience_stale)
+            pending.push({ kind: "AUDIENCE_STALE", message: `${w.worker} carries an old Access audience.`, next: `inca deploy --env ${w.worker.endsWith("-uat") ? "uat" : "prod"}` });
+        if (differs && !r.pending.some((p) => p.kind === "access-apply" && p.worker_name === w.worker)) {
+            pending.push({ kind: "access-differs", message: `${w.host} is declared ${w.declared} but ${w.applied.mode} is applied.`, next: `inca access request ${slug}` });
+        }
+    }
+    return { data: { slug, workers: r.workers }, human, pending };
+}

package/dist/commands/ship.d.ts

@@ -0,0 +1,7 @@
+import type { Ctx, Outcome } from "../context.js";
+export declare function deploy(ctx: Ctx): Promise<Outcome>;
+export declare function promote(ctx: Ctx): Promise<Outcome>;
+/** NAME=value lines; `#` comments; optional quotes. Values are never echoed, even in an error. */
+export declare function parseEnvFile(text: string): Map<string, string>;
+export declare function envPush(ctx: Ctx): Promise<Outcome>;
+export declare function envLs(ctx: Ctx): Promise<Outcome>;

package/dist/commands/ship.js

@@ -0,0 +1,182 @@
+// inca deploy, promote, env push, env ls: Man Hay's own gh and git (INCA-27, 06-cli.md §4).
+import { readFile } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { loadApp, requireIgnored } from "../app.js";
+import { CliError, EXIT, envFlag, str } from "../context.js";
+import { appRepo, ghFor, git, gitOk, prefixFor, secretNames } from "../github.js";
+import { managerClient } from "../manager.js";
+import { requireCliConfig } from "../store.js";
+import { pendingFrom, secretsWithoutValue } from "./ops.js";
+const WORKFLOW = "ci.yml";
+const branchFor = (env) => (env === "uat" ? "dev" : "main");
+const workerFor = (slug, env) => (env === "uat" ? `${slug}-uat` : slug);
+const DOCS_ONLY = (path) => path.endsWith(".md") || path.startsWith("docs/") || path.startsWith("openspec/");
+async function findRun(ctx, gh, full, branch, event, since, sha) {
+    for (let attempt = 0; attempt < 20; attempt++) {
+        const r = await gh.ok(["run", "list", "-R", full, "--workflow", WORKFLOW, "--branch", branch, "--event", event, "--limit", "10", "--json", "databaseId,headSha,createdAt,url"]);
+        const runs = JSON.parse(r.stdout);
+        // A minute of slack for the gap between this machine's clock and GitHub's.
+        const hit = runs.find((x) => Date.parse(x.createdAt) >= since - 60_000 && (sha === null || x.headSha === sha));
+        if (hit)
+            return hit;
+        await ctx.deps.sleep(3000);
+    }
+    throw new CliError(EXIT.OUTSIDE, "RUN_NOT_FOUND", `No ${WORKFLOW} run on ${branch} appeared in a minute.`, `gh run list -R ${full}`);
+}
+/** Waits for the run, then reads what the manager recorded: pending steps make exit 6 (06-cli.md §7). */
+async function waitAndReport(ctx, gh, m, slug, env, run) {
+    const full = `${gh.owner}/${appRepo(slug)}`;
+    ctx.progress(`Watching ${run.url}`);
+    const watch = await gh.run(["run", "watch", String(run.databaseId), "-R", full, "--exit-status"], { inherit: !ctx.json });
+    if (watch.code !== 0) {
+        throw new CliError(EXIT.REFUSED, "CI_FAILED", `The ${WORKFLOW} run failed: a check, or the broker refused the deploy.`, `gh run view ${run.databaseId} -R ${full} --log-failed (the job summary has the broker's code)`, { run: run.url });
+    }
+    const worker = workerFor(slug, env);
+    const deploys = await m.call("GET", `/api/v1/apps/${slug}/deploys?env=${env}`);
+    const recorded = deploys.deploys.find((d) => d.sha === run.headSha && d.result === "ok") ?? null;
+    const app = await m.call("GET", `/api/v1/apps/${slug}`);
+    const pending = pendingFrom(app.pending.filter((p) => p.worker_name === null || p.worker_name === worker));
+    if (!recorded) {
+        pending.push({ kind: "not-deployed", message: `The run passed but no deploy of ${run.headSha.slice(0, 12)} to ${worker} is recorded (a docs-only change skips the deploy).`, next: `Check the job summary at ${run.url}` });
+    }
+    return { data: { run: run.url, sha: run.headSha, worker, version_id: recorded?.version_id ?? null }, pending };
+}
+export async function deploy(ctx) {
+    const env = envFlag(ctx, { required: true });
+    const app = await loadApp(ctx.deps.cwd);
+    const slug = app.config.name;
+    const m = await managerClient(ctx.deps);
+    const gh = await ghFor(ctx.deps, m.config.github_user);
+    const full = `${gh.owner}/${appRepo(slug)}`;
+    const pending = await secretsWithoutValue(ctx, m, slug, app.config.secrets ?? [], [env]);
+    for (const p of pending)
+        ctx.warn(p.message);
+    const branch = branchFor(env);
+    const started = ctx.deps.now();
+    await gh.ok(["workflow", "run", WORKFLOW, "--ref", branch, "-R", full]);
+    if (!ctx.flags.wait) {
+        return { data: { slug, env, branch, started: true }, human: [`Started ${WORKFLOW} on ${branch} for ${workerFor(slug, env)}.`, "inca deploy --wait shows the result."], pending };
+    }
+    const run = await findRun(ctx, gh, full, branch, "workflow_dispatch", started, null);
+    const r = await waitAndReport(ctx, gh, m, slug, env, run);
+    return { data: { slug, env, branch, ...r.data }, human: [`Deployed ${r.data.worker} (${String(r.data.version_id ?? "no version")}).`], pending: [...pending, ...r.pending] };
+}
+export async function promote(ctx) {
+    const { deps } = ctx;
+    const app = await loadApp(deps.cwd);
+    const slug = app.config.name;
+    await gitOk(deps, deps.cwd, ["fetch", "origin"]);
+    const anc = await git(deps, deps.cwd, ["merge-base", "--is-ancestor", "refs/remotes/origin/main", "refs/remotes/origin/dev"]);
+    if (anc.code === 1) {
+        throw new CliError(EXIT.REFUSED, "MAIN_NOT_ANCESTOR", "main has commits that dev lacks; promote only fast-forwards and never force-pushes.", "Bring those commits into dev (merge main into dev, push dev), then promote.");
+    }
+    if (anc.code !== 0)
+        throw new CliError(EXIT.OUTSIDE, "GIT_FAILED", "git could not compare origin/main and origin/dev.");
+    const sha = (await gitOk(deps, deps.cwd, ["rev-parse", "refs/remotes/origin/dev"])).stdout.trim();
+    const mainSha = (await gitOk(deps, deps.cwd, ["rev-parse", "refs/remotes/origin/main"])).stdout.trim();
+    if (sha === mainSha)
+        return { data: { slug, promoted: false, sha }, human: ["main already equals dev; nothing to promote."] };
+    const changed = (await gitOk(deps, deps.cwd, ["diff", "--name-only", mainSha, sha])).stdout.split("\n").filter(Boolean);
+    if (changed.length && changed.every(DOCS_ONLY))
+        ctx.warn("Only *.md, docs/** or openspec/** changed: CI checks this push but does not deploy it.");
+    const started = deps.now();
+    await gitOk(deps, deps.cwd, ["push", "origin", "refs/remotes/origin/dev:refs/heads/main"]);
+    if (!ctx.flags.wait)
+        return { data: { slug, promoted: true, sha }, human: [`Promoted ${sha.slice(0, 12)} to main.`, "CI deploys it to production; inca status shows the result."] };
+    const m = await managerClient(deps);
+    const gh = await ghFor(deps, m.config.github_user);
+    const run = await findRun(ctx, gh, `${gh.owner}/${appRepo(slug)}`, "main", "push", started, sha);
+    const r = await waitAndReport(ctx, gh, m, slug, "prod", run);
+    return { data: { slug, promoted: true, ...r.data }, human: [`Promoted and deployed ${r.data.worker} (${String(r.data.version_id ?? "no version")}).`], pending: r.pending };
+}
+/** NAME=value lines; `#` comments; optional quotes. Values are never echoed, even in an error. */
+export function parseEnvFile(text) {
+    const out = new Map();
+    text.split(/\r?\n/).forEach((raw, i) => {
+        const line = raw.trim();
+        if (line === "" || line.startsWith("#"))
+            return;
+        const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/.exec(line);
+        if (!m)
+            throw new CliError(EXIT.REFUSED, "ENV_FILE_INVALID", `Line ${i + 1} of the values file is not NAME=value.`);
+        let value = m[2].trim();
+        const q = value[0];
+        if ((q === '"' || q === "'") && value.length >= 2 && value.endsWith(q)) {
+            value = q === '"' ? value.slice(1, -1).replace(/\\n/g, "\n").replace(/\\"/g, '"').replace(/\\\\/g, "\\") : value.slice(1, -1);
+        }
+        else if (q === '"' || q === "'") {
+            throw new CliError(EXIT.REFUSED, "ENV_FILE_INVALID", `Line ${i + 1} of the values file has an unclosed quote.`);
+        }
+        if (out.has(m[1]))
+            throw new CliError(EXIT.REFUSED, "ENV_FILE_INVALID", `${m[1]} appears twice in the values file.`);
+        out.set(m[1], value);
+    });
+    return out;
+}
+export async function envPush(ctx) {
+    const { deps } = ctx;
+    const env = envFlag(ctx, { required: true });
+    const app = await loadApp(deps.cwd);
+    const file = resolve(deps.cwd, str(ctx.flags, "from") ?? `.env.inca.${env}`);
+    const rel = relative(deps.cwd, file);
+    const outside = rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+    if (!outside)
+        await requireIgnored(deps, deps.cwd, rel);
+    const other = env === "prod" ? "uat" : "prod";
+    if (basename(file) === `.env.inca.${other}`) {
+        throw new CliError(EXIT.REFUSED, "ENV_FILE_MISMATCH", `${rel} holds ${other} values; refusing to store them as ${env === "prod" ? "PROD_" : "UAT_"}*.`);
+    }
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch {
+        throw new CliError(EXIT.NOT_FOUND, "FILE_NOT_FOUND", `No values file at ${rel}.`, `Create ${rel} (git-ignored) with NAME=value lines.`);
+    }
+    const values = parseEnvFile(text);
+    const declared = app.config.secrets ?? [];
+    for (const name of values.keys())
+        if (!declared.includes(name))
+            ctx.warn(`${name} is in ${rel} but not declared; not sent (inca env add ${name} declares it).`);
+    const c = await requireCliConfig(deps);
+    const gh = await ghFor(deps, c.github_user);
+    const full = `${gh.owner}/${appRepo(app.config.name)}`;
+    const set = [];
+    const missing = [];
+    for (const name of declared) {
+        const value = values.get(name);
+        if (value === undefined || value === "") {
+            missing.push(name);
+            continue;
+        }
+        await gh.ok(["secret", "set", `${prefixFor(env)}${name}`, "-R", full], { input: value });
+        set.push(`${prefixFor(env)}${name}`);
+    }
+    ctx.warn("Values are in GitHub; the Worker still has the old ones until you deploy.");
+    const pending = missing.map((n) => ({ kind: "secret-no-value", message: `${n} is declared but has no value in ${rel}.`, next: `Add ${n}=… to ${rel}, then inca env push --env ${env}` }));
+    return { data: { env, repository: full, set, missing }, human: [`Set ${set.length} secret(s) on ${full}: ${set.join(", ") || "none"}.`, `Deploy to apply: inca deploy --env ${env}`], pending };
+}
+export async function envLs(ctx) {
+    const env = envFlag(ctx, { required: false });
+    const app = await loadApp(ctx.deps.cwd);
+    const slug = app.config.name;
+    const m = await managerClient(ctx.deps);
+    const gh = await ghFor(ctx.deps, m.config.github_user);
+    const have = await secretNames(gh, appRepo(slug));
+    const last = await m.call("GET", `/api/v1/apps/${slug}/env?env=${env}`);
+    const declared = app.config.secrets ?? [];
+    const rows = declared.map((name) => ({ name, github: have.has(`${prefixFor(env)}${name}`), written_at_last_deploy: last.written.includes(name) }));
+    const pending = rows
+        .filter((r) => !r.github)
+        .map((r) => ({ kind: "secret-no-github-value", message: `${r.name} has no ${prefixFor(env)}${r.name} GitHub secret.`, next: `inca env push --env ${env}` }));
+    const stale = last.written.filter((n) => !declared.includes(n));
+    return {
+        data: { env, worker: last.worker, secrets: rows, written_not_declared: stale },
+        human: [
+            `${last.worker}:`,
+            ...rows.map((r) => `  ${r.name.padEnd(28)} github ${r.github ? "yes" : "NO "}  written at last deploy ${r.written_at_last_deploy ? "yes" : "no"}`),
+            ...(stale.length ? [`  Written at the last deploy but no longer declared (the next deploy prunes them): ${stale.join(", ")}`] : []),
+        ],
+        pending,
+    };
+}

package/dist/context.d.ts

@@ -0,0 +1,83 @@
+export declare const EXIT: {
+    readonly OK: 0;
+    readonly UNEXPECTED: 1;
+    readonly USAGE: 2;
+    readonly AUTH: 3;
+    readonly NOT_FOUND: 4;
+    readonly REFUSED: 5;
+    readonly PENDING: 6;
+    readonly OUTSIDE: 7;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+export declare class CliError extends Error {
+    readonly exit: ExitCode;
+    readonly code: string;
+    readonly next: string | null;
+    readonly detail: Record<string, unknown>;
+    constructor(exit: ExitCode, code: string, message: string, next?: string | null, detail?: Record<string, unknown>);
+}
+export declare const usage: (message: string, next?: string | null) => CliError;
+export type RunOptions = {
+    cwd?: string;
+    /** The child's whole environment; omitted means the parent's. */
+    env?: Record<string, string | undefined>;
+    /** Written to the child's stdin; never on the command line. */
+    input?: string;
+    /** Hand the terminal to the child (wrangler dev, gh run watch). */
+    inherit?: boolean;
+};
+export type RunResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+/** Always an argument array, never a shell string. Throws TOOL_MISSING (exit 7) when the program is absent. */
+export type Runner = (cmd: string, args: string[], opts?: RunOptions) => Promise<RunResult>;
+export type Deps = {
+    env: Readonly<Record<string, string | undefined>>;
+    cwd: string;
+    home: string;
+    platform: NodeJS.Platform;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    run: Runner;
+    fetch: typeof fetch;
+    /** A line typed at the terminal, or null when there is no terminal to ask. */
+    prompt: (question: string) => Promise<string | null>;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+};
+export type Pending = {
+    kind: string;
+    message: string;
+    next: string | null;
+};
+/** What a command hands back; main prints it as one JSON document or as human lines with PENDING last. */
+export type Outcome = {
+    data: Record<string, unknown>;
+    human: string[];
+    pending?: Pending[];
+    /** Overrides the default (6 when pending is non-empty, else 0). */
+    exit?: ExitCode;
+};
+export type Flags = Record<string, string | boolean | string[] | undefined>;
+export type Ctx = {
+    deps: Deps;
+    flags: Flags;
+    positionals: string[];
+    /** Arguments after `--` (inca dev). */
+    passthrough: string[];
+    json: boolean;
+    yes: boolean;
+    warn: (line: string) => void;
+    progress: (line: string) => void;
+};
+export declare function str(flags: Flags, name: string): string | undefined;
+export declare function list(flags: Flags, name: string): string[];
+export declare function envFlag(ctx: Ctx, opts: {
+    required: boolean;
+}): "uat" | "prod";
+/** A plain yes/no question; --yes answers it. Without a terminal and without --yes, refused. */
+export declare function confirmPlain(ctx: Ctx, question: string): Promise<void>;
+/** A typed confirmation; --yes never skips it (06-cli.md §10 line 12). */
+export declare function confirmTyped(ctx: Ctx, expected: string): Promise<void>;

package/dist/context.js

@@ -0,0 +1,63 @@
+// What every command gets: the outside world as injectable dependencies, and the exit codes of 06-cli.md §7.
+export const EXIT = {
+    OK: 0,
+    UNEXPECTED: 1,
+    USAGE: 2,
+    AUTH: 3,
+    NOT_FOUND: 4,
+    REFUSED: 5,
+    PENDING: 6,
+    OUTSIDE: 7,
+};
+export class CliError extends Error {
+    exit;
+    code;
+    next;
+    detail;
+    constructor(exit, code, message, next = null, detail = {}) {
+        super(message);
+        this.exit = exit;
+        this.code = code;
+        this.next = next;
+        this.detail = detail;
+    }
+}
+export const usage = (message, next = null) => new CliError(EXIT.USAGE, "USAGE", message, next);
+export function str(flags, name) {
+    const v = flags[name];
+    return typeof v === "string" ? v : undefined;
+}
+export function list(flags, name) {
+    const v = flags[name];
+    return Array.isArray(v) ? v : typeof v === "string" ? [v] : [];
+}
+export function envFlag(ctx, opts) {
+    const v = str(ctx.flags, "env");
+    if (v === undefined) {
+        if (opts.required)
+            throw usage("Say which environment: --env uat or --env prod.");
+        return "uat";
+    }
+    if (v !== "uat" && v !== "prod")
+        throw usage(`--env must be uat or prod, not ${JSON.stringify(v)}.`);
+    return v;
+}
+/** A plain yes/no question; --yes answers it. Without a terminal and without --yes, refused. */
+export async function confirmPlain(ctx, question) {
+    if (ctx.yes)
+        return;
+    const answer = await ctx.deps.prompt(`${question} [y/N] `);
+    if (answer === null)
+        throw new CliError(EXIT.REFUSED, "CONFIRMATION_REQUIRED", `${question} Not confirmed.`, "Run it again with --yes, or at a terminal.");
+    if (!/^y(es)?$/i.test(answer.trim()))
+        throw new CliError(EXIT.REFUSED, "CONFIRMATION_REFUSED", "Not confirmed; nothing was done.");
+}
+/** A typed confirmation; --yes never skips it (06-cli.md §10 line 12). */
+export async function confirmTyped(ctx, expected) {
+    const answer = await ctx.deps.prompt(`Type "${expected}" to confirm: `);
+    if (answer === null) {
+        throw new CliError(EXIT.REFUSED, "CONFIRMATION_REQUIRED", `This needs the typed confirmation "${expected}" at a terminal; --yes does not skip it.`);
+    }
+    if (answer.trim() !== expected)
+        throw new CliError(EXIT.REFUSED, "CONFIRMATION_MISMATCH", `You typed ${JSON.stringify(answer.trim())}, not "${expected}"; nothing was done.`);
+}

package/dist/github.d.ts

@@ -0,0 +1,16 @@
+import type { Deps, RunOptions, RunResult } from "./context.js";
+export type Gh = {
+    owner: string;
+    /** `gh <args>`; the caller names the repository explicitly (`-R`, a positional or an api path). */
+    run: (args: string[], opts?: Omit<RunOptions, "env">) => Promise<RunResult>;
+    /** Same, but a non-zero exit is an outside failure (7). */
+    ok: (args: string[], opts?: Omit<RunOptions, "env">) => Promise<RunResult>;
+};
+export declare const appRepo: (slug: string) => string;
+export declare function ghFor(deps: Deps, user: string): Promise<Gh>;
+export declare const firstLine: (s: string) => string;
+export declare function git(deps: Deps, cwd: string, args: string[], opts?: Omit<RunOptions, "cwd">): Promise<RunResult>;
+export declare function gitOk(deps: Deps, cwd: string, args: string[], opts?: Omit<RunOptions, "cwd">): Promise<RunResult>;
+/** Declared names present as `<PREFIX>_<NAME>` repository secrets. */
+export declare function secretNames(gh: Gh, repo: string): Promise<Set<string>>;
+export declare const prefixFor: (env: "uat" | "prod") => "UAT_" | "PROD_";