@wujiland/cli 0.0.0-stage → 1.0.1

package/dist/commands/ci.js

@@ -0,0 +1,289 @@
+// inca ci deploy: the deploy half of app CI (08-ci.md §6 steps 2–6). Reads the artifact the check job
+// built, selects secrets by declared name, asks GitHub for an OIDC token, POSTs to the broker's /deploy.
+// Secret values come only from INCA_SECRETS_JSON and are never printed (INCA-10, INCA-23).
+import { createHash } from "node:crypto";
+import { appendFile, lstat, readdir, readFile } from "node:fs/promises";
+import { extname, join, resolve, sep } from "node:path";
+import blake3 from "blake3-wasm";
+import { parseConfig, plan } from "@wujiland/config";
+import { CONFIG_FILE, formatErrors } from "../app.js";
+import { CliError, EXIT, envFlag, str, usage } from "../context.js";
+import { prefixFor } from "../github.js";
+import { parseHttpsUrl } from "../store.js";
+export const OIDC_AUDIENCE = "inca-deploy";
+// The broker's limit for the whole request (05-broker.md §5); checked here before an OIDC token is asked for.
+const MAX_BODY_BYTES = 20 * 1024 * 1024;
+// Wrangler's module types (05-broker.md §5); its default module rules map these extensions.
+const MODULE_TYPES = {
+    ".js": "application/javascript+module",
+    ".mjs": "application/javascript+module",
+    ".cjs": "application/javascript",
+    ".wasm": "application/wasm",
+    ".map": "application/source-map",
+    ".txt": "text/plain",
+    ".html": "text/plain",
+    ".sql": "text/plain",
+    ".bin": "application/octet-stream",
+};
+const ASSET_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".htm": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".json": "application/json",
+    ".txt": "text/plain; charset=utf-8",
+    ".md": "text/markdown; charset=utf-8",
+    ".csv": "text/csv; charset=utf-8",
+    ".xml": "application/xml",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".pdf": "application/pdf",
+    ".wasm": "application/wasm",
+    ".webmanifest": "application/manifest+json",
+    ".mp3": "audio/mpeg",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+};
+async function walk(root) {
+    const out = [];
+    for (const entry of await readdir(root, { recursive: true })) {
+        const st = await lstat(join(root, entry));
+        if (st.isFile())
+            out.push(entry);
+    }
+    return out.sort();
+}
+async function readTrimmed(dir, name) {
+    try {
+        return (await readFile(join(dir, name), "utf8")).trim();
+    }
+    catch {
+        throw new CliError(EXIT.NOT_FOUND, "ARTIFACT_INCOMPLETE", `The artifact has no ${name}.`, "The check job must write it (08-ci.md §5 step 9).");
+    }
+}
+/** Declared names only, this environment's prefix only; empty values are listed as missing (08-ci.md §6 step 3). */
+export function selectSecrets(declared, env, raw) {
+    let all = {};
+    if (raw !== undefined && raw.trim() !== "") {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new CliError(EXIT.REFUSED, "SECRETS_JSON_INVALID", "INCA_SECRETS_JSON is not JSON.");
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            throw new CliError(EXIT.REFUSED, "SECRETS_JSON_INVALID", "INCA_SECRETS_JSON is not a JSON object.");
+        all = parsed;
+    }
+    const secrets = {};
+    const missing = [];
+    for (const name of declared) {
+        const key = `${prefixFor(env)}${name}`;
+        const value = Object.hasOwn(all, key) ? all[key] : undefined;
+        if (typeof value === "string" && value !== "")
+            secrets[name] = value;
+        else
+            missing.push(name);
+    }
+    return { secrets, missing };
+}
+async function oidcToken(ctx) {
+    const url = ctx.deps.env.ACTIONS_ID_TOKEN_REQUEST_URL;
+    const bearer = ctx.deps.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+    if (!url || !bearer) {
+        throw new CliError(EXIT.AUTH, "OIDC_UNAVAILABLE", "GitHub offered no OIDC token request.", "The calling workflow needs permissions: id-token: write.");
+    }
+    const u = new URL(url);
+    u.searchParams.set("audience", OIDC_AUDIENCE);
+    let res;
+    try {
+        res = await ctx.deps.fetch(u, { redirect: "error", headers: { authorization: `bearer ${bearer}`, accept: "application/json" } });
+    }
+    catch (e) {
+        throw new CliError(EXIT.OUTSIDE, "OIDC_FAILED", `The OIDC token request failed: ${e.message}.`);
+    }
+    const body = (await res.json().catch(() => null));
+    if (!res.ok || typeof body?.value !== "string")
+        throw new CliError(EXIT.OUTSIDE, "OIDC_FAILED", `GitHub answered the OIDC token request with ${res.status}.`);
+    return body.value;
+}
+const names = (xs) => (xs && xs.length ? xs.map((x) => (typeof x === "string" ? x : JSON.stringify(x))).join(", ") : "none");
+/** Pending steps first, then the result (08-ci.md §6 step 5, §10 line 10). Names only, never values. */
+export function summary(env, r, pending) {
+    const lines = [];
+    if (pending.length) {
+        lines.push(`## PENDING — ${pending.length} step(s) still to do`, "");
+        for (const p of pending)
+            lines.push(`- **${p.kind}**: ${p.message}${p.next ? ` — next: \`${p.next}\`` : ""}`);
+        lines.push("");
+    }
+    if (!r.ok) {
+        lines.push(`## Deploy to ${env} refused`, "", `- code: \`${r.code ?? "UNKNOWN"}\``, `- message: ${r.message ?? ""}`, `- next: ${r.next ?? "none"}`, "");
+        return lines.join("\n");
+    }
+    lines.push(`## Deployed ${r.worker} (${env})`, "", "| | |", "|---|---|", `| Worker | ${r.worker} |`, `| Version | ${r.version_id} |`, `| URL | ${r.url} |`, `| Migrations applied | ${names(r.migrations_applied)} |`, `| Secrets written | ${names(r.secrets_written)} |`, `| Secrets pruned | ${names(r.secrets_pruned)} |`, `| Secrets missing | ${names(r.secrets_missing)} |`, `| Storage created | ${names(r.storage_created)} |`, `| Storage detached | ${names(r.storage_detached)} |`, "");
+    return lines.join("\n");
+}
+export async function ciDeploy(ctx) {
+    const { deps } = ctx;
+    const env = envFlag(ctx, { required: true });
+    const artifact = str(ctx.flags, "artifact");
+    if (artifact === undefined)
+        throw usage("Give --artifact <dir>.");
+    const rawBroker = str(ctx.flags, "broker");
+    if (rawBroker === undefined)
+        throw usage("Give --broker https://….");
+    const broker = parseHttpsUrl(rawBroker, "--broker");
+    const dir = resolve(deps.cwd, artifact);
+    const configText = await readFile(join(dir, CONFIG_FILE), "utf8").catch(() => {
+        throw new CliError(EXIT.NOT_FOUND, "ARTIFACT_INCOMPLETE", `The artifact has no ${CONFIG_FILE}.`);
+    });
+    let migrationNames = [];
+    try {
+        migrationNames = (await readdir(join(dir, "migrations"))).filter((f) => f.endsWith(".sql")).sort();
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    const parsed = parseConfig(configText, { migrationFiles: migrationNames });
+    if (!parsed.ok)
+        throw new CliError(EXIT.REFUSED, "CONFIG_INVALID", `The artifact's config is invalid:\n  ${formatErrors(parsed.errors).join("\n  ")}`, null, { errors: parsed.errors });
+    const config = parsed.value;
+    const planSha = await readTrimmed(dir, "plan_sha256");
+    const rendererVersion = await readTrimmed(dir, "renderer_version");
+    const mainModule = await readTrimmed(dir, "main_module");
+    const sha = deps.env.GITHUB_SHA;
+    const runId = deps.env.GITHUB_RUN_ID;
+    const runAttempt = deps.env.GITHUB_RUN_ATTEMPT;
+    if (!sha || !runId || !runAttempt)
+        throw usage("GITHUB_SHA, GITHUB_RUN_ID and GITHUB_RUN_ATTEMPT are not set: inca ci deploy runs inside GitHub Actions.");
+    const form = new FormData();
+    // A file part keeps the bytes; a string part would have its line ends turned into CRLF.
+    form.append("config", new Blob([configText], { type: "application/yaml" }), CONFIG_FILE);
+    form.append("env", env);
+    form.append("plan_sha256", planSha);
+    form.append("renderer_version", rendererVersion);
+    form.append("main_module", mainModule);
+    form.append("git", JSON.stringify({ sha, run_id: runId, run_attempt: runAttempt }));
+    const distDir = join(dir, "dist");
+    const modules = [];
+    for (const file of await walk(distDir).catch(() => [])) {
+        const name = file.split(sep).join("/");
+        // Wrangler writes a README.md of its own into --outdir; it is not a module.
+        if (name === "README.md")
+            continue;
+        const type = MODULE_TYPES[extname(name).toLowerCase()];
+        if (!type)
+            throw new CliError(EXIT.REFUSED, "MODULE_TYPE_UNKNOWN", `dist/${name} has no Worker module type.`, "Only .js .mjs .cjs .wasm .map .txt .html .sql .bin are sent.");
+        form.append("modules", new File([await readFile(join(distDir, file))], name, { type }));
+        modules.push(name);
+    }
+    if (!modules.length)
+        throw new CliError(EXIT.NOT_FOUND, "ARTIFACT_INCOMPLETE", "The artifact's dist/ holds no module.");
+    if (!modules.includes(mainModule))
+        throw new CliError(EXIT.REFUSED, "MAIN_MODULE_MISSING", `main_module ${mainModule} is not in dist/.`);
+    const migrations = [];
+    for (const name of migrationNames) {
+        const sql = await readFile(join(dir, "migrations", name), "utf8");
+        migrations.push({ name, sha256: createHash("sha256").update(sql, "utf8").digest("hex"), sql });
+    }
+    if (migrations.length)
+        form.append("migrations", JSON.stringify(migrations));
+    const assetsPlan = plan(config, env, { domain: "localhost", team: "" }).assets;
+    const assetPaths = [];
+    if (assetsPlan) {
+        const root = join(dir, assetsPlan.directory);
+        let files;
+        try {
+            files = await walk(root);
+        }
+        catch {
+            throw new CliError(EXIT.REFUSED, "ASSETS_MISSING", `The config declares assets in ${assetsPlan.directory}/, and the artifact has no such directory.`);
+        }
+        const manifest = {};
+        const parts = [];
+        for (const file of files) {
+            const path = `/${file.split(sep).join("/")}`;
+            // Wrangler's own metafiles; Inca does not apply _headers or _redirects, so it refuses them rather than drop them (P-10).
+            if (path === "/.assetsignore")
+                throw new CliError(EXIT.REFUSED, "ASSETS_IGNORE_UNSUPPORTED", ".assetsignore is not supported; keep ignored files out of the assets directory.");
+            if (path === "/_headers" || path === "/_redirects")
+                throw new CliError(EXIT.REFUSED, "ASSETS_META_UNSUPPORTED", `${path.slice(1)} is not applied by Inca; set headers and redirects in the Worker.`);
+            const bytes = await readFile(join(root, file));
+            if (bytes.byteLength > MAX_BODY_BYTES)
+                throw new CliError(EXIT.REFUSED, "BODY_TOO_LARGE", `${path} alone is over 20 MiB; media belongs in R2.`);
+            // Wrangler's asset hash: BLAKE3 over base64 content + extension, first 32 hex (cli.js hashFile).
+            const hash = blake3.hash(bytes.toString("base64") + extname(file).slice(1)).toString("hex").slice(0, 32);
+            manifest[path] = { hash, size: bytes.byteLength };
+            parts.push({ path, bytes });
+        }
+        form.append("assets_manifest", JSON.stringify(manifest));
+        for (const p of parts) {
+            form.append("asset", new File([p.bytes], p.path, { type: ASSET_TYPES[extname(p.path).toLowerCase()] ?? "" }));
+            assetPaths.push(p.path);
+        }
+    }
+    const { secrets, missing } = selectSecrets(config.secrets ?? [], env, deps.env.INCA_SECRETS_JSON);
+    if (Object.keys(secrets).length)
+        form.append("secrets", JSON.stringify(secrets));
+    for (const name of missing)
+        ctx.warn(`${name}: no ${prefixFor(env)}${name} value; not sent.`);
+    const total = [...form.values()].reduce((n, v) => n + (typeof v === "string" ? new TextEncoder().encode(v).byteLength : v.size), 0);
+    if (total > MAX_BODY_BYTES) {
+        throw new CliError(EXIT.REFUSED, "BODY_TOO_LARGE", `The deploy is ${(total / 1048576).toFixed(1)} MiB; the broker takes at most 20 MiB.`, "Move media to R2.");
+    }
+    const token = await oidcToken(ctx);
+    ctx.progress(`POST ${broker}/deploy: ${modules.length} module(s), ${assetPaths.length} asset(s), ${migrations.length} migration(s), secrets ${Object.keys(secrets).sort().join(", ") || "none"}.`);
+    let res;
+    try {
+        res = await deps.fetch(`${broker}/deploy`, { method: "POST", redirect: "error", headers: { authorization: `Bearer ${token}` }, body: form });
+    }
+    catch (e) {
+        throw new CliError(EXIT.OUTSIDE, "BROKER_UNREACHABLE", `The broker did not answer: ${e.message}.`);
+    }
+    const body = (await res.json().catch(() => null));
+    if (body === null)
+        throw new CliError(EXIT.OUTSIDE, "BROKER_NOT_JSON", `The broker answered ${res.status} without JSON.`);
+    const pending = [...(body.pending ?? [])];
+    const missingAll = [...new Set([...missing, ...(body.secrets_missing ?? [])])].sort();
+    for (const name of missingAll) {
+        pending.push({ kind: "secret-missing", message: `${name} has no ${prefixFor(env)}${name} value; the Worker keeps its old value or has none.`, next: `inca env push --env ${env}, then deploy again` });
+    }
+    const md = summary(env, body.ok ? { ...body, secrets_missing: missingAll } : body, pending);
+    const summaryFile = deps.env.GITHUB_STEP_SUMMARY;
+    if (summaryFile)
+        await appendFile(summaryFile, `${md}\n`);
+    if (!body.ok) {
+        throw new CliError(res.status >= 500 ? EXIT.OUTSIDE : EXIT.REFUSED, body.code ?? `HTTP_${res.status}`, body.message ?? `The broker refused (${res.status}).`, body.next ?? null);
+    }
+    return {
+        data: {
+            worker: body.worker,
+            version_id: body.version_id,
+            url: body.url,
+            migrations_applied: body.migrations_applied ?? [],
+            secrets_written: body.secrets_written ?? [],
+            secrets_missing: missingAll,
+            secrets_pruned: body.secrets_pruned ?? [],
+            storage_created: body.storage_created ?? [],
+            storage_detached: body.storage_detached ?? [],
+            modules,
+            assets: assetPaths,
+        },
+        human: md.split("\n"),
+        pending,
+        // A success with pending steps is green in CI; the list is at the top of the summary (08-ci.md §6 step 6).
+        exit: EXIT.OK,
+    };
+}

package/dist/commands/create.d.ts

@@ -0,0 +1,8 @@
+import type { Ctx, Outcome } from "../context.js";
+export declare const SLUG: RegExp;
+export declare const TEMPLATE = "inca-app-template";
+/** The SSH alias of inca-library/docs/REPOS.md, github.com-<account>; the alias sets the SSH user. */
+export declare const remoteUrl: (owner: string, repo: string) => string;
+export declare function checkSlug(slug: string): void;
+export declare function parseStorage(raw: string | undefined): Record<string, string[]>;
+export declare function create(ctx: Ctx): Promise<Outcome>;

package/dist/commands/create.js

@@ -0,0 +1,154 @@
+// inca create: validate, repo from the template, register and provision, push main and dev (06-cli.md §4, §8).
+// Resumable: every step first looks for its own result.
+import { access, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parseConfig, reservedReason } from "@wujiland/config";
+import { parseDocument } from "yaml";
+import { CONFIG_FILE, formatErrors } from "../app.js";
+import { CliError, EXIT, str, usage } from "../context.js";
+import { appRepo, firstLine, ghFor, git, gitOk } from "../github.js";
+import { managerClient } from "../manager.js";
+export const SLUG = /^[a-z0-9]([a-z0-9-]{0,40}[a-z0-9])?$/;
+export const TEMPLATE = "inca-app-template";
+const BINDING = /^[A-Z][A-Z0-9_]{0,62}$/;
+/** The SSH alias of inca-library/docs/REPOS.md, github.com-<account>; the alias sets the SSH user. */
+export const remoteUrl = (owner, repo) => `github.com-${owner}:${owner}/${repo}.git`;
+export function checkSlug(slug) {
+    if (!SLUG.test(slug) || slug.endsWith("-uat")) {
+        throw new CliError(EXIT.REFUSED, "SLUG_INVALID", `${JSON.stringify(slug)} is not a valid slug: lower-case letters, digits and hyphens, 1–42 characters, never ending -uat.`);
+    }
+    const reserved = reservedReason(slug);
+    if (reserved)
+        throw new CliError(EXIT.REFUSED, "SLUG_RESERVED", `${reserved}.`, "Choose another slug.");
+}
+export function parseStorage(raw) {
+    const out = {};
+    if (raw === undefined || raw === "")
+        return out;
+    for (const item of raw.split(",")) {
+        const [kind, binding, ...rest] = item.trim().split(":");
+        if (rest.length || !kind || !binding || !["d1", "kv", "r2"].includes(kind) || !BINDING.test(binding)) {
+            throw usage(`--storage takes kind:BINDING pairs (d1, kv, r2), for example d1:DB,r2:MEDIA; not ${JSON.stringify(item)}.`);
+        }
+        (out[kind] ??= []).push(binding);
+    }
+    return out;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** null when the repo does not exist; refuses one that was not made from the template (§8). */
+async function findRepo(gh, repo) {
+    const full = `${gh.owner}/${repo}`;
+    const view = await gh.run(["repo", "view", full, "--json", "name,templateRepository"]);
+    if (view.code !== 0) {
+        if (/could not resolve to a repository/i.test(view.stderr))
+            return null;
+        throw new CliError(EXIT.OUTSIDE, "GH_FAILED", `gh repo view ${full} exited ${view.code}: ${firstLine(view.stderr)}`);
+    }
+    const info = JSON.parse(view.stdout);
+    const t = info.templateRepository;
+    if (!t || t.name !== TEMPLATE || t.owner?.login !== gh.owner) {
+        throw new CliError(EXIT.REFUSED, "REPO_NOT_OURS", `${full} exists but was not made from ${gh.owner}/${TEMPLATE}; inca create never scaffolds over it.`, "Pick another slug, or remove that repository yourself.");
+    }
+    return { id: await repoId(gh, repo) };
+}
+async function repoId(gh, repo) {
+    const r = await gh.ok(["api", `repos/${gh.owner}/${repo}`, "--jq", ".id"]);
+    const id = r.stdout.trim();
+    if (!/^[0-9]+$/.test(id))
+        throw new CliError(EXIT.OUTSIDE, "GH_FAILED", `gh api did not return a numeric id for ${repo}.`);
+    return id;
+}
+export async function create(ctx) {
+    const { deps } = ctx;
+    const slug = ctx.positionals[0];
+    checkSlug(slug);
+    const description = str(ctx.flags, "description");
+    if (description === undefined || description.trim() === "")
+        throw usage('Give --description "…".');
+    const storage = parseStorage(str(ctx.flags, "storage"));
+    const m = await managerClient(deps);
+    const gh = await ghFor(deps, m.config.github_user);
+    const repo = appRepo(slug);
+    const full = `${gh.owner}/${repo}`;
+    const steps = [];
+    let found = await findRepo(gh, repo);
+    const today = new Date(deps.now()).toISOString().slice(0, 10);
+    const probe = `version: 1\nname: ${slug}\ndescription: ${JSON.stringify(description)}\ncompatibility_date: "${today}"\n`;
+    await m.call("POST", "/api/v1/apps", { slug, description, repository: full, repository_id: found?.id ?? "0", config: probe, dry_run: true });
+    if (!found) {
+        ctx.progress(`Creating ${full} from ${gh.owner}/${TEMPLATE}.`);
+        await gh.ok(["repo", "create", full, "--private", "--template", `${gh.owner}/${TEMPLATE}`, "--description", description]);
+        found = { id: await repoId(gh, repo) };
+        steps.push("repo created");
+    }
+    const dir = join(deps.cwd, repo);
+    if (await exists(dir)) {
+        const origin = await git(deps, dir, ["config", "--get", "remote.origin.url"]);
+        if (origin.code !== 0 || origin.stdout.trim() !== remoteUrl(gh.owner, repo)) {
+            throw new CliError(EXIT.REFUSED, "DIR_NOT_CLONE", `${dir} exists and is not a clone of ${full}.`, "Run inca create from another directory.");
+        }
+    }
+    else {
+        // GitHub fills a repo from a template a few seconds after creating it.
+        for (let attempt = 1;; attempt++) {
+            await gitOk(deps, deps.cwd, ["clone", remoteUrl(gh.owner, repo), repo]);
+            if (await exists(join(dir, CONFIG_FILE)))
+                break;
+            await rm(dir, { recursive: true, force: true });
+            if (attempt === 5)
+                throw new CliError(EXIT.OUTSIDE, "TEMPLATE_NOT_READY", `${full} still has no ${CONFIG_FILE} after ${attempt} clones.`, `Run inca create ${slug} again in a minute.`);
+            await deps.sleep(3000);
+        }
+        steps.push("cloned");
+    }
+    const configPath = join(dir, CONFIG_FILE);
+    const doc = parseDocument(await readFile(configPath, "utf8"), { uniqueKeys: true });
+    if (doc.get("name") !== slug) {
+        doc.set("name", slug);
+        doc.set("description", description);
+        if (Object.keys(storage).length)
+            doc.set("storage", doc.createNode(storage));
+        const text = String(doc);
+        const parsed = parseConfig(text);
+        if (!parsed.ok)
+            throw new CliError(EXIT.REFUSED, "CONFIG_INVALID", `The edited config is invalid:\n  ${formatErrors(parsed.errors).join("\n  ")}`, null, { errors: parsed.errors });
+        await writeFile(configPath, text);
+        const pkgPath = join(dir, "package.json");
+        if (await exists(pkgPath)) {
+            const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+            pkg.name = repo;
+            await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+        }
+        await gitOk(deps, dir, ["add", "--", CONFIG_FILE, ...((await exists(pkgPath)) ? ["package.json"] : [])]);
+        await gitOk(deps, dir, ["commit", "-m", `inca create ${slug}`]);
+        steps.push("config written");
+    }
+    const configText = await readFile(configPath, "utf8");
+    ctx.progress("Registering and provisioning with the manager.");
+    const reg = await m.call("POST", "/api/v1/apps", { slug, description, repository: full, repository_id: found.id, config: configText });
+    if (reg.status === "failed") {
+        throw new CliError(EXIT.OUTSIDE, "PROVISION_FAILED", `Provisioning ${slug} stopped: ${JSON.stringify(reg.failure)}.`, `inca create ${slug} again resumes from the failed step.`, { failure: reg.failure });
+    }
+    // Local main (the template plus the config commit), never HEAD: a resumed run cannot ship local dev.
+    // Not forced, so it only ever fast-forwards.
+    await gitOk(deps, dir, ["push", "origin", "refs/heads/main:refs/heads/main"]);
+    const dev = await gitOk(deps, dir, ["ls-remote", "--heads", "origin", "refs/heads/dev"]);
+    if (dev.stdout.trim() === "") {
+        await gitOk(deps, dir, ["push", "origin", "HEAD:refs/heads/dev"]);
+        steps.push("dev pushed");
+    }
+    await git(deps, dir, ["switch", "-c", "dev", "--track", "origin/dev"]);
+    const hosts = { prod: `${slug}.${m.domain}`, uat: `${slug}-uat.${m.domain}` };
+    return {
+        data: { slug, repository: full, repository_id: found.id, directory: dir, status: reg.status ?? null, hosts, steps },
+        human: [`${slug}: ${full}, ${reg.status ?? "registered"}.`, `Production: https://${hosts.prod}`, `UAT:        https://${hosts.uat}`, `Next: cd ${repo} && npm install && inca dev`],
+    };
+}

package/dist/commands/local.d.ts

@@ -0,0 +1,5 @@
+import type { Ctx, Outcome } from "../context.js";
+export declare function dev(ctx: Ctx): Promise<Outcome>;
+export declare function configCheck(ctx: Ctx): Promise<Outcome>;
+export declare function configRender(ctx: Ctx): Promise<Outcome>;
+export declare function envAdd(ctx: Ctx): Promise<Outcome>;

package/dist/commands/local.js

@@ -0,0 +1,185 @@
+// inca dev, inca config check|render, inca env add: the renderer run locally (02-renderer.md §3, §8).
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { RENDERER_VERSION, parseConfig, plan, planHash, toWranglerJsonc } from "@wujiland/config";
+import { isSeq, parseDocument } from "yaml";
+import { CONFIG_FILE, formatErrors, isTracked, loadApp, migrationFiles, readText, requireIgnored } from "../app.js";
+import { INSTALL, checkTool } from "../auth.js";
+import { CliError, EXIT, str, usage } from "../context.js";
+import { managerClient } from "../manager.js";
+import { parseHttpsUrl, parseManagerUrl, readCliConfig } from "../store.js";
+const WRANGLER = "wrangler.jsonc";
+const LOCAL_FACTS = { domain: "localhost", team: "local" };
+const HOSTNAME = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The domain is in no public package (INCA-33c): from --domain, else from the manager URL saved at login. */
+async function domainFor(ctx) {
+    const flag = str(ctx.flags, "domain");
+    if (flag !== undefined) {
+        if (!HOSTNAME.test(flag))
+            throw usage(`--domain ${JSON.stringify(flag)} is not a domain name.`);
+        return flag;
+    }
+    const c = await readCliConfig(ctx.deps);
+    if (c)
+        return parseManagerUrl(c.manager_url).domain;
+    throw usage("A build render needs the platform domain.", "Pass --domain <domain>, or run inca login first.");
+}
+export async function dev(ctx) {
+    const { deps } = ctx;
+    if (ctx.passthrough.some((a) => a === "--remote" || a.startsWith("--remote=") || a === "-r")) {
+        throw new CliError(EXIT.REFUSED, "REMOTE_REFUSED", "inca dev runs locally only; --remote would bind real resources.", "Deploy to UAT with inca deploy --env uat.");
+    }
+    const app = await loadApp(deps.cwd);
+    await requireIgnored(deps, deps.cwd, WRANGLER);
+    const p = plan(app.config, "local", LOCAL_FACTS);
+    await writeFile(join(deps.cwd, WRANGLER), toWranglerJsonc(p));
+    const local = join(deps.cwd, "node_modules", ".bin", "wrangler");
+    const wrangler = (await exists(local)) ? local : "wrangler";
+    await checkTool(deps, wrangler, ["--version"], INSTALL.wrangler);
+    ctx.progress(`Rendered ${WRANGLER} (local); starting wrangler dev.`);
+    const r = await deps.run(wrangler, ["dev", "-c", WRANGLER, ...ctx.passthrough], { cwd: deps.cwd, inherit: true });
+    return {
+        data: { worker: p.worker, wrangler_exit: r.code },
+        human: [`wrangler dev exited ${r.code}.`],
+        exit: r.code === 0 ? EXIT.OK : EXIT.OUTSIDE,
+    };
+}
+/** A wrangler.jsonc on disk must equal what this config renders in some mode (02-renderer.md §8). */
+function renders(config) {
+    return [toWranglerJsonc(plan(config, "local", LOCAL_FACTS)), toWranglerJsonc(plan(config, "uat", LOCAL_FACTS)), toWranglerJsonc(plan(config, "prod", LOCAL_FACTS))];
+}
+export async function configCheck(ctx) {
+    const { deps } = ctx;
+    const text = await readText(join(deps.cwd, CONFIG_FILE), CONFIG_FILE);
+    const migrations = await migrationFiles(deps.cwd);
+    const parsed = parseConfig(text, { migrationFiles: migrations });
+    const errors = parsed.ok ? [] : [...parsed.errors];
+    if (await isTracked(deps, deps.cwd, WRANGLER)) {
+        errors.push({ code: "WRANGLER_TRACKED", path: "", message: `${WRANGLER} is tracked by git; it is rendered and must never be committed (INCA-07). git rm --cached ${WRANGLER}` });
+    }
+    const onDisk = join(deps.cwd, WRANGLER);
+    if (parsed.ok && (await exists(onDisk)) && !renders(parsed.value).includes(await readFile(onDisk, "utf8"))) {
+        errors.push({ code: "WRANGLER_HAND_EDITED", path: "", message: `${WRANGLER} differs from a fresh render; delete it and let inca dev or CI render it.` });
+    }
+    const data = { file: CONFIG_FILE, errors };
+    const human = errors.length ? formatErrors(errors) : [`${CONFIG_FILE}: valid.`];
+    const pending = [];
+    if (ctx.flags.drift && parsed.ok) {
+        const m = await managerClient(deps);
+        const drift = [];
+        for (const env of ["uat", "prod"]) {
+            const local = planHash(plan(parsed.value, env, { domain: m.domain, team: "" }));
+            const r = await m.call("GET", `/api/v1/apps/${parsed.value.name}/deploys?env=${env}`);
+            const last = r.deploys.find((d) => d.result === "ok") ?? null;
+            const deployed = last?.plan_sha256 ?? null;
+            drift.push({ env, plan_sha256: local, deployed_plan_sha256: deployed, deployed_at: last?.at ?? null, drift: deployed !== local });
+            human.push(deployed === local ? `${env}: deployed config matches.` : `${env}: DRIFT — this config is not what was last deployed (${deployed ?? "never deployed"}).`);
+        }
+        data.drift = drift;
+    }
+    if (ctx.flags.contract && parsed.ok) {
+        const raw = str(ctx.flags, "broker") ?? (await readCliConfig(deps))?.broker_url;
+        if (raw === undefined)
+            throw usage("--contract needs the broker's URL.", "Pass --broker https://…, or save it with inca login --broker.");
+        const broker = parseHttpsUrl(raw, "--broker");
+        let contract;
+        try {
+            const res = await deps.fetch(`${broker}/contract`);
+            contract = (await res.json());
+        }
+        catch (e) {
+            throw new CliError(EXIT.OUTSIDE, "BROKER_UNREACHABLE", `The broker's /contract could not be read: ${e.message}.`);
+        }
+        if (!Array.isArray(contract.passthrough_keys))
+            throw new CliError(EXIT.OUTSIDE, "BROKER_SHAPE", "The broker's /contract has no passthrough_keys list.");
+        const allowed = new Set(contract.passthrough_keys);
+        for (const key of Object.keys(parsed.value.wrangler ?? {})) {
+            if (!allowed.has(key))
+                errors.push({ code: "CONTRACT_KEY_UNKNOWN", path: `/wrangler/${key}`, message: `The deployed broker (renderer ${String(contract.renderer_version)}) does not list ${key}; deploy the platform first.` });
+        }
+        data.contract = { broker, renderer_version: contract.renderer_version };
+        if (errors.length)
+            human.splice(0, human.length, ...formatErrors(errors));
+    }
+    if (errors.length) {
+        throw new CliError(EXIT.REFUSED, errors[0].code, `${errors.length} problem(s) in ${CONFIG_FILE}:\n  ${formatErrors(errors).join("\n  ")}`, null, { errors });
+    }
+    return { data, human, pending };
+}
+export async function configRender(ctx) {
+    const { deps } = ctx;
+    const mode = str(ctx.flags, "mode") ?? "local";
+    if (mode !== "local" && mode !== "build")
+        throw usage("--mode is local or build.");
+    const envRaw = str(ctx.flags, "env");
+    if (mode === "local" && envRaw !== undefined)
+        throw usage("--env applies to --mode build only; local takes the UAT shape.");
+    if (mode === "build" && envRaw !== "uat" && envRaw !== "prod")
+        throw usage("--mode build needs --env uat or --env prod.");
+    const app = await loadApp(deps.cwd);
+    const facts = mode === "local" ? LOCAL_FACTS : { domain: await domainFor(ctx), team: "" };
+    const p = plan(app.config, mode === "local" ? "local" : envRaw, facts);
+    const out = resolve(deps.cwd, str(ctx.flags, "out") ?? (mode === "build" ? ".inca" : "."));
+    await mkdir(out, { recursive: true });
+    const rendered = join(out, WRANGLER);
+    const rel = relative(deps.cwd, rendered);
+    if (!rel.startsWith(".."))
+        await requireIgnored(deps, deps.cwd, rel);
+    await writeFile(rendered, toWranglerJsonc(p));
+    const hash = planHash(p);
+    const files = [rendered];
+    if (mode === "build") {
+        await writeFile(join(out, "plan_sha256"), hash);
+        await writeFile(join(out, "renderer_version"), RENDERER_VERSION);
+        files.push(join(out, "plan_sha256"), join(out, "renderer_version"));
+    }
+    return {
+        data: { mode, env: p.env, worker: p.worker, plan_sha256: hash, renderer_version: RENDERER_VERSION, files },
+        human: [`Rendered ${rel} (${mode}, ${p.env}).`, `plan_sha256 ${hash}`, `renderer ${RENDERER_VERSION}`],
+    };
+}
+const ENV_NAME = /^(?!INCA_|CF_|CLOUDFLARE_|GITHUB_|UAT_|PROD_)[A-Z][A-Z0-9_]{0,62}$/;
+export async function envAdd(ctx) {
+    const name = ctx.positionals[0];
+    if (!ENV_NAME.test(name))
+        throw new CliError(EXIT.REFUSED, "SECRET_NAME_INVALID", `${name} is not a valid secret name (A–Z, 0–9, _; no INCA_, CF_, CLOUDFLARE_, GITHUB_, UAT_, PROD_ prefix).`);
+    const path = join(ctx.deps.cwd, CONFIG_FILE);
+    const before = await readText(path, CONFIG_FILE);
+    // Edits the YAML document, not the text, so comments and key order stay (06-cli.md §10 line 9).
+    const doc = parseDocument(before, { uniqueKeys: true });
+    if (doc.errors.length)
+        throw new CliError(EXIT.REFUSED, "CONFIG_PARSE", `${CONFIG_FILE} does not parse: ${doc.errors[0].message.split("\n")[0]}`);
+    const current = doc.get("secrets");
+    let added = true;
+    if (current === undefined || current === null) {
+        doc.set("secrets", doc.createNode([name]));
+    }
+    else if (isSeq(current)) {
+        if (current.items.some((i) => (typeof i === "object" && i !== null && "value" in i ? i.value : i) === name))
+            added = false;
+        else
+            current.add(doc.createNode(name));
+    }
+    else {
+        throw new CliError(EXIT.REFUSED, "CONFIG_SHAPE", "secrets: in the config is not a list.");
+    }
+    const after = String(doc);
+    const parsed = parseConfig(after, { migrationFiles: await migrationFiles(ctx.deps.cwd) });
+    if (!parsed.ok)
+        throw new CliError(EXIT.REFUSED, parsed.errors[0].code, `With ${name} the config would be invalid:\n  ${formatErrors(parsed.errors).join("\n  ")}`, null, { errors: parsed.errors });
+    if (added)
+        await writeFile(path, after);
+    return {
+        data: { name, added, secrets: parsed.value.secrets ?? [] },
+        human: [added ? `Declared ${name} in ${CONFIG_FILE}.` : `${name} was already declared.`, "Next: put its value in .env.inca.uat / .env.inca.prod, then inca env push --env <env>."],
+    };
+}

package/dist/commands/login.d.ts

@@ -0,0 +1,3 @@
+import type { Ctx, Outcome } from "../context.js";
+export declare function login(ctx: Ctx): Promise<Outcome>;
+export declare function whoami(ctx: Ctx): Promise<Outcome>;