primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/function-run.js

@@ -0,0 +1,389 @@
+/**
+ * Running a function from the CLI — the decisions, without the I/O (#3448,
+ * project `server-functions` phase 4).
+ *
+ * `functions invoke`, `functions start` and `functions runs wait` are three
+ * verbs over one route, and almost everything about them is a rule rather than
+ * a request: which flags may appear together, what `--input` means, which
+ * identity the call runs under, how long to wait between polls, which exit code
+ * a settled run earns, and what line to print beside each id so an operator
+ * knows the next command. Every one of those is decidable with no server, so
+ * every one of them lives here, where `cli-unit-tests` can pin it and a
+ * rejected checkpoint stays diagnosable (#3187's lesson).
+ */
+/** Exit codes, one place, because three verbs share them. */
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+/** The wait's budget was spent with the run still in flight. */
+export const EXIT_TIMED_OUT = 124;
+/** Ctrl-C — the workflows group's convention (`workflows.ts`). */
+export const EXIT_INTERRUPTED = 130;
+/**
+ * Read the flags, and refuse BEFORE any request is made.
+ *
+ * That ordering is the point (D3448-010): an operator who typed a malformed
+ * `--input` or two identities has made a mistake the platform should never see
+ * — and a refusal that arrived after the call would be a refusal for something
+ * that had already run.
+ */
+export function resolveRunFlags(flags) {
+    if (flags.user !== undefined && flags.as !== undefined) {
+        return {
+            ok: false,
+            error: "--user and --as system are mutually exclusive: --user runs as that app user, --as system runs with no caller at all.",
+        };
+    }
+    if (flags.as !== undefined && flags.as !== "system") {
+        return {
+            ok: false,
+            error: `--as accepts only 'system' (got '${flags.as}').`,
+        };
+    }
+    if (flags.user !== undefined && !String(flags.user).trim()) {
+        return { ok: false, error: "--user needs a user id." };
+    }
+    let input = {};
+    if (flags.input !== undefined) {
+        try {
+            // An explicit `null` stays `null` (D3281-SO-007): a schema-less function
+            // receives it, rather than the `{}` an absent flag means.
+            input = JSON.parse(flags.input);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: `--input is not valid JSON: ${err?.message ?? String(err)}`,
+            };
+        }
+    }
+    let timeoutSeconds = null;
+    if (flags.timeout !== undefined && flags.timeout !== null && flags.timeout !== "") {
+        const parsed = Number(flags.timeout);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            return {
+                ok: false,
+                error: `--timeout must be a positive number of seconds (got '${flags.timeout}').`,
+            };
+        }
+        timeoutSeconds = parsed;
+    }
+    const identity = flags.as === "system"
+        ? { kind: "system" }
+        : flags.user !== undefined
+            ? { kind: "user", userId: String(flags.user).trim() }
+            : { kind: "self" };
+    return { ok: true, input, identity, timeoutSeconds };
+}
+/**
+ * The runtime a function run used, read from the run row — #3482, C-6.
+ *
+ * `WorkflowRun.executionMode` is the runtime under the old word, and #3482
+ * does not rename a stored column (D3482-009; phase 7 owns the rename), so the
+ * mapping lives here, once, and every surface that says "runtime" says it the
+ * same way. `sync` is the request runtime — a webhook delivery, a
+ * `workflow.call` leaf — and `durable` is the task runtime.
+ *
+ * ABSENT means the task runtime, not "unknown": every writer of a durable row
+ * has written `durable` since #3186, and the rows that predate the column are
+ * durable runs. A row that says something else entirely is not a runtime this
+ * platform has, and answering null is how a reader learns that rather than
+ * being told a word that was never true.
+ */
+export function runtimeForExecutionMode(executionMode) {
+    if (executionMode === "sync")
+        return "request";
+    if (executionMode === "durable" || executionMode === undefined || executionMode === null) {
+        return "task";
+    }
+    return null;
+}
+/**
+ * The RUNTIME cell of one `functions runs` row.
+ *
+ * Blank rather than guessed for a row this reader cannot place: `runs` pages
+ * one function's own runs, but the same shape reaches the CLI from surfaces
+ * that carry DSL rows too, and printing `task` for one would be a word about
+ * something that has no runtime at all.
+ */
+export function runRuntimeCell(run) {
+    return runtimeForExecutionMode(run?.executionMode) ?? "";
+}
+/**
+ * The two slice cells of one `functions runs` row — REFRESHES and RESETS.
+ *
+ * One rule for both, because they are two facts about the same record and the
+ * distinction that matters is the same for each: a row with NO slice record
+ * gets a BLANK cell, and a record that carries no count gets `0`.
+ *
+ *   - blank means "there is no record" — a request invocation opens no lease,
+ *     and neither did any run that predates the record's own child;
+ *   - `0` means "the record says nothing happened", which for #3566 is the
+ *     answer an operator needs: a fabricated zero on a row with no record would
+ *     read as "the platform never reset this run", and the row cannot know that.
+ *
+ * A value that is not a whole number reads `0` rather than reaching the table:
+ * the cell is a count, and printing `NaN` or `two` in a column of numbers
+ * teaches an operator nothing.
+ */
+export function runSliceCells(run) {
+    const slice = run?.slice;
+    if (!slice || typeof slice !== "object")
+        return { refreshes: "", resets: "" };
+    const count = (value) => String(Number.isInteger(Number(value)) ? Number(value) : 0);
+    return { refreshes: count(slice.refreshCount), resets: count(slice.resets) };
+}
+// ─── waiting ────────────────────────────────────────────────────────
+/** The JS client's schedule: 400 ms doubling to a 5 s ceiling. */
+export const WAIT_INITIAL_DELAY_MS = 400;
+export const WAIT_MAX_DELAY_MS = 5_000;
+/** 15 minutes, the JS client's default. */
+export const WAIT_DEFAULT_TIMEOUT_SECONDS = 900;
+/**
+ * The delay before poll `attempt` (0-based).
+ *
+ * Pure and pinned, because a backoff that silently stopped backing off is a
+ * poll storm nobody notices until a long run is being asked 150 times a
+ * minute.
+ */
+export function waitDelayMs(attempt) {
+    const delay = WAIT_INITIAL_DELAY_MS * 2 ** Math.max(0, attempt);
+    return Math.min(delay, WAIT_MAX_DELAY_MS);
+}
+/**
+ * A settled run's exit code — D3448-010.
+ *
+ * `completed` is 0 and everything else an operator can act on is 1. An
+ * in-flight status is null: the wait has not finished, and turning "still
+ * running" into an exit code is how a script comes to believe a run failed
+ * because it was slow.
+ */
+export function exitCodeForRunStatus(status) {
+    switch (status) {
+        case "completed":
+            return EXIT_OK;
+        case "failed":
+        case "terminated":
+        case "missing":
+        case "skipped":
+            return EXIT_FAILED;
+        default:
+            return null;
+    }
+}
+/** A request invocation's exit code: only `completed` is success. */
+export function exitCodeForInvokeStatus(status) {
+    return status === "completed" ? EXIT_OK : EXIT_FAILED;
+}
+/**
+ * Every id a verb prints is followed by the diagnostics command that takes it
+ * — the issue's own requirement, and one pure function so it is pinned.
+ *
+ * An id with no next step is an id an operator has to go and look up how to
+ * use, which is the thing this issue exists to remove.
+ */
+export function invokeIdLines(args) {
+    const lines = [
+        {
+            label: "Function ID",
+            value: args.functionId,
+            commands: [`primitive functions logs ${args.functionId}`],
+        },
+    ];
+    if (args.invocationId) {
+        lines.push({
+            label: "Invocation ID",
+            value: args.invocationId,
+            commands: [
+                `primitive functions logs ${args.functionId} --invocation ${args.invocationId}`,
+            ],
+        });
+    }
+    return lines;
+}
+export function startIdLines(args) {
+    return [
+        {
+            label: "Run ID",
+            value: args.runId,
+            commands: [
+                `primitive functions runs steps ${args.functionId} ${args.runId}`,
+                `primitive functions runs terminate ${args.functionId} ${args.runId}`,
+                `primitive functions runs wait ${args.functionId} ${args.runId}`,
+            ],
+        },
+        {
+            label: "Function ID",
+            value: args.functionId,
+            commands: [`primitive functions logs ${args.functionId}`],
+        },
+    ];
+}
+/** The line a wait prints when it gives up, or is interrupted. */
+export function resumeCommand(functionId, runId) {
+    return `primitive functions runs wait ${functionId} ${runId}`;
+}
+/** Render one `IdLines` as the two-or-more lines an operator reads. */
+export function renderIdLines(lines) {
+    const out = [];
+    for (const line of lines) {
+        out.push(`${line.label} ${line.value}`);
+        for (const command of line.commands)
+            out.push(`  → ${command}`);
+    }
+    return out;
+}
+/** How the identity is reported, so an operator knows who ran it. */
+export function describeIdentity(identity) {
+    if (identity.kind === "system") {
+        return `Ran as system (manual, by ${identity.byUserId ?? "unknown"})`;
+    }
+    const role = identity.appRole ? ` (${identity.appRole})` : "";
+    return `Ran as ${identity.userId ?? "unknown"}${role}`;
+}
+// ─── the filtered listing's continuation rule ───────────────────────
+/**
+ * How many EMPTY pages carrying a cursor the CLI follows before it renders.
+ *
+ * D3448-SO-006's CLI half. A filtered page holding only other runs' records
+ * comes back empty WITH a cursor, which is an intermediate page and not the
+ * end; returning on it — as `functions logs` did — reports "no logs" for a run
+ * whose records are one page further down. The server's bounded scan makes
+ * that rare; this makes it impossible to read as the end.
+ */
+export const MAX_AUTO_CONTINUE_PAGES = 5;
+/**
+ * What to do with a page that came back holding nothing.
+ *
+ * A page with rows is rendered. An empty page with NO cursor is the end and is
+ * rendered too (the empty state). An empty page WITH a cursor is intermediate.
+ */
+export function decidePageContinuation(page, pagesFollowed) {
+    if ((page.items?.length ?? 0) > 0)
+        return { action: "render" };
+    const cursor = page.nextCursor;
+    if (!cursor)
+        return { action: "render" };
+    if (pagesFollowed >= MAX_AUTO_CONTINUE_PAGES) {
+        return { action: "exhausted", cursor };
+    }
+    return { action: "continue", cursor };
+}
+// ─── the `logs` flag combinations ───────────────────────────────────
+/**
+ * `--invocation` names ONE record, so every flag that shapes a LISTING is a
+ * contradiction beside it, and `--run` is a filter a tail cannot honour (the
+ * tail walks the whole index; a run's records are a bounded set that ends).
+ */
+export function logsFlagConflict(flags) {
+    if (flags.invocation) {
+        const conflicts = [
+            flags.run ? "--run" : null,
+            flags.follow ? "--follow" : null,
+            flags.cursor ? "--cursor" : null,
+            flags.limit !== undefined ? "--limit" : null,
+        ].filter(Boolean);
+        if (conflicts.length > 0) {
+            return `--invocation names one record, so it cannot be combined with ${conflicts.join(", ")}.`;
+        }
+        return null;
+    }
+    if (flags.run && flags.follow) {
+        return "--run and --follow cannot be combined: a run's records are a bounded set, and a tail walks the whole index.";
+    }
+    return null;
+}
+// ─── the `--user` credential ────────────────────────────────────────
+/** Ten minutes — long enough for the platform's own 30 s ceiling and no more. */
+export const USER_TOKEN_TTL = "10m";
+/** The name the minted token carries, so an operator can find it if it leaks. */
+export function userTokenName(verb, functionKey, at = new Date()) {
+    return `primitive functions ${verb} ${functionKey} ${at.toISOString()}`;
+}
+/** Ctrl-C, and the SIGTERM a supervisor sends, both end the process. */
+function installInterruptHandler(handler) {
+    process.on("SIGINT", handler);
+    process.on("SIGTERM", handler);
+    return () => {
+        process.off("SIGINT", handler);
+        process.off("SIGTERM", handler);
+    };
+}
+/**
+ * Mint, use, revoke — and revoke on EVERY exit path.
+ *
+ * The token is a real credential for ANOTHER USER, live for ten minutes, so
+ * "every exit path" has to include the one an operator actually takes when a
+ * call is slower than they expected: Ctrl-C. A `finally` alone does not cover
+ * it — with no handler installed, Node's default terminates the process and no
+ * `finally` in it ever runs (CR3448-001) — so the wrapper handles the signal
+ * itself, revokes, and only then exits 130.
+ *
+ * A failed revoke does NOT change the exit code — the invocation happened and
+ * its outcome is the answer — but it names the token and the command that
+ * revokes it, because an un-revoked credential an operator does not know about
+ * is worse than a warning they do (edge 32).
+ *
+ * The VALUE is never returned to the caller and never printed: `use` receives
+ * it, and nothing else does.
+ */
+export async function withMintedToken(effects, use) {
+    const minted = await effects.mint();
+    let revoked = false;
+    // Once, whichever path gets there first: an interrupt that lands while the
+    // answer is already on its way must not revoke a second time.
+    const revokeOnce = async () => {
+        if (revoked)
+            return;
+        revoked = true;
+        try {
+            await effects.revoke(minted.tokenId);
+        }
+        catch (err) {
+            effects.warn(`The temporary token for this call could not be revoked: ${minted.tokenId}. ` +
+                `Revoke it with 'primitive tokens revoke ${minted.tokenId}'. ` +
+                `(${err?.message ?? String(err)})`);
+        }
+    };
+    const onInterrupt = effects.onInterrupt ?? installInterruptHandler;
+    const exit = effects.exit ?? ((code) => process.exit(code));
+    const removeHandler = onInterrupt(() => {
+        // The in-flight request is abandoned; the credential is not. Nothing is
+        // printed here — the value, and the fact one was minted at all, stay out
+        // of both streams (D3448-009).
+        void revokeOnce().then(() => exit(EXIT_INTERRUPTED));
+    });
+    try {
+        return await use(minted.token);
+    }
+    finally {
+        removeHandler();
+        await revokeOnce();
+    }
+}
+/**
+ * Turn a refusal envelope into the lines an operator reads — #3448 D3448-010.
+ *
+ * Pure, because it carries the fact that makes handing the envelope back
+ * worth anything instead of throwing: a 429's `Retry-After`, which the server
+ * already worked out and which would be re-derived badly from an exception
+ * message.
+ *
+ * #3482 — there is no "Version mode" line any more. It named the mode a
+ * refused call's version was locked to, and no version is locked to anything.
+ */
+export function refusalLines(answer) {
+    const body = answer.body ?? {};
+    const retry = answer.retryAfterSeconds !== null ? ` — retry in ${answer.retryAfterSeconds}s` : "";
+    const fields = [];
+    if (body.errorCode)
+        fields.push({ label: "Code", value: String(body.errorCode) });
+    const details = Array.isArray(body.details)
+        ? body.details.map((detail) => typeof detail === "string" ? detail : JSON.stringify(detail))
+        : [];
+    return {
+        message: `${body.error ?? `Refused with HTTP ${answer.httpStatus}`}${retry}`,
+        fields,
+        details,
+    };
+}
+//# sourceMappingURL=function-run.js.map

