@wujiland/cli 0.0.0-stage → 1.0.1

package/dist/github.js

@@ -0,0 +1,63 @@
+// Man Hay's own `gh` and `git` (INCA-27). Each gh call gets a token for the named account in its own
+// environment only; the active gh account is never switched and the token is never kept (06-cli.md §4).
+import { INSTALL, checkTool } from "./auth.js";
+import { CliError, EXIT } from "./context.js";
+export const appRepo = (slug) => `inca-app-${slug}`;
+export async function ghFor(deps, user) {
+    await checkTool(deps, "gh", ["--version"], INSTALL.gh);
+    let token = null;
+    const getToken = async () => {
+        if (token !== null)
+            return token;
+        const r = await deps.run("gh", ["auth", "token", "--user", user]);
+        const t = r.stdout.trim();
+        if (r.code !== 0 || t === "") {
+            throw new CliError(EXIT.AUTH, "GH_NOT_LOGGED_IN", `gh has no login for ${user}.`, `gh auth login (as ${user}), then gh auth switch back to your usual account`);
+        }
+        token = t;
+        return t;
+    };
+    const run = async (args, opts = {}) => {
+        const env = { ...deps.env, GH_TOKEN: await getToken(), GH_PROMPT_DISABLED: "1" };
+        return deps.run("gh", args, { ...opts, env });
+    };
+    const ok = async (args, opts = {}) => {
+        const r = await run(args, opts);
+        if (r.code !== 0)
+            throw new CliError(EXIT.OUTSIDE, "GH_FAILED", `gh ${args.slice(0, 2).join(" ")} exited ${r.code}: ${firstLine(r.stderr)}`);
+        return r;
+    };
+    return { owner: user, run, ok };
+}
+export const firstLine = (s) => s.trim().split("\n")[0] ?? "";
+export async function git(deps, cwd, args, opts = {}) {
+    try {
+        return await deps.run("git", args, { ...opts, cwd });
+    }
+    catch (e) {
+        if (e instanceof CliError && e.code === "TOOL_MISSING")
+            throw new CliError(EXIT.OUTSIDE, "TOOL_MISSING", "git is not installed.", INSTALL.git);
+        throw e;
+    }
+}
+export async function gitOk(deps, cwd, args, opts = {}) {
+    const r = await git(deps, cwd, args, opts);
+    if (r.code !== 0)
+        throw new CliError(EXIT.OUTSIDE, "GIT_FAILED", `git ${args[0]} exited ${r.code}: ${firstLine(r.stderr)}`);
+    return r;
+}
+/** Declared names present as `<PREFIX>_<NAME>` repository secrets. */
+export async function secretNames(gh, repo) {
+    const r = await gh.ok(["secret", "list", "-R", `${gh.owner}/${repo}`, "--json", "name"]);
+    let list;
+    try {
+        list = JSON.parse(r.stdout);
+    }
+    catch {
+        throw new CliError(EXIT.OUTSIDE, "GH_FAILED", "gh secret list did not return JSON.");
+    }
+    if (!Array.isArray(list))
+        throw new CliError(EXIT.OUTSIDE, "GH_FAILED", "gh secret list did not return a list.");
+    return new Set(list.map((x) => x.name).filter((n) => typeof n === "string"));
+}
+export const prefixFor = (env) => (env === "uat" ? "UAT_" : "PROD_");

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { main, COMMANDS } from "./main.js";
+export { nodeDeps, runProcess } from "./node.js";
+export { EXIT, CliError } from "./context.js";
+export type { Deps, Outcome, Pending, RunOptions, RunResult, Runner } from "./context.js";
+export { CLI_VERSION } from "./version.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { main, COMMANDS } from "./main.js";
+export { nodeDeps, runProcess } from "./node.js";
+export { EXIT, CliError } from "./context.js";
+export { CLI_VERSION } from "./version.js";

package/dist/main.d.ts

@@ -0,0 +1,13 @@
+import type { ParseArgsConfig } from "node:util";
+import type { Ctx, Deps, Outcome } from "./context.js";
+type Options = NonNullable<ParseArgsConfig["options"]>;
+export type Command = {
+    options: Options;
+    /** [min, max] positional arguments. */
+    args: [number, number];
+    usage: string;
+    run: (ctx: Ctx) => Promise<Outcome>;
+};
+export declare const COMMANDS: Record<string, Command>;
+export declare function main(argv: string[], deps: Deps): Promise<number>;
+export {};

package/dist/main.js

