primitive-admin 1.1.0-alpha.9 → 1.1.0

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;