primitive-admin 1.1.0-alpha.9 → 1.2.0-alpha.0

package/dist/src/lib/config-json-field.js

@@ -0,0 +1,56 @@
+/**
+ * Emitting a `type: "json"` field (a JSON Schema, a provider-options blob) as
+ * TOML — the rule `config pull` writes every such field through.
+ *
+ * Issue #1446 wrote it for workflows and prompts inside `sync.ts`; #3317 moved
+ * it here because `serializeFunction` lives in its own module and needed the
+ * same rule rather than a second, subtly different copy of it. A function's
+ * schemas are stored as JSON STRINGS on the row, so the module that could not
+ * reach this one emitted nothing at all for them, and the comparison read the
+ * server as holding no schema.
+ */
+import { canEmitNative } from "./toml-native-form.js";
+/**
+ * The TOML value for one `type: "json"` field, or `undefined` when the record
+ * holds none (the key is then omitted).
+ *
+ * The parsed value is emitted as a native table whenever it round-trips
+ * faithfully (`canEmitNative === null`), falling back to the JSON string only
+ * for the values TOML silently drops (`null` / `undefined` anywhere inside).
+ * The empty object `{}` is a real, distinct value (for a schema: "accepts
+ * anything") and emits as an empty table, so it survives a pull → push cycle
+ * instead of being cleared server-side.
+ *
+ * The sponsor-approved decision is to always move to native aggressively — no
+ * form preservation — so this does not consult the existing file's form.
+ *
+ * `subject` names the object in the fallback warning, e.g. `Workflow 'greet'`.
+ */
+export function serializeJsonField(value, fieldName, subject, log) {
+    if (value === undefined || value === null)
+        return undefined;
+    // JSON fields arrive from the server GET parsed; defensively accept a JSON
+    // string too (a function's schemas are always one, and an inline-authored
+    // file re-serialized here is another).
+    let obj = value;
+    if (typeof value === "string") {
+        try {
+            obj = JSON.parse(value);
+        }
+        catch {
+            // Not valid JSON — keep the original string as the emitted value.
+            return value;
+        }
+    }
+    if (obj && typeof obj === "object") {
+        const reason = canEmitNative(obj);
+        if (reason) {
+            log(`${subject}: cannot emit \`${fieldName}\` as native TOML (${reason}); using JSON string.`);
+            return JSON.stringify(obj);
+        }
+        return obj;
+    }
+    // A non-object value (unexpected) — preserve it as a JSON string.
+    return JSON.stringify(obj);
+}
+//# sourceMappingURL=config-json-field.js.map