@@ -0,0 +1,123 @@
+// Argument parsing, dispatch, and the output contract: --json prints exactly one JSON document on
+// stdout; progress and warnings go to stderr; exit codes per 06-cli.md §7.
+import { parseArgs } from "node:util";
+import { CliError, EXIT, usage } from "./context.js";
+import { accessRequest, decommission, purge } from "./commands/access.js";
+import { ciDeploy } from "./commands/ci.js";
+import { create } from "./commands/create.js";
+import { configCheck, configRender, dev, envAdd } from "./commands/local.js";
+import { login, whoami } from "./commands/login.js";
+import { accessShow, logs, ls, rollback, status, versions } from "./commands/ops.js";
+import { deploy, envLs, envPush, promote } from "./commands/ship.js";
+import { CLI_VERSION } from "./version.js";
+const s = { type: "string" };
+const b = { type: "boolean" };
+const many = { type: "string", multiple: true };
+// Only `login` has --manager (INCA-33): no other command can change where the CLI sends the token.
+export const COMMANDS = {
+    login: { options: { manager: s, "github-user": s, app: s, broker: s, infra: s }, args: [0, 0], usage: "inca login --manager https://manager.<domain> [--github-user <account>] [--app <slug>]", run: login },
+    whoami: { options: {}, args: [0, 0], usage: "inca whoami", run: whoami },
+    create: { options: { description: s, storage: s }, args: [1, 1], usage: 'inca create <slug> --description "…" [--storage d1:DB,r2:MEDIA]', run: create },
+    dev: { options: {}, args: [0, 0], usage: "inca dev [-- <wrangler args>]", run: dev },
+    "config check": { options: { drift: b, contract: b, broker: s }, args: [0, 0], usage: "inca config check [--drift] [--contract [--broker <url>]]", run: configCheck },
+    "config render": { options: { mode: s, env: s, out: s, domain: s }, args: [0, 0], usage: "inca config render [--mode local|build] [--env uat|prod] [--out <dir>] [--domain <domain>]", run: configRender },
+    deploy: { options: { env: s, wait: b }, args: [0, 0], usage: "inca deploy --env uat|prod [--wait]", run: deploy },
+    promote: { options: { wait: b }, args: [0, 0], usage: "inca promote [--wait]", run: promote },
+    status: { options: {}, args: [0, 1], usage: "inca status [<slug>]", run: status },
+    ls: { options: {}, args: [0, 0], usage: "inca ls", run: ls },
+    logs: { options: { env: s, since: s, until: s, level: s, request: s, follow: b, interval: s }, args: [1, 1], usage: "inca logs <slug> [--env] [--since] [--until] [--level] [--request] [--follow [--interval <s>]]", run: logs },
+    "env add": { options: {}, args: [1, 1], usage: "inca env add <NAME>", run: envAdd },
+    "env push": { options: { env: s, from: s }, args: [0, 0], usage: "inca env push --env uat|prod [--from <file>]", run: envPush },
+    "env ls": { options: { env: s }, args: [0, 0], usage: "inca env ls [--env uat|prod]", run: envLs },
+    "access show": { options: {}, args: [0, 1], usage: "inca access show [<slug>]", run: accessShow },
+    "access request": { options: { named: many, public: b, private: b, bypass: many, infra: s }, args: [1, 1], usage: "inca access request <slug> [--named <email>…] [--public] [--private] [--bypass <path>…] [--infra <dir>]", run: accessRequest },
+    versions: { options: { env: s }, args: [0, 1], usage: "inca versions [<slug>] [--env]", run: versions },
+    rollback: { options: { env: s, to: s }, args: [0, 1], usage: "inca rollback [<slug>] --env uat|prod [--to <version>]", run: rollback },
+    decommission: { options: { infra: s }, args: [1, 1], usage: "inca decommission <slug> [--infra <dir>]", run: decommission },
+    purge: { options: {}, args: [1, 1], usage: "inca purge <slug>", run: purge },
+    "ci deploy": { options: { artifact: s, env: s, broker: s }, args: [0, 0], usage: "inca ci deploy --artifact <dir> --env uat|prod --broker <url>", run: ciDeploy },
+};
+const GLOBAL = { json: b, quiet: b, yes: b, help: b };
+const GROUPS = new Set(["config", "env", "access", "ci"]);
+function helpText() {
+    return ["inca — the command line for the whole life of an Inca app.", "", ...Object.values(COMMANDS).map((c) => `  ${c.usage}`), "", "Global: --json --quiet --yes --help --version"].join("\n");
+}
+export async function main(argv, deps) {
+    const dash = argv.indexOf("--");
+    const head = dash === -1 ? argv : argv.slice(0, dash);
+    const passthrough = dash === -1 ? [] : argv.slice(dash + 1);
+    const json = head.includes("--json");
+    const quiet = head.includes("--quiet");
+    const errOut = (e) => {
+        if (json)
+            deps.stdout(`${JSON.stringify({ ok: false, code: e.code, message: e.message, next: e.next, ...e.detail })}\n`);
+        else
+            deps.stderr(`error ${e.code}: ${e.message}${e.next ? `\n  next: ${e.next}` : ""}\n`);
+        return e.exit;
+    };
+    try {
+        if (head[0] === "--version" || head[0] === "-v") {
+            deps.stdout(json ? `${JSON.stringify({ ok: true, version: CLI_VERSION })}\n` : `${CLI_VERSION}\n`);
+            return EXIT.OK;
+        }
+        const words = head.filter((a) => !a.startsWith("-"));
+        if (head.length === 0 || (words.length === 0 && head.includes("--help"))) {
+            deps.stdout(json ? `${JSON.stringify({ ok: true, usage: Object.values(COMMANDS).map((c) => c.usage) })}\n` : `${helpText()}\n`);
+            return head.length === 0 ? EXIT.USAGE : EXIT.OK;
+        }
+        const first = head[0];
+        const name = GROUPS.has(first) && head[1] !== undefined && !head[1].startsWith("-") ? `${first} ${head[1]}` : first;
+        const command = COMMANDS[name];
+        if (!command)
+            throw usage(`Unknown command ${JSON.stringify(name)}.`, "inca --help");
+        if (passthrough.length && name !== "dev")
+            throw usage("Only inca dev passes arguments after --.");
+        let parsed;
+        try {
+            parsed = parseArgs({ args: head.slice(name.split(" ").length), options: { ...GLOBAL, ...command.options }, allowPositionals: true, strict: true });
+        }
+        catch (e) {
+            throw usage(`${e.message}`, command.usage);
+        }
+        const { values, positionals } = parsed;
+        if (values.help) {
+            deps.stdout(json ? `${JSON.stringify({ ok: true, usage: command.usage })}\n` : `${command.usage}\n`);
+            return EXIT.OK;
+        }
+        const [min, max] = command.args;
+        if (positionals.length < min || positionals.length > max)
+            throw usage(`Wrong number of arguments.`, command.usage);
+        const ctx = {
+            deps,
+            flags: values,
+            positionals,
+            passthrough,
+            json,
+            yes: values.yes === true,
+            warn: (line) => deps.stderr(`warning: ${line}\n`),
+            progress: (line) => {
+                if (!quiet)
+                    deps.stderr(`${line}\n`);
+            },
+        };
+        const outcome = await command.run(ctx);
+        const pending = outcome.pending ?? [];
+        const exit = outcome.exit ?? (pending.length ? EXIT.PENDING : EXIT.OK);
+        if (json) {
+            deps.stdout(`${JSON.stringify({ ok: true, ...outcome.data, pending })}\n`);
+        }
+        else {
+            const lines = quiet ? [] : [...outcome.human];
+            for (const p of pending)
+                lines.push(`PENDING ${p.kind}: ${p.message}${p.next ? `\n  next: ${p.next}` : ""}`);
+            if (lines.length)
+                deps.stdout(`${lines.join("\n")}\n`);
+        }
+        return exit;
+    }
+    catch (e) {
+        if (e instanceof CliError)
+            return errOut(e);
+        return errOut(new CliError(EXIT.UNEXPECTED, "UNEXPECTED", `Unexpected failure: ${e.message ?? String(e)}`, "This is a bug in inca; report it with the command you ran."));
+    }
+}

