primitive-admin 1.2.0-alpha.1 → 1.2.0-alpha.11

package/dist/src/commands/functions.js

@@ -16,18 +16,21 @@
  * (#2803's resurrection guard) — otherwise shipping a fix would silently put
  * an endpoint an operator had taken down back in service.
  */
-import { existsSync, readdirSync } from "fs";
+import { existsSync, readdirSync, readFileSync } from "fs";
 import { join, relative as relativePath } from "path";
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
 import { resolveSyncDir } from "../lib/sync-paths.js";
+import { requireCurrentEnvironment } from "../lib/env-resolver.js";
+import { AUTH_CASE_FILE_SUFFIX, authFixturesPathFor, readAuthFixtures, } from "../lib/auth-fixtures.js";
+import { caseFilesInTree, caseSummary, checkRequestBody, exitCodeForCheck, judgeCase, parseAuthorizeCaseFile, parseRuntimeFlag, parseTriggerFlag, renderCaseTable, renderCheckLine, resolveAliases, } from "../lib/function-authorize-check.js";
 import { FunctionSchemaCodegenError, functionSchemaSources, } from "../lib/function-schema-codegen.js";
 import { functionTypeWiringProblems, staleFunctionTypeArtifacts, writeFunctionTypeArtifacts, } from "../lib/function-db-types.js";
 import { AGENT_CLIENT_FILE_SUFFIX, promptSchemaSources, treeDeclaresAgentPrompt, } from "../lib/prompt-schema-codegen.js";
 import { generateFunctionSwiftTypes } from "../lib/swift-codegen/functionGenerator.js";
 import { AGENT_SWIFT_FILE_SUFFIX } from "../lib/swift-codegen/agentGenerator.js";
 import { SwiftCodegenError } from "../lib/swift-codegen/schemaToSwift.js";
-import { success, error, info, warn, keyValue, result as printResult, formatTable, formatDate, formatStatus, json, jsonLine, divider, } from "../lib/output.js";
+import { success, error, info, warn, keyValue, result as printResult, formatTable, formatDate, formatDuration, formatStatus, json, jsonLine, divider, flushOutput, } from "../lib/output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import { FUNCTION_LOG_COLUMNS, functionLogCells, functionLogLine, } from "../lib/function-log-row.js";
 import { activatedLine, activationOutput, activationPrompt, activationRefusalLine, functionVersionRows, newerVersionLine, versionLine, } from "../lib/function-versions.js";
@@ -35,12 +38,14 @@ import { parseStatusFilter } from "../lib/object-status-filter.js";
 import { renderStepRunTable } from "../lib/step-run-table.js";
 import { triggerKindsCell, triggerTableRows, } from "../lib/function-trigger-listing.js";
 import { renderRunLogs } from "../lib/function-log-lines.js";
-import { buildWorkflowStepEnvelope } from "../lib/log-inspection.js";
+import { buildIntegrationEnvelope, buildWorkflowStepEnvelope, formatIntegrationStepCell, } from "../lib/log-inspection.js";
 import { followLoop } from "../lib/watch.js";
 import { buildLogFollowSource } from "../lib/function-log-tail.js";
 import { toFunctionLogInspectionRow } from "../lib/log-inspection.js";
-import { decidePageContinuation, describeIdentity, exitCodeForInvokeStatus, exitCodeForRunStatus, invokeIdLines, logsFlagConflict, refusalLines, renderIdLines, resolveRunFlags, runRuntimeCell, runSliceCells, runtimeForExecutionMode, resumeCommand, startIdLines, userTokenName, waitDelayMs, withMintedToken, EXIT_INTERRUPTED, EXIT_TIMED_OUT, USER_TOKEN_TTL, WAIT_DEFAULT_TIMEOUT_SECONDS, } from "../lib/function-run.js";
+import { decidePageContinuation, describeIdentity, exitCodeForInvokeStatus, exitCodeForRunStatus, invokeIdLines, logsFlagConflict, refusalLines, renderIdLines, resolveRunFlags, runRuntime, runRuntimeCell, runSliceCells, resumeCommand, startIdLines, userTokenName, waitDelayMs, withMintedToken, EXIT_INTERRUPTED, EXIT_TIMED_OUT, USER_TOKEN_TTL, WAIT_DEFAULT_TIMEOUT_SECONDS, } from "../lib/function-run.js";
 import { wholeListEnvelope } from "../lib/paginate.js";
+import { authorizeSection } from "../lib/function-authorize-view.js";
+import { registerFunctionTriggersCommands } from "./function-trigger-commands.js";
 /**
  * How far back one `--follow` tick will page to meet its high-water mark.
  *
@@ -126,10 +131,8 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                 info("No functions found.");
                 return;
             }
-            // #3690 — which functions a webhook or a schedule reaches, in one call.
-            // The standalone `webhooks list` and `cron-triggers list` hide the
-            // rows a function owns (#3181), so without this the only way to find
-            // an app's triggers was `functions get`, one function at a time.
+            // #3690 — which functions a webhook or a schedule reaches, in one call,
+            // rather than `functions get` one function at a time.
             console.log(formatTable(filtered.map((f) => ({
                 ...f,
                 triggersCell: triggerKindsCell(f.triggers),
@@ -241,6 +244,14 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                 printResult("  Config ID", active.configId);
                 printResult("  Entry", active.entry);
                 printResult("  Content Hash", active.contentHash || "-");
+                // #4717 — whether this version carries `authorize`, as the server's
+                // push probe recorded it. A legacy version runs the header's
+                // `access` rule above.
+                printResult("  Authorize", active.authorize === true ? "yes" : "no (legacy)");
+                // #4730 — what the push collected about it, from the manifest.
+                const section = authorizeSection(record.manifest && typeof record.manifest === "object" ? record.manifest : null, active.authorize === true);
+                for (const [label, value] of section ?? [])
+                    printResult(`    ${label}`, value);
                 // #3482 — no Mode line. The config says nothing about how a
                 // function runs: `invoke` runs it inside the request, `start` runs
                 // it as a task, and every function takes both.
@@ -276,22 +287,21 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                         ? documentSchemaModels.join(", ")
                         : "declares no models");
             }
-            // #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.
+            // #3181 — where an operator finds the receiver URL a provider must be
+            // pointed at, and the schedule the platform actually holds.
             divider();
             info("Triggers:");
             const triggers = record.triggers ?? { webhook: null, cron: [] };
             const cronEntries = Array.isArray(triggers.cron)
                 ? triggers.cron
                 : [];
+            // #4803 — the db3 types this function watches; absent when none.
+            const db3Entries = Array.isArray(triggers.db3) ? triggers.db3 : [];
             // #3483 — an OLDER server still answers a `databases` key, and this
             // command ignores it rather than branching on it: the trigger it
             // described was removed, so a section about it would tell an operator
             // that a write runs this function when nothing does.
-            if (!triggers.webhook && cronEntries.length === 0) {
+            if (!triggers.webhook && cronEntries.length === 0 && db3Entries.length === 0) {
                 printResult("  Triggers", "none — this function is invoked over HTTP only");
             }
             if (triggers.webhook) {
@@ -319,6 +329,21 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                     { header: "LAST RUN", key: "lastTriggeredRunId" },
                 ]));
             }
+            if (db3Entries.length > 0) {
+                info("DB3 TRIGGERS (one run per flush of a db3 of the type):");
+                console.log(formatTable(db3Entries, [
+                    { header: "TYPE", key: "type" },
+                    { header: "ID", key: "triggerId" },
+                    { header: "STATUS", key: "status", format: formatStatus },
+                    {
+                        header: "LAST FIRED",
+                        key: "lastTriggeredAt",
+                        format: (value) => (value ? formatDate(value) : "never"),
+                    },
+                    { header: "LAST RUN", key: "lastTriggeredRunId" },
+                    { header: "LAST ERROR", key: "lastError" },
+                ]));
+            }
             // #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
@@ -431,6 +456,9 @@ Configuration lives in functions/<key>.toml, and the code beside it:
                 { header: "ENVELOPE", key: "envelope" },
                 { header: "TRIGGERS", key: "triggers" },
                 { header: "BY", key: "by" },
+                // #4717 — last, so every column a reader already parses keeps
+                // its place.
+                { header: "AUTHORIZE", key: "authorize" },
             ]));
             if (nextCursor) {
                 info(`More versions: --cursor ${nextCursor}`);
@@ -526,7 +554,7 @@ What activating a version does, and does not:
             // empty string that sorts beside real ones.
             const withRuntime = (items ?? []).map((run) => ({
                 ...run,
-                runtime: runtimeForExecutionMode(run?.executionMode),
+                runtime: runRuntime(run),
             }));
             if (options.json) {
                 json({ items: withRuntime, nextCursor });
@@ -540,12 +568,13 @@ What activating a version does, and does not:
             // #3381, #3566 — flatten the slice record's two counts onto the
             // row for the REFRESHES and RESETS columns. One helper decides
             // both, so a row with no record gets a blank cell in each and a
-            // record with no count gets `0`.
+            // record with no count gets `0`. #3766 — and the LAST PROGRESS
+            // cell, from the same helper.
             items.map((run) => ({
                 ...run,
                 // #3482 — which RUNTIME this run used, from the row's own
-                // `executionMode`. One pure mapping, so the word an operator
-                // reads here is the word `ctx.runtime` gave the code.
+                // `runtime` (#3190). One reader, so the word an operator reads
+                // here is the word `ctx.runtime` gave the code.
                 runtime: runRuntimeCell(run),
                 ...runSliceCells(run),
             })), [
@@ -572,6 +601,11 @@ What activating a version does, and does not:
                 // step, so a run that reset and then COMPLETED carries no failure
                 // and no error code: this cell is the only place it shows.
                 { header: "RESETS", key: "resets" },
+                // #3766 — when the platform last saw this run's slice do
+                // anything: its open, a refresh, a park or a step boundary. A
+                // `running` run whose last progress is long past is the stalled
+                // one. Blank with no slice record.
+                { header: "LAST PROGRESS", key: "lastProgress" },
                 { header: "STARTED", key: "startedAt", format: formatDate },
                 { header: "ENDED", key: "endedAt", format: formatDate },
                 { header: "CODE", key: "errorCode" },
@@ -634,6 +668,53 @@ What activating a version does, and does not:
             process.exit(1);
         }
     });
+    // #3190 — the integration calls one run made. The run → integration-logs
+    // pivot was `workflows/runs/{runId}/integration-logs` on the admin API and
+    // had no CLI verb; a function run is addressed by the function that owns it,
+    // as `runs steps` is.
+    runs
+        .command("integration-logs")
+        .description("List the integration calls a function run made")
+        .argument("<function-id>", "Function ID")
+        .argument("<run-id>", "Run ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--limit <n>", "Number of calls to show (at most 200)", "100")
+        .option("--json", "Output as JSON")
+        .action(async (functionId, runId, _options, command) => {
+        // See `runs steps` above: `runs` parses its own `--app`/`--json` out of
+        // the argv before dispatching here, so the merged view is the real one.
+        const options = command.optsWithGlobals();
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const { items } = await client.listFunctionRunIntegrationLogs(resolvedAppId, functionId, runId, { limit: parseInt(options.limit, 10) });
+            if (options.json) {
+                json(buildIntegrationEnvelope(items));
+                return;
+            }
+            if (!items || items.length === 0) {
+                info("No integration calls found for this run.");
+                return;
+            }
+            const rows = items.map((log) => ({
+                ...log,
+                stepCell: formatIntegrationStepCell(log),
+            }));
+            console.log(formatTable(rows, [
+                { header: "TIME", key: "timestamp", format: formatDate },
+                { header: "INTEGRATION", key: "integrationKey", format: (v) => v || "" },
+                { header: "METHOD", key: "method" },
+                { header: "PATH", key: "path" },
+                { header: "STATUS", key: "status" },
+                { header: "DURATION", key: "durationMs", format: formatDuration },
+                { header: "STEP", key: "stepCell" },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
     // #3348 — end a run that will not settle.
     //
     // `client.functions.terminate` has existed in the SDK since #3186 and nothing
@@ -901,8 +982,8 @@ What activating a version does, and does not:
     // 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.
+    // verb and the flag are the ones `workflows codegen` already uses for
+    // exactly this.
     functions
         .command("codegen")
         .allowExcessArguments(false)
@@ -1081,6 +1162,8 @@ What activating a version does, and does not:
             warn(`functions/tsconfig.json: ${problem}`);
         }
     });
+    // #3190 — the operational verbs of a function's webhook and cron triggers.
+    registerFunctionTriggersCommands(functions);
     // #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
@@ -1387,10 +1470,6 @@ Reclaiming the key means hard-deleting the row:
             }
             const body = {
                 rootInput: flags.input,
-                // #3482 — `--as system` is the ONE door that is a single route for
-                // both runtimes, so it keeps the deprecated body selector; every
-                // other call says it with the route.
-                ...(identity.asSystem ? { mode: "task" } : {}),
                 ...(contextDocId ? { contextDocId } : {}),
                 ...(options.runKey ? { runKey: options.runKey } : {}),
             };
@@ -1455,6 +1534,200 @@ Reclaiming the key means hard-deleting the row:
             process.exit(1);
         }
     });
+    // ── authorize (#4732) ───────────────────────────────────────────────
+    //
+    // Runs a function's `authorize` alone, through the admin endpoint, so a
+    // gate can be checked without running the handler. The app, the fixture
+    // map and the case files all come from the one environment `--env`
+    // resolves, so the verb takes no `--app` (#3154's one-tree rule).
+    functions
+        .command("authorize")
+        .allowExcessArguments(false)
+        .description("Run only a function's authorize for a user, door, runtime and input, and print the decision; --cases runs its case file")
+        .argument("[key]", "Function key (as written in functions/<key>.toml)")
+        .option("--user <id>", "auth.user: an app user id or an @fixture alias (default: no user)")
+        .option("--role <role>", "Replace auth.user's role for the check; memberships stay the user's")
+        .option("--trigger <door>", "http (default), webhook, cron, manual, context, history, db3, function:<key>, tool[:<name>]")
+        .option("--runtime <runtime>", "request or task (default: the door's own)")
+        .option("--input <json>", "The input, as JSON; @fixture aliases resolve inside it (default {})")
+        .option("--cases", "Run the function's case file, functions/<key>.auth.json")
+        .option("--all", "With --cases, run every case file in the tree")
+        .option("--json", "Output as JSON")
+        .action(async (functionKey, options) => {
+        const refuse = (message) => {
+            error(message);
+            process.exit(2);
+        };
+        const singleFlags = ["user", "role", "trigger", "runtime", "input"].filter((flag) => options[flag] !== undefined);
+        if (options.all && !options.cases)
+            refuse("--all runs every case file: use it with --cases");
+        if (options.cases && singleFlags.length > 0) {
+            refuse(`--cases runs each case as its file states it: drop ${singleFlags.map((f) => `--${f}`).join(", ")}`);
+        }
+        if (options.all && functionKey)
+            refuse("--cases --all runs every case file: name no function with it");
+        if (!functionKey && !options.all) {
+            refuse(options.cases ? "Name the function whose case file to run, or use --all" : "Name the function to check");
+        }
+        let env;
+        let configDir;
+        try {
+            env = requireCurrentEnvironment();
+            configDir = resolveSyncDir();
+        }
+        catch (err) {
+            return refuse(err.message);
+        }
+        const appId = env.config.appId;
+        const fixturesPath = authFixturesPathFor(env);
+        const fixturesLabel = relativePath(env.projectRoot, fixturesPath);
+        const fixtures = readAuthFixtures(fixturesPath);
+        if (fixtures.ok === false)
+            return refuse(fixtures.error.replace(fixturesPath, fixturesLabel));
+        /** A case's or the flags' user and input, with the aliases resolved. */
+        const resolveSubject = (user, input) => {
+            const resolvedUser = resolveAliases(user, fixtures.fixtures, fixturesLabel, "user");
+            if (resolvedUser.ok === false)
+                return resolvedUser;
+            if (resolvedUser.value !== null && typeof resolvedUser.value !== "string") {
+                return { ok: false, error: `user ${user} must resolve to a user id or null in ${fixturesLabel}` };
+            }
+            const resolvedInput = resolveAliases(input, fixtures.fixtures, fixturesLabel, "$");
+            if (resolvedInput.ok === false)
+                return resolvedInput;
+            return { ok: true, user: resolvedUser.value, input: resolvedInput.value };
+        };
+        const client = new ApiClient();
+        if (!options.cases) {
+            const trigger = parseTriggerFlag(options.trigger ?? "http");
+            if (trigger.ok === false)
+                return refuse(trigger.error);
+            let runtime = null;
+            if (options.runtime !== undefined) {
+                const parsed = parseRuntimeFlag(options.runtime);
+                if (parsed.ok === false)
+                    return refuse(parsed.error);
+                runtime = parsed.runtime;
+            }
+            let input = {};
+            if (options.input !== undefined) {
+                try {
+                    input = JSON.parse(options.input);
+                }
+                catch {
+                    return refuse(`--input is not valid JSON: ${options.input}`);
+                }
+            }
+            const subject = resolveSubject(options.user ?? null, input);
+            if (subject.ok === false)
+                return refuse(subject.error);
+            let outcome;
+            try {
+                const target = await resolveFunctionByKey(client, appId, functionKey);
+                outcome = await client.authorizeFunction(appId, target.functionId, checkRequestBody({
+                    user: subject.user,
+                    role: options.role ?? null,
+                    trigger: trigger.trigger,
+                    runtime,
+                    input: subject.input,
+                }));
+            }
+            catch (err) {
+                return refuse(err.message);
+            }
+            const exitCode = exitCodeForCheck(outcome);
+            if (options.json) {
+                json({
+                    ...(outcome.httpStatus >= 400 ? { httpStatus: outcome.httpStatus } : {}),
+                    ...(outcome.body ?? {}),
+                    functionKey,
+                    exitCode,
+                });
+                await flushOutput();
+                process.exit(exitCode);
+            }
+            if (outcome.httpStatus >= 400) {
+                const body = outcome.body ?? {};
+                error(`${body.error ?? "The check was refused"}` +
+                    `${body.code ? ` (${body.code}${body.reason ? `, ${body.reason}` : ""})` : ""}`);
+                await flushOutput();
+                process.exit(exitCode);
+            }
+            console.log(renderCheckLine(outcome.body));
+            await flushOutput();
+            process.exit(exitCode);
+        }
+        // ── cases ──
+        const functionsDir = join(configDir, "functions");
+        const keys = options.all ? caseFilesInTree(functionsDir) : [functionKey];
+        if (keys.length === 0) {
+            if (options.json)
+                json({ items: [], passed: 0, failed: 0 });
+            else
+                console.log("No case files");
+            await flushOutput();
+            process.exit(0);
+        }
+        let listed;
+        try {
+            listed = (await client.listFunctions(appId)).items ?? [];
+        }
+        catch (err) {
+            return refuse(err.message);
+        }
+        const rows = [];
+        for (const key of keys) {
+            const filePath = join(functionsDir, `${key}${AUTH_CASE_FILE_SUFFIX}`);
+            const fileLabel = relativePath(env.projectRoot, filePath);
+            if (!existsSync(filePath))
+                refuse(`No case file ${fileLabel}`);
+            const parsed = parseAuthorizeCaseFile(readFileSync(filePath, "utf-8"), fileLabel);
+            if (parsed.ok === false) {
+                if (!options.all)
+                    refuse(parsed.error);
+                rows.push({ ...judgeCase(key, { name: "(case file)", expect: "-", code: null }, { error: parsed.error }) });
+                continue;
+            }
+            const match = listed.find((item) => String(item.functionKey ?? "").toLowerCase() === key.toLowerCase());
+            for (const testCase of parsed.cases) {
+                if (!match) {
+                    rows.push(judgeCase(key, testCase, { error: `no function '${key}' in this app` }));
+                    continue;
+                }
+                const subject = resolveSubject(testCase.user, testCase.input);
+                if (subject.ok === false) {
+                    rows.push(judgeCase(key, testCase, { error: `case "${testCase.name}": ${subject.error}` }));
+                    continue;
+                }
+                const trigger = parseTriggerFlag(testCase.trigger);
+                let outcome;
+                try {
+                    outcome = await client.authorizeFunction(appId, String(match.functionId), checkRequestBody({
+                        user: subject.user,
+                        role: testCase.role,
+                        trigger: trigger.ok ? trigger.trigger : { kind: "http" },
+                        runtime: testCase.runtime,
+                        input: subject.input,
+                    }));
+                }
+                catch (err) {
+                    outcome = { error: err.message };
+                }
+                rows.push(judgeCase(key, testCase, outcome));
+            }
+        }
+        const summary = caseSummary(rows);
+        if (options.json) {
+            json({ items: rows, passed: summary.passed, failed: summary.failed });
+        }
+        else {
+            console.log(renderCaseTable(rows, { withFunction: !!options.all }));
+            console.log(summary.line);
+        }
+        // A report past the pipe buffer is cut off by an exit that does not wait.
+        await flushOutput();
+        process.exit(summary.failed > 0 ? 1 : 0);
+    });
     runs
         .command("wait")
         .allowExcessArguments(false)