package/dist/src/lib/config-json-field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-json-field.js","sourceRoot":"","sources":["../../../src/lib/config-json-field.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAU,EACV,SAAiB,EACjB,OAAe,EACf,GAA8B;IAE9B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,2EAA2E;IAC3E,0EAA0E;IAC1E,uCAAuC;IACvC,IAAI,GAAG,GAAG,KAAK,CAAC;IAChB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;YAClE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,MAAM,EAAE,CAAC;YACX,GAAG,CACD,GAAG,OAAO,mBAAmB,SAAS,sBAAsB,MAAM,uBAAuB,CAC1F,CAAC;YACF,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,kEAAkE;IAClE,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/dist/src/lib/config-object-descriptor.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The configuration-object descriptor registry (issue #2645).
+ *
+ * Server-side configuration is authored in TOML and applied with `config push`.
+ * That makes the TOML field surface the thing an operator has to discover, so
+ * it needs a machine-readable definition — the job per-flag `--help` used to do.
+ * This registry is that definition, and it drives four commands:
+ *
+ *   - `config fields <type>`      lists a type's keys, types, required, default
+ *   - `config create <type> <key>`   scaffolds the type's file from `scaffold()`
+ *   - `config set <type>/<key>`   validates the dotted path being edited
+ *   - `config push --only <sel>`  resolves a selector to a type + key
+ *
+ * ── Deliberately a descriptor, never reflection ──────────────────────────
+ * The field list is declared here, not inferred from the pull serializers in
+ * `commands/sync.ts`. Reflection over emitted keys cannot report `required` or
+ * `default`, and an implicit field surface is exactly the drift #2644 exists to
+ * end. The workflow key set is CONSUMED from #2644's vendored definition
+ * (`config-surface.ts` / `generated-config-surfaces.ts`) and the app settings
+ * from `app-settings-descriptor.ts`, rather than restated, so there is still
+ * one definition per field.
+ *
+ * ── Drift guard ──────────────────────────────────────────────────────────
+ * `cli/tests/unit/config-object-descriptor.test.ts` cross-checks the registry
+ * against `SYNC_RESOURCE_TYPES` (every per-entity type has exactly one
+ * descriptor) and `PUSH_PRUNE_SPECS` (the declared identity path is a real
+ * field), and asserts each scaffold parses and carries every required field. A
+ * new sync resource type therefore fails a test rather than silently
+ * under-reporting from `config fields`.
+ *
+ * ── Relationship to #2644 ────────────────────────────────────────────────
+ * #2644 defines one shared field definition across the server, the TOML surface
+ * and CLI validation. These descriptors are sized to be ABSORBED by it: they
+ * carry only what the four commands above need, and no validation behavior.
+ */
+import { type SyncResourceType } from "./sync-resource-types.js";
+/** Value shape of a TOML key, as reported by `config fields`. */
+export type ConfigFieldType = "string" | "number" | "boolean" | "string[]" | "table" | "table[]" | "json";
+export interface ConfigFieldDescriptor {
+    /** Dotted TOML path, e.g. `workflow.status`, `verification.jwt`. */
+    path: string;
+    type: ConfigFieldType;
+    /** True when `config push` cannot apply the file without this key. */
+    required: boolean;
+    /**
+     * The value the server assumes when the key is absent. `undefined` means
+     * there is no default — an absent key leaves the field unset (or, for the
+     * TOML-owned fields, clears it).
+     */
+    default?: string | number | boolean;
+    /** One line, shown by `config fields`. */
+    description: string;
+}
+/**
+ * A second file the same object is authored across (issue #2645).
+ *
+ * A workflow's named configs are sidecar files (`workflows/<key>.configs/
+ * <name>.toml`, spec §Contracts/Named configs), authored by the same person as
+ * the workflow and pushed by the same command — but they are not keys of
+ * `workflows/<key>.toml`, so they cannot be fields of the descriptor without
+ * telling `config set` to write them into the wrong file. They are listed
+ * separately instead: `config fields` has to report the whole surface, because
+ * it is what replaced per-flag `--help` for the removed `workflows configs`
+ * verbs (criterion 7).
+ */
+export interface ConfigObjectCompanionFile {
+    /** Where the companion lives, e.g. `workflows/<key>.configs/<name>.toml`. */
+    fileHint: string;
+    /** One line saying what the file is and what names it. */
+    description: string;
+    fields: readonly ConfigFieldDescriptor[];
+}
+export interface ConfigObjectDescriptor {
+    /** Selector name: `workflow`, `webhook`, `app`, `var`. */
+    type: string;
+    /**
+     * Layout metadata for the 13 per-entity types. Absent for the two root
+     * singletons (`app.toml`, `vars.toml`), which `SYNC_RESOURCE_TYPES`
+     * deliberately excludes.
+     */
+    resourceType?: SyncResourceType;
+    /** Where the object is authored, for help text and error messages. */
+    fileHint: string;
+    /**
+     * Dotted path of the key that names the object, when it has one in-file.
+     * Types keyed purely by filename (transforms, rule-sets) declare none.
+     */
+    identity?: string;
+    /** One line describing what the object configures. */
+    description: string;
+    fields: readonly ConfigFieldDescriptor[];
+    /** Further files the object is authored across, listed but not `config set`-able. */
+    companionFiles?: readonly ConfigObjectCompanionFile[];
+    /**
+     * True when the file's root-level keys are the author's own rather than a
+     * fixed surface — `vars.toml` is a flat `KEY = "value"` table. There is no
+     * field list to declare, so `config set` accepts any single-segment path.
+     */
+    freeFormRootKeys?: boolean;
+    /** The file body `config create <type> <key>` writes. */
+    scaffold(key: string): string;
+}
+/** The identity path a descriptor declares, or `undefined` when keyed by filename. */
+export declare function describedIdentityPath(descriptor: ConfigObjectDescriptor): string | undefined;
+/**
+ * What the server assumes when a `[workflow]` key is absent.
+ *
+ * The vendored `WORKFLOW_TABLE` (#2644) carries key set and value shape but
+ * not defaults, so the defaults are stated here, next to the other types'.
+ * They are not free text: the `models.yaml` `WorkflowDefinition` defaults are
+ * the source of truth, and
+ * `cli/tests/unit/config-object-descriptor.test.ts` parses that model and fails
+ * when a default here disagrees or a newly-defaulted field is missing. Without
+ * them `config fields workflow` reported `default null` for the queueing and
+ * dispatch knobs — the command that replaced per-flag `--help` under-reporting
+ * exactly what the removed flags used to document (issue #2645).
+ *
+ * Exported because `config diff`'s workflow comparator needs exactly this table
+ * to normalize omitted-vs-defaulted fields, and kept a hand-mirrored second
+ * copy of it until #2731. Two tables can disagree; a guarded one cannot go
+ * stale unnoticed.
+ */
+export declare const WORKFLOW_FIELD_DEFAULTS: Record<string, string | number | boolean>;
+export declare const CONFIG_OBJECT_DESCRIPTORS: readonly ConfigObjectDescriptor[];
+/** Every selector type name, in registry order. */
+export declare const CONFIG_OBJECT_TYPES: readonly string[];
+export declare function getConfigObjectDescriptor(type: string): ConfigObjectDescriptor | undefined;