package/dist/manager.d.ts

@@ -0,0 +1,10 @@
+import type { Deps } from "./context.js";
+import type { CliConfig } from "./store.js";
+export type ManagerClient = {
+    url: string;
+    domain: string;
+    config: CliConfig;
+    call: <T = Record<string, unknown>>(method: "GET" | "POST", path: string, body?: unknown) => Promise<T>;
+};
+export declare const managerAccount: (managerUrl: string) => string;
+export declare function managerClient(deps: Deps): Promise<ManagerClient>;

package/dist/manager.js

@@ -0,0 +1,51 @@
+// The manager's HTTP API (04-manager.md §6) with the owner's Access token in `cf-access-token`.
+import { loadToken } from "./auth.js";
+import { CliError, EXIT } from "./context.js";
+import { parseManagerUrl, requireCliConfig } from "./store.js";
+function exitFor(status, code) {
+    if (status === 401 || code === "NOT_OWNER")
+        return EXIT.AUTH;
+    if (status === 404)
+        return EXIT.NOT_FOUND;
+    if (status >= 500)
+        return EXIT.OUTSIDE;
+    return EXIT.REFUSED;
+}
+export const managerAccount = (managerUrl) => `access:${new URL(managerUrl).hostname}`;
+export async function managerClient(deps) {
+    const config = await requireCliConfig(deps);
+    const { url, domain } = parseManagerUrl(config.manager_url);
+    const token = await loadToken(deps, managerAccount(url));
+    const call = async (method, path, body) => {
+        let res;
+        try {
+            res = await deps.fetch(`${url}${path}`, {
+                method,
+                redirect: "manual",
+                headers: { "cf-access-token": token, accept: "application/json", ...(body === undefined ? {} : { "content-type": "application/json" }) },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            });
+        }
+        catch (e) {
+            throw new CliError(EXIT.OUTSIDE, "MANAGER_UNREACHABLE", `The manager did not answer: ${e.message}.`);
+        }
+        // Access answers an expired session with a redirect to its login page, not with JSON.
+        if (res.status >= 300 && res.status < 400)
+            throw new CliError(EXIT.AUTH, "ACCESS_SESSION", "Access wants a new sign-in.", "inca login");
+        let parsed;
+        try {
+            parsed = await res.json();
+        }
+        catch {
+            throw new CliError(res.status === 401 || res.status === 403 ? EXIT.AUTH : EXIT.OUTSIDE, "MANAGER_NOT_JSON", `The manager answered ${res.status} without JSON.`, res.status === 401 || res.status === 403 ? "inca login" : null);
+        }
+        const r = parsed;
+        if (r.ok !== true) {
+            const code = typeof r.code === "string" ? r.code : `HTTP_${res.status}`;
+            const { ok: _ok, code: _c, message: _m, next: _n, ...rest } = r;
+            throw new CliError(exitFor(res.status, code), code, typeof r.message === "string" ? r.message : `The manager refused (${res.status}).`, typeof r.next === "string" ? r.next : null, rest);
+        }
+        return parsed;
+    };
+    return { url, domain, config, call };
+}