package/dist/src/lib/function-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-run.js","sourceRoot":"","sources":["../../../src/lib/function-run.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/function-schema-codegen.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Schema-typed codegen for server functions — #3281, project
+ * `server-functions` phase 4.
+ *
+ * The intent's "Schema-typed codegen on every push": `<Key>Input` and
+ * `<Key>Output` from the declared schemas, a handler helper so function code
+ * is typed from the declaration, and a typed per-key invoker. Two artifacts,
+ * both rendered from the same `functions/<key>.toml` and both regenerated by
+ * `config push`, `config pull` and `primitive functions codegen`:
+ *
+ *   - `functions/primitive-function-types.d.ts` — every key's input and
+ *     output types, and a `FunctionSchemas` augmentation keyed by function
+ *     key (the `DatabaseSchemas` shape `primitive-db-types.d.ts` uses), which
+ *     is what types `defineFunction("<key>", handler)`: `input` is the
+ *     declared input, the return is checked against the declared output, and
+ *     a key the tree does not declare is a compile error.
+ *   - `functions/generated/<key>.generated.ts` — the client invoker, the
+ *     `workflows codegen` layout: imports only from `js-bao-wss-client`,
+ *     exports the two types and a `<key>(client)` factory. Since #3482 EVERY
+ *     function's invoker carries both verbs — `invoke`, `start`, `getStatus`,
+ *     `waitFor`, `terminate` — because the config says nothing about how a
+ *     function runs and the caller picks the runtime at each call. `waitFor`
+ *     binds `<Key>Output`, so the completion path is typed too (D3281-SO-003).
+ *
+ * ── The same descriptor the platform validates with ──────────────────────
+ *
+ * Schemas are interpreted through the vendored descriptor `workflows codegen`
+ * already reads (`workflow-codegen/schemaToTs.ts`, a byte copy of the server's
+ * `schema-descriptor.ts`), so what compiles is what every invocation door
+ * accepts: `input` is a REQUIRED option iff the schema rejects `{}` (the
+ * client sends `rootInput` only when `input !== undefined`, and the server
+ * defaults an absent one to `{}`), an absent schema is `unknown`, and a
+ * malformed schema fails naming the file rather than typing something false.
+ *
+ * ── Identifiers ──────────────────────────────────────────────────────────
+ *
+ * Names come from the workflow naming helpers (PascalCase, the digit-leading
+ * and reserved-word rules), and the runtime call always passes the ORIGINAL
+ * key. Two keys that sanitize to one identifier would render one file over the
+ * other, so that is refused naming both.
+ *
+ * FORMATTING CONTRACT (#1565): the invoker is emitted as a fixed point of
+ * Prettier's default config through `codegen-shared/prettierStable.ts`, like
+ * the other two generators, because `--check` byte-compares.
+ */
+/** The regenerated declaration beside `primitive-db-types.d.ts`. */
+export declare const FUNCTION_TYPES_DECLARATION_FILE = "primitive-function-types.d.ts";
+/** Where the per-key invokers go, under `functions/`, unless `-o` says otherwise. */
+export declare const FUNCTION_INVOKERS_DIR = "generated";
+/** Suffix identifying a generated invoker (shared with the other generators). */
+export declare const GENERATED_FILE_SUFFIX = ".generated.ts";
+export declare class FunctionSchemaCodegenError extends Error {
+}
+export interface FunctionSchemaSource {
+    /**
+     * The file stem, which is the key push uses when the file declares none.
+     * An authored `[function] key` wins over it — see {@link resolveFunctionKey}.
+     */
+    key: string;
+    tomlPath: string;
+    tomlContent: string;
+}
+/** What the renderers need from one `functions/<key>.toml`. */
+export interface FunctionSchemaIR {
+    key: string;
+    /** The tree-relative file this came from, for a message an author acts on. */
+    fileLabel: string;
+    inputSchema: unknown;
+    outputSchema: unknown;
+    /** `input` is a required option iff the schema rejects `{}`. */
+    inputRequired: boolean;
+    /** `<Key>` — the PascalCase base of the two type names. */
+    typeBaseName: string;
+    inputTypeName: string;
+    outputTypeName: string;
+    /** `<key>(client)` — the exported factory. */
+    factoryName: string;
+}
+/**
+ * Every `functions/*.toml` in a tree, read once. The key is the one push
+ * uses: the file name (push takes the identity from it and attaches
+ * `functionKey` itself).
+ */
+export declare function functionSchemaSources(configDir: string): FunctionSchemaSource[];
+/**
+ * Parse one file into the data both renderers need. Throws a
+ * `FunctionSchemaCodegenError` naming the file for malformed schema JSON or an
+ * unresolvable mode — the honest `unknown` is for an ABSENT schema, never a
+ * broken one.
+ */
+export declare function describeFunctionSchemas(source: FunctionSchemaSource): FunctionSchemaIR;
+/**
+ * Describe every source, sorted by key, refusing two files that resolve to one
+ * key. This is the LANGUAGE-NEUTRAL half of the set-level IR, shared with the
+ * Swift emitter (#3344): mode, schemas and requiredness come from here for
+ * both languages, so the two clients can never disagree about what a function
+ * exposes.
+ *
+ * The TypeScript base-name collision check deliberately stays out of it
+ * (`describeAll` below adds it): it is about the TS emitter's own
+ * `<Base>Input`/`<Base>Output` identifiers, and the Swift run has its own
+ * run-scoped symbol registry — which also covers the invoker struct and the
+ * factory function the TS check knows nothing about.
+ */
+export declare function describeFunctionSchemaSet(sources: readonly FunctionSchemaSource[]): Array<{
+    fn: FunctionSchemaIR;
+    source: FunctionSchemaSource;
+}>;
+/**
+ * A top-level `<Name>Input`/`<Name>Output` declaration: an absent schema →
+ * `unknown`, a plain object → an `interface`, anything else (a `oneOf` above
+ * all, which begins with `{` too) → a `type` alias. Same decision as the
+ * workflow generator, through the shared descriptor rather than a heuristic.
+ *
+ * Exported for `prompt-schema-codegen.ts` (#3330): a prompt's
+ * `<Key>PromptOutput` is the same question about the same kind of schema, and
+ * a second copy of this would be the third spelling of one rule.
+ */
+export declare function renderTypeDecl(name: string, schema: unknown): string;
+/**
+ * The declaration for a whole tree's functions. Sorted by key so the bytes
+ * depend on the files and not on the order they were read in. The
+ * augmentation is emitted even when the tree has no function yet: an empty
+ * `FunctionSchemas` keeps `FunctionKeys` open (`string`), so nothing breaks.
+ */
+export declare function renderFunctionSchemasDeclaration(sources: readonly FunctionSchemaSource[]): string;
+/**
+ * The full `<key>.generated.ts` for one function. Pure — exported so tests
+ * can assert on the string directly.
+ */
+export declare function renderFunctionInvokerFile(source: FunctionSchemaSource): {
+    key: string;
+    content: string;
+};
+/**
+ * Every invoker for a tree, keyed by the file name the generator writes
+ * (`<key>.generated.ts`), with the identifier-collision refusal applied
+ * across the set.
+ */
+export declare function renderFunctionInvokers(sources: readonly FunctionSchemaSource[]): Array<{
+    fileName: string;
+    content: string;
+}>;