primitive-admin 1.1.0-alpha.6 → 1.1.0-alpha.60

package/dist/src/lib/workflow-config-sidecar.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Named workflow configs as files (issue #2645, spec §Contracts/Named configs).
+ *
+ * A workflow's named configurations used to reach the server only through
+ * `workflows configs create/update/duplicate/activate` — verbs, not files. That
+ * made the live body of a running workflow invisible to the repo and to review,
+ * which is precisely the failure #1976 records and the reason this issue exists.
+ * The design-gate decision was "TOML wins": each config body is a file at
+ * `workflows/<key>.configs/<name>.toml`, and `activeConfigName` in
+ * `workflows/<key>.toml` names the live one.
+ *
+ * The layout mirrors the `<key>.tests/` sidecar convention the sync tree
+ * already uses, so there is one directory idiom rather than two.
+ *
+ *   workflows/order-intake.toml            # the workflow, incl. activeConfigName
+ *   workflows/order-intake.configs/v2.toml # a named config body
+ *   workflows/order-intake.tests/*.toml    # test cases (pre-existing)
+ *
+ * File shape:
+ *
+ *   [config]
+ *   description = "second cut"
+ *   status = "active"
+ *
+ *   [[steps]]
+ *   id = "greet"
+ *   kind = "noop"
+ *
+ *   [expr.cel]
+ *   ready = "input.ok == true"
+ *
+ * The config's NAME is the file name and is deliberately not restated inside
+ * the file: a second declaration would be a second thing to change and a
+ * mismatch to adjudicate, which is the shape of problem this issue removes.
+ */
+/** Directory holding a workflow's named config bodies. */
+export declare function workflowConfigsDir(configDir: string, key: string): string;
+/** The config name a sidecar file declares — its base name. */
+export declare function workflowConfigNameFromFile(file: string): string;
+/** A named config body, as authored on disk. */
+export interface WorkflowConfigSidecar {
+    name: string;
+    description?: string;
+    status?: string;
+    /** Always an array once parsed: an empty body is a real, pushable state. */
+    steps: any[];
+    /** `[expr.cel]` named guards travelling with these steps (#1614). */
+    expressions?: {
+        cel: Record<string, string>;
+    };
+}
+/** Emit a server config record as its sidecar file body. */
+export declare function serializeWorkflowConfigSidecar(config: any): string;
+/** Read a parsed sidecar back into the body `sync push` applies. */
+export declare function parseWorkflowConfigSidecar(name: string, tomlData: any): WorkflowConfigSidecar;
+/**
+ * Every named config authored for a workflow, in file-name order.
+ *
+ * An absent directory returns an empty list rather than throwing: a workflow
+ * with no sidecars is the ordinary single-config case, where the body is the
+ * `steps` in `workflows/<key>.toml`.
+ */
+export declare function readWorkflowConfigSidecars(configDir: string, key: string, readToml?: (path: string) => any): WorkflowConfigSidecar[];

package/dist/src/lib/workflow-config-sidecar.js

@@ -0,0 +1,96 @@
+/**
+ * Named workflow configs as files (issue #2645, spec §Contracts/Named configs).
+ *
+ * A workflow's named configurations used to reach the server only through
+ * `workflows configs create/update/duplicate/activate` — verbs, not files. That
+ * made the live body of a running workflow invisible to the repo and to review,
+ * which is precisely the failure #1976 records and the reason this issue exists.
+ * The design-gate decision was "TOML wins": each config body is a file at
+ * `workflows/<key>.configs/<name>.toml`, and `activeConfigName` in
+ * `workflows/<key>.toml` names the live one.
+ *
+ * The layout mirrors the `<key>.tests/` sidecar convention the sync tree
+ * already uses, so there is one directory idiom rather than two.
+ *
+ *   workflows/order-intake.toml            # the workflow, incl. activeConfigName
+ *   workflows/order-intake.configs/v2.toml # a named config body
+ *   workflows/order-intake.tests/*.toml    # test cases (pre-existing)
+ *
+ * File shape:
+ *
+ *   [config]
+ *   description = "second cut"
+ *   status = "active"
+ *
+ *   [[steps]]
+ *   id = "greet"
+ *   kind = "noop"
+ *
+ *   [expr.cel]
+ *   ready = "input.ok == true"
+ *
+ * The config's NAME is the file name and is deliberately not restated inside
+ * the file: a second declaration would be a second thing to change and a
+ * mismatch to adjudicate, which is the shape of problem this issue removes.
+ */
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { basename, join } from "path";
+import { parseConfigToml, stringifyConfigToml } from "./config-toml.js";
+/** Directory holding a workflow's named config bodies. */
+export function workflowConfigsDir(configDir, key) {
+    return join(configDir, "workflows", `${key}.configs`);
+}
+/** The config name a sidecar file declares — its base name. */
+export function workflowConfigNameFromFile(file) {
+    return basename(file, ".toml");
+}
+/** Emit a server config record as its sidecar file body. */
+export function serializeWorkflowConfigSidecar(config) {
+    const cel = config?.expressions?.cel && typeof config.expressions.cel === "object"
+        ? config.expressions.cel
+        : undefined;
+    const data = {
+        config: {
+            description: config?.description || undefined,
+            status: config?.status || undefined,
+        },
+        steps: Array.isArray(config?.steps) ? config.steps : [],
+        ...(cel && Object.keys(cel).length > 0 ? { expr: { cel } } : {}),
+    };
+    for (const k of Object.keys(data.config)) {
+        if (data.config[k] === undefined)
+            delete data.config[k];
+    }
+    return stringifyConfigToml(data);
+}
+/** Read a parsed sidecar back into the body `sync push` applies. */
+export function parseWorkflowConfigSidecar(name, tomlData) {
+    const config = tomlData?.config || {};
+    const cel = tomlData?.expr?.cel && typeof tomlData.expr.cel === "object"
+        ? tomlData.expr.cel
+        : undefined;
+    return {
+        name,
+        description: config.description ?? undefined,
+        status: config.status ?? undefined,
+        steps: Array.isArray(tomlData?.steps) ? tomlData.steps : [],
+        ...(cel ? { expressions: { cel } } : {}),
+    };
+}
+/**
+ * Every named config authored for a workflow, in file-name order.
+ *
+ * An absent directory returns an empty list rather than throwing: a workflow
+ * with no sidecars is the ordinary single-config case, where the body is the
+ * `steps` in `workflows/<key>.toml`.
+ */
+export function readWorkflowConfigSidecars(configDir, key, readToml = (p) => parseConfigToml(readFileSync(p, "utf-8"))) {
+    const dir = workflowConfigsDir(configDir, key);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".toml"))
+        .sort()
+        .map((f) => parseWorkflowConfigSidecar(workflowConfigNameFromFile(f), readToml(join(dir, f))));
+}
+//# sourceMappingURL=workflow-config-sidecar.js.map