package/dist/node.d.ts

@@ -0,0 +1,6 @@
+import type { Deps, RunOptions, RunResult } from "./context.js";
+export declare const childEnv: (env: Record<string, string | undefined>) => {
+    [k: string]: string;
+};
+export declare function runProcess(cmd: string, args: string[], opts?: RunOptions): Promise<RunResult>;
+export declare function nodeDeps(): Deps;

package/dist/node.js

@@ -0,0 +1,56 @@
+// The real outside world for bin.ts: child processes by argument array (never a shell), the terminal, fetch.
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { CliError, EXIT } from "./context.js";
+// The Access token and CI's secret values are for this process only; no child (gh, git, wrangler) gets them.
+const PRIVATE_ENV = new Set(["INCA_TOKEN", "INCA_SECRETS_JSON"]);
+export const childEnv = (env) => Object.fromEntries(Object.entries(env).filter((e) => e[1] !== undefined && !PRIVATE_ENV.has(e[0])));
+export function runProcess(cmd, args, opts = {}) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd,
+            env: childEnv(opts.env ?? process.env),
+            shell: false,
+            stdio: [opts.input !== undefined ? "pipe" : opts.inherit ? "inherit" : "ignore", opts.inherit ? "inherit" : "pipe", opts.inherit ? "inherit" : "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (d) => (stdout += d.toString("utf8")));
+        child.stderr?.on("data", (d) => (stderr += d.toString("utf8")));
+        child.on("error", (e) => {
+            if (e.code === "ENOENT")
+                reject(new CliError(EXIT.OUTSIDE, "TOOL_MISSING", `${cmd} is not installed.`));
+            else
+                reject(e);
+        });
+        child.on("close", (code) => resolvePromise({ code: code ?? 1, stdout, stderr }));
+        if (opts.input !== undefined)
+            child.stdin?.end(opts.input);
+    });
+}
+export function nodeDeps() {
+    return {
+        env: process.env,
+        cwd: process.cwd(),
+        home: homedir(),
+        platform: process.platform,
+        stdout: (t) => process.stdout.write(t),
+        stderr: (t) => process.stderr.write(t),
+        run: runProcess,
+        fetch: globalThis.fetch,
+        prompt: async (question) => {
+            if (!process.stdin.isTTY)
+                return null;
+            const rl = createInterface({ input: process.stdin, output: process.stderr });
+            try {
+                return await rl.question(question);
+            }
+            finally {
+                rl.close();
+            }
+        },
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        now: () => Date.now(),
+    };
+}

