primitive-admin 1.1.0-alpha.8 → 1.1.0-alpha.80

package/dist/src/commands/functions.js

@@ -0,0 +1,672 @@
+/**
+ * `primitive functions` — server functions' read and operational verbs
+ * (#3179, project `server-functions`).
+ *
+ * A server function is the SIXTH status-carrying type (`docs/cli-design.md`,
+ * §Object availability): it exposes a public endpoint, so it carries
+ * `active | inactive | archived`, the `enable`/`disable` pair, and the
+ * `archive` spelling of the delete flow. It carries no `create`, `update` or
+ * `delete` verb — the function is authored in `functions/<key>.toml` beside the
+ * TypeScript its `entry` names, applied with `config push`, and prune-by-push
+ * stays the only CLI hard-delete path.
+ *
+ * The rule worth stating loudly here, because a function IS code on a public
+ * endpoint: a `config push` to a DISABLED function updates the code and leaves
+ * it out of service. `status` has one writer pair and push is not one of them
+ * (#2803's resurrection guard) — otherwise shipping a fix would silently put
+ * an endpoint an operator had taken down back in service.
+ */
+import { existsSync } from "fs";
+import { join } from "path";
+import { ApiClient } from "../lib/api-client.js";
+import { resolveAppId } from "../lib/config.js";
+import { resolveSyncDir } from "../lib/sync-paths.js";
+import { activeVersionMode } from "../lib/function-sync.js";
+import { FunctionSchemaCodegenError } from "../lib/function-schema-codegen.js";
+import { functionTypeWiringProblems, staleFunctionTypeArtifacts, writeFunctionTypeArtifacts, } from "../lib/function-db-types.js";
+import { success, error, info, warn, keyValue, result as printResult, formatTable, formatDate, formatStatus, json, jsonLine, divider, } from "../lib/output.js";
+import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { parseStatusFilter } from "../lib/object-status-filter.js";
+import { followLoop } from "../lib/watch.js";
+import { buildLogFollowSource } from "../lib/function-log-tail.js";
+import { toFunctionLogInspectionRow } from "../lib/log-inspection.js";
+/**
+ * How far back one `--follow` tick will page to meet its high-water mark.
+ *
+ * A bound on one CALL rather than "until you get there": the listing is
+ * newest-first, so an unbounded walk on a busy function would page through a
+ * whole window of history in one go. Ten pages at the default limit is 250
+ * invocations between polls — comfortably past what two seconds of an admitted
+ * caller can record. A tail that does fall behind carries its walk into the
+ * next call rather than skipping the gap (CR3287-017): the rows between the
+ * mark and now are all printed, in order, a bounded number of pages at a time.
+ */
+const FOLLOW_MAX_PAGES_PER_TICK = 10;
+/**
+ * One invocation, as a human reads it in the table — #3287.
+ *
+ * The FIRST error line only: a stack is eight kilobytes and a table row is
+ * one line, so the row says what happened and `--json` carries the rest.
+ */
+function firstErrorLine(row) {
+    const message = String(row?.errorMessage ?? "").trim();
+    if (message)
+        return message.split("\n")[0];
+    const stderr = Array.isArray(row?.stderr) ? row.stderr : [];
+    return stderr.length > 0 ? String(stderr[0].line ?? "") : "";
+}
+/** The same row, for the follow tail's one-line-per-invocation output. */
+function logRow(row) {
+    const when = row?.startedAt ? String(row.startedAt) : "";
+    const code = row?.errorCode ? `  ${row.errorCode}` : "";
+    const detail = firstErrorLine(row);
+    return `${when}  ${row?.status ?? ""}  ${row?.trigger?.kind ?? ""}  ${row?.runId || row?.invocationId || ""}${code}${detail ? `  ${detail}` : ""}`;
+}
+export function registerFunctionsCommands(program) {
+    const functions = program
+        .command("functions")
+        .description("Inspect and operate server functions")
+        .addHelpText("after", `
+Examples:
+  $ primitive config create function greet   # then edit functions/greet.toml and: primitive config push
+  $ primitive functions list
+  $ primitive functions get 01HXY...
+  $ primitive functions disable 01HXY...     # out of service; pushes still land
+  $ primitive functions archive 01HXY...     # retire it (soft delete)
+`);
+    // Configuration is authored in TOML and applied with `config push` (#2645):
+    // this group carries no config-setting flags, and the code the function runs
+    // is the TypeScript beside its file rather than anything a verb can send.
+    functions.addHelpText("after", `
+Configuration lives in functions/<key>.toml, and the code beside it:
+  $ primitive config fields function        # the file's keys, types and defaults
+  $ primitive config create function <key>  # scaffold one locally
+  $ primitive config set function/<key> <path>=<value>
+  $ primitive config push --only function/<key>
+`);
+    functions
+        .command("list")
+        .description("List server functions")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--status <status>", "Filter by status: active, inactive, archived")
+        .option("--json", "Output as JSON")
+        .action(async (appId, options) => {
+        const resolvedAppId = resolveAppId(appId, options);
+        const client = new ApiClient();
+        try {
+            const status = parseStatusFilter("functions", options.status, [
+                "active",
+                "inactive",
+                "archived",
+            ]);
+            // The admin listing drains `functionsByApp` server-side, so there is no
+            // cursor to follow and the filter is applied here.
+            const { items } = await client.listFunctions(resolvedAppId);
+            const filtered = status
+                ? (items || []).filter((f) => String(f.status ?? "active") === status)
+                : items || [];
+            if (options.json) {
+                json(filtered);
+                return;
+            }
+            if (filtered.length === 0) {
+                info("No functions found.");
+                return;
+            }
+            console.log(formatTable(filtered, [
+                { header: "KEY", key: "functionKey" },
+                { header: "ID", key: "functionId" },
+                { header: "STATUS", key: "status", format: formatStatus },
+                { header: "MODIFIED", key: "modifiedAt", format: formatDate },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    functions
+        .command("get")
+        .description("Get a server function, and the version it currently runs")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const record = await client.getFunction(resolvedAppId, functionId);
+            // The versions are append-only and nameless; `activeConfigId` is the
+            // only thing that says which one runs, so a listing without it would
+            // report the newest rather than the live one.
+            let active = null;
+            if (record?.activeConfigId) {
+                const { items } = await client.listFunctionConfigs(resolvedAppId, functionId);
+                active =
+                    (items || []).find((c) => String(c.configId) === String(record.activeConfigId)) ?? null;
+            }
+            if (options.json) {
+                json({ ...record, activeConfig: active });
+                return;
+            }
+            printResult("Function ID", record.functionId);
+            printResult("Key", record.functionKey);
+            printResult("Description", record.description || "-");
+            printResult("Status", formatStatus(record.status));
+            printResult("Access", record.access || "-");
+            printResult("Input Schema", record.inputSchema || "-");
+            printResult("Output Schema", record.outputSchema || "-");
+            divider();
+            info("Active version:");
+            if (!active) {
+                printResult("  Version", "none — no code has been pushed yet");
+            }
+            else {
+                printResult("  Config ID", active.configId);
+                printResult("  Entry", active.entry);
+                printResult("  Content Hash", active.contentHash || "-");
+                // #3281 — the mode words. A server that predates `mode` serializes
+                // only the `durable` column, which reads the same way.
+                printResult("  Mode", activeVersionMode(active));
+                printResult("  Limits", active.limits || "-");
+                // #3182 — what this version declared: since #3279 the egress
+                // allowlist, the secrets that may enter the sandbox and the
+                // high-blast opt-ins. Shown here because `functions get` is where an
+                // operator asks what a deployed function is configured to reach.
+                const capabilities = Array.isArray(active.capabilities)
+                    ? active.capabilities
+                    : [];
+                printResult("  Capabilities", capabilities.length > 0 ? capabilities.join(", ") : "-");
+            }
+            // #3181 — the ONE surface a function's triggers are visible on. The
+            // hidden `AppWebhook` and `CronTrigger` rows are omitted from
+            // `webhooks list`, `cron-triggers list` and `config pull` by design, so
+            // without this an operator could not find the receiver URL a provider
+            // must be pointed at, or the schedule the platform actually holds.
+            divider();
+            info("Triggers:");
+            const triggers = record.triggers ?? { webhook: null, cron: [] };
+            const cronEntries = Array.isArray(triggers.cron)
+                ? triggers.cron
+                : [];
+            // #3184 — the database types this function watches. A change trigger
+            // has no standalone surface at all (there is no `database-triggers
+            // list`), so this is the only place an operator can see that a write
+            // to a type runs this function. A server that predates #3184 sends no
+            // `databases` key, which reads as none.
+            const databaseEntries = Array.isArray(triggers.databases)
+                ? triggers.databases
+                : [];
+            if (!triggers.webhook &&
+                cronEntries.length === 0 &&
+                databaseEntries.length === 0) {
+                printResult("  Triggers", "none — this function is invoked over HTTP only");
+            }
+            if (triggers.webhook) {
+                printResult("  Webhook", triggers.webhook.webhookId);
+                printResult("    URL", triggers.webhook.url || "-");
+                printResult("    Scheme", triggers.webhook.verificationScheme || "-");
+                printResult("    Status", formatStatus(triggers.webhook.status));
+                printResult("    Signing Secret", triggers.webhook.signingSecret || "-");
+                printResult("    Last Triggered", triggers.webhook.lastTriggeredAt
+                    ? formatDate(triggers.webhook.lastTriggeredAt)
+                    : "never");
+            }
+            if (cronEntries.length > 0) {
+                console.log(formatTable(cronEntries, [
+                    { header: "NAME", key: "name" },
+                    { header: "ID", key: "triggerId" },
+                    { header: "CRON", key: "cron" },
+                    { header: "TZ", key: "timezone" },
+                    { header: "STATUS", key: "status", format: formatStatus },
+                    { header: "NEXT FIRE", key: "nextFireAt", format: formatDate },
+                    { header: "FIRED", key: "firedCount" },
+                    { header: "LAST RUN", key: "lastTriggeredRunId" },
+                ]));
+            }
+            if (databaseEntries.length > 0) {
+                printResult("  Database changes", "a committed write to one of these types runs this function");
+                // A fire carries the rows of every change of the type (the intent's
+                // 2026-09-09 decision), so the row says which type and no more —
+                // the READ GRANTS column retired with the grant grammar (#3279).
+                console.log(formatTable(databaseEntries, [
+                    { header: "DATABASE TYPE", key: "databaseType" },
+                ]));
+            }
+            // #3187 / #3279 — the ACTIVE version's manifest: what it registered
+            // and what it TOUCHES, from the push-time collection. Documentation,
+            // never authorization — function code acts as the system, and this
+            // is what lets an operator see what a version reaches without opening
+            // the bundle (principle 8). A server that predates the manifest block
+            // sends only `queries`.
+            divider();
+            info("Manifest (documentation, not authorization):");
+            const manifest = record.manifest && typeof record.manifest === "object"
+                ? record.manifest
+                : { queries: Array.isArray(record.queries) ? record.queries : [] };
+            const queries = Array.isArray(manifest.queries) ? manifest.queries : [];
+            const models = Array.isArray(manifest.models) ? manifest.models : [];
+            const families = Array.isArray(manifest.families)
+                ? manifest.families
+                : [];
+            if (!record.manifest) {
+                printResult("  Manifest", "none recorded — this version was pushed without a manifest");
+            }
+            else {
+                printResult("  Models", (models.length > 0 ? models.join(", ") : "none named") +
+                    // The marker is the difference between "names none" and "names
+                    // these, and possibly more" (D3279-006).
+                    (manifest.dynamicModels === true
+                        ? " (+ a model name resolved at run time)"
+                        : ""));
+                printResult("  Families", families.length > 0 ? families.join(", ") : "none reached");
+            }
+            if (queries.length === 0) {
+                if (record.manifest)
+                    printResult("  Queries", "none registered");
+            }
+            else {
+                console.log(formatTable(queries, [
+                    { header: "NAME", key: "name" },
+                    { header: "KIND", key: "kind" },
+                    {
+                        header: "MODELS",
+                        key: "models",
+                        format: (value) => Array.isArray(value) && value.length > 0 ? value.join(", ") : "-",
+                    },
+                    {
+                        header: "SCOPED",
+                        key: "callerScoped",
+                        format: (value) => (value ? "$caller" : "no"),
+                    },
+                    {
+                        header: "CACHE",
+                        key: "cache",
+                        format: (value) => (value ? `${value.ttlMs}ms` : "off"),
+                    },
+                ]));
+            }
+            divider();
+            printResult("Created", formatDate(record.createdAt));
+            printResult("Modified", formatDate(record.modifiedAt));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // #3181 — a trigger-fired invocation writes a run row, and a function run has
+    // no `workflowId`, so `primitive workflows runs` cannot see it. This verb is
+    // the only way to inspect what a webhook or a schedule actually did
+    // (principle 8).
+    functions
+        .command("runs")
+        .description("List a server function's runs, newest first")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--limit <n>", "Rows per page (default 25, max 100)")
+        .option("--cursor <cursor>", "Continue from a previous page")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const { items, nextCursor } = await client.listFunctionRuns(resolvedAppId, functionId, {
+                ...(options.limit ? { limit: Number(options.limit) } : {}),
+                ...(options.cursor ? { cursor: options.cursor } : {}),
+            });
+            if (options.json) {
+                json({ items, nextCursor });
+                return;
+            }
+            if (!items || items.length === 0) {
+                info("No runs found for this function.");
+                return;
+            }
+            console.log(formatTable(items, [
+                { header: "RUN ID", key: "runId" },
+                { header: "STATUS", key: "status", format: formatStatus },
+                { header: "FIRED BY", key: "initiatorKind" },
+                // #3280 — FIRED BY already said `function`; this is the half that
+                // makes it actionable, so a failed page leads back to the
+                // orchestrator that started it. Blank for a root.
+                { header: "PARENT", key: "parentFunctionKey" },
+                { header: "STARTED", key: "startedAt", format: formatDate },
+                { header: "ENDED", key: "endedAt", format: formatDate },
+                { header: "CODE", key: "errorCode" },
+            ]));
+            if (nextCursor) {
+                info(`More runs: --cursor ${nextCursor}`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // #3287 — the invocation logs. `runs` above answers what HAPPENED; this
+    // answers what the function PRINTED and what it threw, which is the thing
+    // an operator reaches for when a function is failing and the response says
+    // only that it did.
+    functions
+        .command("logs")
+        .description("List a server function's invocation logs, newest first")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--limit <n>", "Rows per page (default 25, max 100)")
+        .option("--cursor <cursor>", "Continue from a previous page")
+        .option("--follow", "Append new invocations as they are recorded (tail)")
+        .option("--interval <seconds>", "Poll interval for --follow (default 2)")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        const limit = options.limit ? Number(options.limit) : undefined;
+        // A cursor names a page in the PAST and a tail starts from now: serving
+        // both would mean guessing which the caller meant.
+        if (options.follow && options.cursor) {
+            error("--follow and --cursor cannot be combined; --follow tails from now.");
+            process.exit(1);
+        }
+        try {
+            if (options.follow) {
+                const intervalSeconds = options.interval ? Number(options.interval) : 2;
+                if (!Number.isFinite(intervalSeconds) || intervalSeconds <= 0) {
+                    error("--interval must be a positive number of seconds.");
+                    process.exit(1);
+                }
+                const controller = new AbortController();
+                const onSigint = () => controller.abort();
+                process.on("SIGINT", onSigint);
+                try {
+                    // The high-water mark is the newest `invocationId` already seen.
+                    // It is a ULID, so string order IS creation order and "newer than
+                    // this" is a comparison rather than a set of ids to remember.
+                    // The route answers NEWEST first, so a tick walks BACKWARD until
+                    // it meets the mark rather than reading one page and hoping
+                    // (CR3287-007). The walk is `buildLogFollowSource`, where it can
+                    // be put to a test without a server.
+                    const source = buildLogFollowSource(({ cursor }) => client.listFunctionLogs(resolvedAppId, functionId, {
+                        ...(limit ? { limit } : {}),
+                        ...(cursor ? { cursor } : {}),
+                    }), {
+                        idOf: (row) => String(row.invocationId),
+                        maxPagesPerTick: FOLLOW_MAX_PAGES_PER_TICK,
+                    });
+                    if (!options.json) {
+                        info("Following invocations (Ctrl-C to stop)…");
+                    }
+                    await followLoop(source, {
+                        intervalMs: intervalSeconds * 1000,
+                        signal: controller.signal,
+                        render: (items) => {
+                            if (options.json) {
+                                // One JSON object per line — a tail has no closing bracket
+                                // to wait for — each in the SHARED inspection item shape,
+                                // the same items the one-shot envelope carries.
+                                for (const row of items)
+                                    jsonLine(toFunctionLogInspectionRow(row));
+                                return;
+                            }
+                            for (const row of items)
+                                console.log(logRow(row));
+                        },
+                    });
+                }
+                finally {
+                    process.off("SIGINT", onSigint);
+                }
+                return;
+            }
+            const { items, nextCursor } = await client.listFunctionLogs(resolvedAppId, functionId, {
+                ...(limit ? { limit } : {}),
+                ...(options.cursor ? { cursor: options.cursor } : {}),
+            });
+            if (options.json) {
+                // The shared envelope, whose items are the shared inspection shape:
+                // a consumer classifies and pivots on `outcome`, `nativeStatus` and
+                // `correlation` without knowing which store answered (DSO3287-007).
+                json({
+                    items: items.map((row) => toFunctionLogInspectionRow(row)),
+                    hasMore: !!nextCursor,
+                    ...(nextCursor ? { nextCursor } : {}),
+                });
+                return;
+            }
+            if (!items || items.length === 0) {
+                info("No invocation logs found for this function.");
+                return;
+            }
+            console.log(formatTable(items.map((row) => ({
+                startedAt: row.startedAt,
+                status: row.status,
+                trigger: row.trigger?.kind ?? "",
+                // A trigger fire and a task run name their run; a request
+                // invocation's key is its own id.
+                runOrInvocation: row.runId || row.invocationId,
+                errorCode: row.errorCode ?? "",
+                firstError: firstErrorLine(row),
+            })), [
+                { header: "TIME", key: "startedAt", format: formatDate },
+                { header: "STATUS", key: "status", format: formatStatus },
+                { header: "TRIGGER", key: "trigger" },
+                { header: "RUN/INVOCATION ID", key: "runOrInvocation" },
+                { header: "CODE", key: "errorCode" },
+                { header: "ERROR", key: "firstError" },
+            ]));
+            if (nextCursor) {
+                info(`More logs: --cursor ${nextCursor}`);
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // #3182 — the typed handle's generated files, and the freshness question a
+    // CI job has to be able to ASK. `config push` writes them and `config diff`
+    // names the stale ones, but a diff exits 0 whatever it found, so a job that
+    // meant to fail on stale types passed and a declaration that disagreed with
+    // its schema reached the author as types that quietly lie (F3182-004). The
+    // verb and the flag are the two `databases codegen` and `workflows codegen`
+    // already use for exactly this.
+    functions
+        .command("codegen")
+        .allowExcessArguments(false)
+        .description("Write the generated files into the config tree's functions/ directory: the database-type declaration, the primitive-functions declaration, the functions declaration (<Key>Input/<Key>Output from each function's schemas), the per-function client invokers under generated/, and the tsconfig that wires the declarations into your editor. `config push` does this too; this is the standalone form, with a --check mode for CI.")
+        .option("--check", "Exit non-zero if the generated files are out of date or the tsconfig no longer loads them (CI guard); does not write.")
+        .option("-o, --out <dir>", "Directory for the per-function client invokers (default: <tree>/functions/generated/)")
+        .option("--json", "Output the result summary as JSON")
+        .action(async (options) => {
+        // A tree command: what it writes is the environment's own directory,
+        // which is the only directory it can be asked to write (#3154).
+        const configDir = resolveSyncDir();
+        if (!existsSync(configDir)) {
+            error(`Config directory not found: ${configDir}`);
+            process.exit(1);
+        }
+        if (!existsSync(join(configDir, "functions"))) {
+            // Nothing to type: the artifacts exist to serve function sources, and
+            // a tree with none needs no compiler wiring. Not a failure — a tree
+            // may legitimately have no functions.
+            if (options.json)
+                json({ ok: true, stale: [], problems: [] });
+            else
+                info(`No functions/ directory in ${configDir}; nothing to generate.`);
+            return;
+        }
+        // #3281 — the per-key client invokers go beside the declarations unless
+        // `-o` names another directory, the `workflows codegen` shape.
+        const artifactOptions = options.out ? { invokerDir: String(options.out) } : {};
+        // Wiring push cannot repair is checked alongside freshness: a tsconfig
+        // that carries comments is never rewritten, so it can be perfectly
+        // current and still load none of the declarations (CR3182-003).
+        let problems;
+        let stale = [];
+        try {
+            problems = functionTypeWiringProblems(configDir, artifactOptions);
+            if (options.check)
+                stale = staleFunctionTypeArtifacts(configDir, artifactOptions);
+        }
+        catch (err) {
+            // A malformed schema in a function file: nothing can be generated
+            // from it, and the message names the file.
+            if (!(err instanceof FunctionSchemaCodegenError))
+                throw err;
+            if (options.json)
+                json({ ok: false, stale: [], problems: [err.message] });
+            else
+                error(err.message);
+            process.exit(1);
+        }
+        if (options.check) {
+            if (stale.length === 0 && problems.length === 0) {
+                if (options.json)
+                    json({ ok: true, stale: [], problems: [] });
+                else
+                    success("Check passed: the function types are up to date.");
+                return;
+            }
+            if (options.json) {
+                json({ ok: false, stale, problems });
+            }
+            else {
+                error(`Check failed: ${stale.length} file(s) out of date` +
+                    (problems.length > 0
+                        ? `, ${problems.length} wiring problem(s).`
+                        : "."));
+                for (const relative of stale)
+                    error(`  out of date: ${relative}`);
+                for (const problem of problems) {
+                    error(`  functions/tsconfig.json: ${problem}`);
+                }
+                // Name the command that fixes what was just reported, keeping the
+                // options that decided WHERE it looked (#2911). The tree itself is
+                // no longer one of them (#3154) — only `-o` is left.
+                const regenerate = ["primitive functions codegen"];
+                if (options.out)
+                    regenerate.push(`-o ${options.out}`);
+                info(`Run \`${regenerate.join(" ")}\` to regenerate.`);
+            }
+            process.exit(1);
+        }
+        const written = writeFunctionTypeArtifacts(configDir, undefined, artifactOptions);
+        if (options.json) {
+            json({ written, problems });
+            return;
+        }
+        success(`Wrote ${written.length} file(s) into ${configDir}/functions/.`);
+        for (const relative of written)
+            keyValue("  wrote", relative);
+        for (const problem of problems) {
+            warn(`functions/tsconfig.json: ${problem}`);
+        }
+    });
+    // #2803 — the operational verb pair, and the only writers of `status` besides
+    // the delete flow. `config push` is deliberately not one: see the module note.
+    functions
+        .command("disable")
+        .description("Take a server function out of service now. Invocations are refused; the committed configuration and code are unchanged.")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.setFunctionAvailability(resolvedAppId, functionId, "disable");
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Function disabled: ${result.functionKey || functionId}`);
+            info("Invocations are refused. `primitive config push` still updates the code and leaves it out of service — `primitive functions enable` puts it back.");
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    functions
+        .command("enable")
+        .description("Put a server function back in service.")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.setFunctionAvailability(resolvedAppId, functionId, "enable");
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Function enabled: ${result.functionKey || functionId}`);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // #2907 — the delete flow's CLI spelling. The plain `DELETE` the server has
+    // always answered by writing the tombstone; not a second writer of `status`.
+    functions
+        .command("archive")
+        .description("Retire a server function (soft delete). Delete-lifecycle, not `disable`: the row is kept, goes on holding its key, and there is no un-archive.")
+        .argument("<function-id>", "Function ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+What archiving a function costs:
+  Invocations are refused, as they are for a disabled function.
+  The archived row still holds its key in the app's SINGLE key namespace — no
+  new function, workflow, script or webhook may take that key while it stands —
+  and pushing code to an archived function is refused.
+  \`primitive functions enable\` refuses an archived function; there is no
+  un-archive.
+
+Reclaiming the key means hard-deleting the row:
+  $ rm functions/<key>.toml
+  $ primitive config push --prune     # confirmed; hard-deletes the row, its
+                                      # versions and their stored bundles
+  # or hard-delete it in the console, then re-add the file and push.
+`)
+        .action(async (functionId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirmed;
+            try {
+                confirmed = await confirmPrompt(`Archive function ${functionId}? Invocations stop, the row keeps its ` +
+                    `key in the app's single key namespace, and there is no un-archive.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirmed) {
+                info("Cancelled.");
+                return;
+            }
+        }
+        const client = new ApiClient();
+        try {
+            // The soft delete: no `hard`, so the server writes the tombstone and
+            // keeps the reservation. Prune-by-push owns the hard path.
+            const result = await client.deleteFunction(resolvedAppId, functionId);
+            if (options.json) {
+                json(result);
+                return;
+            }
+            success(`Function archived: ${functionId}`);
+            info("Invocations are refused and pushes to it are rejected. The row still holds its key — reclaim it by removing its file and running a confirmed `primitive config push --prune`.");
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=functions.js.map