package/dist/src/lib/workflow-config-sidecar.js.map

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

package/dist/src/lib/workflow-field-descriptor.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Classification of the `WorkflowDefinition` field surface (issue #2326,
+ * Phase 1 of #1976).
+ *
+ * Purpose: give the CLI a mechanical trip-wire for the drift that keeps
+ * happening — the server grows a `[workflow]`-level config field (`syncCallable`
+ * #807, `accessRule` #571, `runAs` #1081, `capabilities` #1172, `lock` #1518)
+ * and the CLI silently drops it on `sync push` / `sync pull`. Every field of the
+ * `WorkflowDefinition` model must appear in exactly one of the three groups
+ * below. The generated artifact `generated-workflow-model-fields.ts` carries the
+ * model's real field list (parsed from `models.yaml` at build time), and
+ * `cli/tests/unit/workflow-field-descriptor-drift-guard.test.ts` asserts
+ *
+ *     synced ∪ structural ∪ internal  ===  the model's fields
+ *
+ * so a new field hard-fails the guard until someone classifies it.
+ *
+ * ── Scope: declarative classification and coverage ONLY ──────────────────
+ * Decision of record (#1976, 2026-07-23): this table records WHICH fields
+ * exist, whether each is synced / structural / internal, and its `[workflow]`
+ * TOML key. Anything with real BEHAVIOR gets an explicit per-field handler or
+ * stays outside the table. In particular this file deliberately does NOT encode
+ * as boolean knobs:
+ *   - the schema fields' native-TOML-table-vs-JSON-string parsing
+ *     (`buildWorkflowPayloadFromToml` / `safeJsonParse` own that),
+ *   - `syncCallable`'s deferred second PATCH on update (#807 — `applyWorkflowBody`
+ *     owns that),
+ *   - the `metadataManifest` (#1304) and `expr.cel` (#1614) structural side
+ *     channels, which are attached alongside the steps write and are not
+ *     `[workflow]`-table keys at all.
+ * `cli/src/lib/app-settings-descriptor.ts` is the shape being matched:
+ * deliberately narrow.
+ *
+ * ── What Phase 1 does and does not do ───────────────────────────────────
+ * Phase 1 (this file) is the guard only. Making the push builder
+ * (`workflow-payload.ts`) and the pull serializer (`serializeWorkflow` in
+ * `commands/sync.ts`) *consume* this table is Phase 2 (#2327).
+ * `synced` therefore means "belongs in the `[workflow]` TOML table", NOT
+ * "already round-trips" — see `SYNCED_NOT_YET_WIRED` below.
+ */
+/** Value shape of a synced `[workflow]` key. Descriptive; behavior lives in the handlers. */
+export type WorkflowFieldType = "string" | "number" | "boolean" | "string[]" | "json";
+export interface WorkflowFieldDescriptor {
+    /** `WorkflowDefinition` model field name === the server payload key. */
+    field: string;
+    /** Key under the `[workflow]` table in workflow TOML (usually === `field`). */
+    tomlKey: string;
+    /** Value shape, for the Phase 2 handlers and for documentation. */
+    type: WorkflowFieldType;
+}
+/**
+ * The author-facing `[workflow]`-table config fields — the ones a workflow
+ * author manages as code and the CLI must round-trip.
+ */
+export declare const WORKFLOW_FIELD_DESCRIPTOR: readonly WorkflowFieldDescriptor[];
+/**
+ * Fields that ARE author-controlled but do not live in the `[workflow]` table —
+ * they travel through their own structural channel. Kept distinct from
+ * `WORKFLOW_FIELDS_INTERNAL` so "internal" keeps meaning "not author-facing".
+ */
+export declare const WORKFLOW_FIELDS_STRUCTURAL: ReadonlySet<string>;
+/**
+ * Fields the server owns: identity, ownership, timestamps, computed pointers,
+ * and the deprecated draft/revision slot. None of these are ever sent by the
+ * CLI, and none belong in workflow TOML.
+ */
+export declare const WORKFLOW_FIELDS_INTERNAL: ReadonlySet<string>;
+/**
+ * Synced fields the CLI does NOT round-trip yet — Phase 2 (#2327) wires them.
+ * Recorded explicitly so "classified" is never mistaken for "implemented".
+ * `lock` was wired by #1972; `templateMissingMarker` was removed from the
+ * platform by #2643, so the set is now empty.
+ */
+export declare const SYNCED_NOT_YET_WIRED: ReadonlySet<string>;
+/** Descriptor `field` names, for coverage/parity checks. */
+export declare const WORKFLOW_SYNCED_FIELDS: ReadonlySet<string>;
+/** Look up a synced field's descriptor by model field name. */
+export declare function getWorkflowFieldDescriptor(field: string): WorkflowFieldDescriptor | undefined;
+/**
+ * Model fields that are classified in NONE of synced / structural / internal —
+ * i.e. a field someone added to `models.yaml` without deciding how the CLI
+ * treats it. Non-empty is a hard failure in the drift guard.
+ */
+export declare function findUnclassifiedWorkflowFields(modelFields: readonly string[]): string[];
+/**
+ * Classifications that no longer correspond to a model field — i.e. a field
+ * removed from `models.yaml` while the CLI still classifies it. Also a hard
+ * failure: a stale classification must not silently pass, or the coverage
+ * claim quietly stops meaning anything.
+ */
+export declare function findStaleWorkflowClassifications(modelFields: readonly string[]): string[];

package/dist/src/lib/workflow-field-descriptor.js

@@ -0,0 +1,153 @@
+/**
+ * Classification of the `WorkflowDefinition` field surface (issue #2326,
+ * Phase 1 of #1976).
+ *
+ * Purpose: give the CLI a mechanical trip-wire for the drift that keeps
+ * happening — the server grows a `[workflow]`-level config field (`syncCallable`
+ * #807, `accessRule` #571, `runAs` #1081, `capabilities` #1172, `lock` #1518)
+ * and the CLI silently drops it on `sync push` / `sync pull`. Every field of the
+ * `WorkflowDefinition` model must appear in exactly one of the three groups
+ * below. The generated artifact `generated-workflow-model-fields.ts` carries the
+ * model's real field list (parsed from `models.yaml` at build time), and
+ * `cli/tests/unit/workflow-field-descriptor-drift-guard.test.ts` asserts
+ *
+ *     synced ∪ structural ∪ internal  ===  the model's fields
+ *
+ * so a new field hard-fails the guard until someone classifies it.
+ *
+ * ── Scope: declarative classification and coverage ONLY ──────────────────
+ * Decision of record (#1976, 2026-07-23): this table records WHICH fields
+ * exist, whether each is synced / structural / internal, and its `[workflow]`
+ * TOML key. Anything with real BEHAVIOR gets an explicit per-field handler or
+ * stays outside the table. In particular this file deliberately does NOT encode
+ * as boolean knobs:
+ *   - the schema fields' native-TOML-table-vs-JSON-string parsing
+ *     (`buildWorkflowPayloadFromToml` / `safeJsonParse` own that),
+ *   - `syncCallable`'s deferred second PATCH on update (#807 — `applyWorkflowBody`
+ *     owns that),
+ *   - the `metadataManifest` (#1304) and `expr.cel` (#1614) structural side
+ *     channels, which are attached alongside the steps write and are not
+ *     `[workflow]`-table keys at all.
+ * `cli/src/lib/app-settings-descriptor.ts` is the shape being matched:
+ * deliberately narrow.
+ *
+ * ── What Phase 1 does and does not do ───────────────────────────────────
+ * Phase 1 (this file) is the guard only. Making the push builder
+ * (`workflow-payload.ts`) and the pull serializer (`serializeWorkflow` in
+ * `commands/sync.ts`) *consume* this table is Phase 2 (#2327).
+ * `synced` therefore means "belongs in the `[workflow]` TOML table", NOT
+ * "already round-trips" — see `SYNCED_NOT_YET_WIRED` below.
+ */
+/**
+ * The author-facing `[workflow]`-table config fields — the ones a workflow
+ * author manages as code and the CLI must round-trip.
+ */
+export const WORKFLOW_FIELD_DESCRIPTOR = [
+    { field: "name", tomlKey: "name", type: "string" },
+    { field: "status", tomlKey: "status", type: "string" },
+    { field: "description", tomlKey: "description", type: "string" },
+    // JSON Schema objects. TOML may present them as an inline table OR as a
+    // JSON string; the push builder owns that parse (not a knob here).
+    { field: "inputSchema", tomlKey: "inputSchema", type: "json" },
+    { field: "outputSchema", tomlKey: "outputSchema", type: "json" },
+    { field: "perUserMaxRunning", tomlKey: "perUserMaxRunning", type: "number" },
+    { field: "perUserMaxQueued", tomlKey: "perUserMaxQueued", type: "number" },
+    { field: "perAppMaxRunning", tomlKey: "perAppMaxRunning", type: "number" },
+    { field: "perAppMaxQueued", tomlKey: "perAppMaxQueued", type: "number" },
+    { field: "queueTtlSeconds", tomlKey: "queueTtlSeconds", type: "number" },
+    { field: "dequeueOrder", tomlKey: "dequeueOrder", type: "string" },
+    {
+        field: "requiresClientApply",
+        tomlKey: "requiresClientApply",
+        type: "boolean",
+    },
+    // Create-only on the wire (#807: update sends it as a deferred second PATCH
+    // once the new steps are live). That sequencing is the payload builder's job.
+    { field: "syncCallable", tomlKey: "syncCallable", type: "boolean" },
+    { field: "accessRule", tomlKey: "accessRule", type: "string" },
+    { field: "runAs", tomlKey: "runAs", type: "string" },
+    // #1518/#1972 — declarative run-scoped lock. `[workflow.lock]` inline table
+    // on the TOML side, JSON on the wire; validated server-side by
+    // `parseWorkflowLock` (decision of record #6: no client-side mirror validator).
+    { field: "lock", tomlKey: "lock", type: "json" },
+    // #1078 Tier 1b — StringSetField on the model, string array in TOML/JSON.
+    { field: "capabilities", tomlKey: "capabilities", type: "string[]" },
+];
+/**
+ * Fields that ARE author-controlled but do not live in the `[workflow]` table —
+ * they travel through their own structural channel. Kept distinct from
+ * `WORKFLOW_FIELDS_INTERNAL` so "internal" keeps meaning "not author-facing".
+ */
+export const WORKFLOW_FIELDS_STRUCTURAL = new Set([
+    // The workflow's identity. Comes from the TOML file name / `--key`, and is
+    // attached by the caller rather than spread from the `[workflow]` table.
+    "workflowKey",
+    // #1304 — JSON declared-access manifest, derived from the workflow's CEL
+    // fields and attached alongside the steps write, not typed by the author.
+    "metadataManifest",
+]);
+/**
+ * Fields the server owns: identity, ownership, timestamps, computed pointers,
+ * and the deprecated draft/revision slot. None of these are ever sent by the
+ * CLI, and none belong in workflow TOML.
+ */
+export const WORKFLOW_FIELDS_INTERNAL = new Set([
+    // Identity / ownership / timestamps — assigned by the server.
+    "workflowId",
+    "appId",
+    "createdBy",
+    "createdAt",
+    "modifiedAt",
+    // Pointer to the active WorkflowConfiguration — server-computed on publish.
+    "activeConfigId",
+    // DEPRECATED in models.yaml: the legacy revision + draft slot, kept for
+    // migration/backward compatibility. Server-managed; never author-authored.
+    "latestRevision",
+    "stepsR2Key",
+    "draftStepsR2Key",
+    "draftInputSchema",
+    "draftOutputSchema",
+    "draftModifiedAt",
+]);
+/**
+ * Synced fields the CLI does NOT round-trip yet — Phase 2 (#2327) wires them.
+ * Recorded explicitly so "classified" is never mistaken for "implemented".
+ * `lock` was wired by #1972; `templateMissingMarker` was removed from the
+ * platform by #2643, so the set is now empty.
+ */
+export const SYNCED_NOT_YET_WIRED = new Set([]);
+/** Descriptor `field` names, for coverage/parity checks. */
+export const WORKFLOW_SYNCED_FIELDS = new Set(WORKFLOW_FIELD_DESCRIPTOR.map((d) => d.field));
+/** Look up a synced field's descriptor by model field name. */
+export function getWorkflowFieldDescriptor(field) {
+    return WORKFLOW_FIELD_DESCRIPTOR.find((d) => d.field === field);
+}
+/**
+ * Model fields that are classified in NONE of synced / structural / internal —
+ * i.e. a field someone added to `models.yaml` without deciding how the CLI
+ * treats it. Non-empty is a hard failure in the drift guard.
+ */
+export function findUnclassifiedWorkflowFields(modelFields) {
+    return modelFields
+        .filter((f) => !WORKFLOW_SYNCED_FIELDS.has(f) &&
+        !WORKFLOW_FIELDS_STRUCTURAL.has(f) &&
+        !WORKFLOW_FIELDS_INTERNAL.has(f))
+        .sort();
+}
+/**
+ * Classifications that no longer correspond to a model field — i.e. a field
+ * removed from `models.yaml` while the CLI still classifies it. Also a hard
+ * failure: a stale classification must not silently pass, or the coverage
+ * claim quietly stops meaning anything.
+ */
+export function findStaleWorkflowClassifications(modelFields) {
+    const known = new Set(modelFields);
+    return [
+        ...WORKFLOW_SYNCED_FIELDS,
+        ...WORKFLOW_FIELDS_STRUCTURAL,
+        ...WORKFLOW_FIELDS_INTERNAL,
+    ]
+        .filter((f) => !known.has(f))
+        .sort();
+}
+//# sourceMappingURL=workflow-field-descriptor.js.map

package/dist/src/lib/workflow-field-descriptor.js.map

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

package/dist/src/lib/workflow-fragments.d.ts

@@ -0,0 +1,64 @@
+/**
+ * CLI-only workflow fragment expansion.
+ *
+ * Workflows may declare `include = ["fragment-name", ...]` at the top of
+ * their TOML. The CLI expands those references into a fully-flattened
+ * `[[steps]]` list before push — the server never sees fragments and
+ * stores only the canonical, expanded JSON.
+ *
+ * Pinned decisions (#744):
+ *   - CLI-only. No server-side WorkflowFragment model.
+ *   - Fragments live at <workflowDir>/../workflow-fragments/<name>.toml.
+ *   - Fragment files are `[[steps]]` lists only — no `[workflow]` block.
+ *   - No recursive includes in v1 (fragments cannot themselves `include`).
+ *   - Unique step ids validated post-expansion; collisions name both
+ *     locations in the error message.
+ *
+ * Parameterized includes (#1448):
+ *   - Two include forms are supported. The bare form
+ *     `include = ["name", ...]` (an array of fragment-name strings) is
+ *     unchanged. The parameterized form uses `[[include]]` array-of-tables:
+ *
+ *       [[include]]
+ *       fragment = "lifecycle-email"          # required
+ *       runIf = "input.type == 'x'"           # optional; ANDed onto each step
+ *       with = { id = "...", subject = "..." } # params, exposed as {{ params.* }}
+ *
+ *   - A file uses one form or the other — mixing string and table entries in a
+ *     single `include` array is an error.
+ *   - `{{ params.* }}` references inside the fragment's steps are substituted
+ *     at EXPAND time from the include's `with` table. A whole-string
+ *     `{{ params.x }}` splices the raw typed value (number/bool/table);
+ *     an embedded `{{ params.x }}` inside a larger string stringifies it.
+ *     A missing param is a hard error. Only the `params.` namespace is
+ *     touched — every other `{{ ... }}` template passes through to the server
+ *     verbatim, and `params.` never survives into the expanded output.
+ *   - The include-level `runIf` (CEL) is ANDed onto every expanded step:
+ *     both present → `(<includeRunIf>) && (<stepRunIf>)`; one present → that
+ *     one; neither → no runIf.
+ *
+ * Wiring: `parseTomlFile()` in `cli/src/commands/sync.ts` calls
+ * `expandWorkflowTomlData()` after parsing. All 24 push parse sites in
+ * sync.ts route through that single seam, so the expansion is uniform.
+ * The standalone `expandWorkflow(filePath)` helper backs the
+ * `primitive workflows expand` subcommand for debugging.
+ */
+export interface ExpandedWorkflow {
+    workflow?: Record<string, any>;
+    steps: Array<Record<string, any>>;
+    include?: undefined;
+    [key: string]: any;
+}
+/**
+ * Read and expand a workflow TOML file from disk. Returns the parsed
+ * TOML with all `include` fragments spliced in. If the file has no
+ * `include` key, the parsed TOML is returned unchanged.
+ */
+export declare function expandWorkflow(workflowPath: string): ExpandedWorkflow;
+/**
+ * Expand the `include` key of an already-parsed TOML object. Resolves
+ * fragment files relative to `<workflowPath>/../../workflow-fragments/`.
+ * Use this when the TOML has already been parsed elsewhere (e.g. inside
+ * `parseTomlFile()`).
+ */
+export declare function expandWorkflowTomlData(parsed: Record<string, any>, workflowPath: string): ExpandedWorkflow;