package/dist/store.d.ts

@@ -0,0 +1,18 @@
+import type { Deps } from "./context.js";
+export type CliConfig = {
+    manager_url: string;
+    github_user: string;
+    broker_url?: string;
+    infra_dir?: string;
+};
+export declare const configPath: (home: string) => string;
+/** `https://manager.<something>` and nothing else: no port, path, query, credentials (INCA-33). */
+export declare function parseManagerUrl(raw: string): {
+    url: string;
+    domain: string;
+};
+export declare function parseHttpsUrl(raw: string, what: string): string;
+export declare const GITHUB_USER: RegExp;
+export declare function readCliConfig(deps: Deps): Promise<CliConfig | null>;
+export declare function requireCliConfig(deps: Deps): Promise<CliConfig>;
+export declare function writeCliConfig(deps: Deps, c: CliConfig): Promise<void>;

package/dist/store.js

@@ -0,0 +1,83 @@
+// ~/.config/inca/cli.json: the manager address and the GitHub account, never a token (INCA-33, INCA-27).
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CliError, EXIT, usage } from "./context.js";
+export const configPath = (home) => join(home, ".config", "inca", "cli.json");
+/** `https://manager.<something>` and nothing else: no port, path, query, credentials (INCA-33). */
+export function parseManagerUrl(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw usage(`${JSON.stringify(raw)} is not a URL; give https://manager.<domain>.`);
+    }
+    const labels = u.hostname.split(".");
+    const ok = u.protocol === "https:" &&
+        u.port === "" &&
+        u.username === "" &&
+        u.password === "" &&
+        (u.pathname === "/" || u.pathname === "") &&
+        u.search === "" &&
+        u.hash === "" &&
+        labels[0] === "manager" &&
+        labels.length >= 3 &&
+        labels.every((l) => l !== "");
+    if (!ok)
+        throw usage(`The manager URL must be https://manager.<domain>, not ${JSON.stringify(raw)}.`);
+    return { url: `https://${u.hostname}`, domain: labels.slice(1).join(".") };
+}
+export function parseHttpsUrl(raw, what) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw usage(`${what} ${JSON.stringify(raw)} is not a URL.`);
+    }
+    if (u.protocol !== "https:" || u.username !== "" || u.password !== "" || u.search !== "" || u.hash !== "") {
+        throw usage(`${what} must be a plain https:// URL, not ${JSON.stringify(raw)}.`);
+    }
+    return u.origin + u.pathname.replace(/\/+$/, "");
+}
+export const GITHUB_USER = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;
+export async function readCliConfig(deps) {
+    let text;
+    try {
+        text = await readFile(configPath(deps.home), "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw e;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new CliError(EXIT.REFUSED, "CLI_CONFIG_INVALID", `${configPath(deps.home)} is not valid JSON.`, "Run inca login --manager https://manager.<domain> again.");
+    }
+    const r = raw;
+    if (typeof r.manager_url !== "string" || typeof r.github_user !== "string") {
+        throw new CliError(EXIT.REFUSED, "CLI_CONFIG_INVALID", `${configPath(deps.home)} lacks manager_url or github_user.`, "Run inca login again.");
+    }
+    // A hand-edited file is held to the same rule as the flag.
+    parseManagerUrl(r.manager_url);
+    if (!GITHUB_USER.test(r.github_user))
+        throw new CliError(EXIT.REFUSED, "CLI_CONFIG_INVALID", "github_user in cli.json is not a GitHub account name.");
+    return r;
+}
+export async function requireCliConfig(deps) {
+    const c = await readCliConfig(deps);
+    if (!c)
+        throw new CliError(EXIT.AUTH, "NOT_LOGGED_IN", "No manager is set.", "inca login --manager https://manager.<domain> --github-user <account>");
+    return c;
+}
+export async function writeCliConfig(deps, c) {
+    const dir = join(deps.home, ".config", "inca");
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const path = configPath(deps.home);
+    await writeFile(path, `${JSON.stringify(c, null, 2)}\n`, { mode: 0o600 });
+    await chmod(path, 0o600);
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const CLI_VERSION = "1.0.1";

package/dist/version.js

@@ -0,0 +1,2 @@
+// Equals cli/package.json "version"; a test keeps them in step.
+export const CLI_VERSION = "1.0.1";

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@wujiland/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "inca: the command line for the whole life of an Inca app.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "inca": "dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@wujiland/config": "1.0.0",
+    "blake3-wasm": "2.1.5",
+    "yaml": "2.9.1"
+  }
+}