@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/framework/schema-version.d.ts

@@ -0,0 +1,140 @@
+import { ConfigFormatError } from "./rejection.js";
+import { Patch, SerializedConfig } from "./Config.js";
+
+//#region src/framework/schema-version.d.ts
+/**
+ * The schema version this build of the package writes and reads natively — the newest registered
+ * migration's version, restated as a constant so writers need no registry at hand.
+ *
+ * 1 is the baseline: the entire pre-versioning corpus, before any migration exists. The first
+ * migration replaces this with its own mint timestamp, and every bump after that does the same.
+ *
+ * Two tests in `schema-version.test.ts` guard it: the hash tripwire (any schema edit fails until
+ * this bumps and a migration registers), and the max-registered assertion — which is also what
+ * catches an OUT-OF-DATE PR. A branch that minted its migration before a newer one landed on main
+ * sets this constant to its own older timestamp; the merge ref then carries a registered migration
+ * newer than the constant, and the assertion fails until the author re-mints.
+ */
+declare const CURRENT_SCHEMA_VERSION = 20260910212453;
+/** What the walkers need to see of an envelope — loose on purpose, so a typed `SerializedConfig`
+ *  and a raw old-shape record both flow in without casts. */
+interface VersionStamped {
+  readonly version?: unknown;
+  readonly sources?: unknown;
+}
+/** A wire-form envelope as a migration sees it — raw, because its shape is some PAST version's, and
+ *  only the terminal `hydrateFrom` parse speaks the current one. */
+type RawWireConfig = Record<string, unknown>;
+/** What the walker hands back: current-shaped, so typed callers read it as the wire form, and raw
+ *  enough that a test or migration can reach any field. */
+type UpgradedWire = SerializedConfig & RawWireConfig;
+/** A zod-like validator — what a frozen historical schema needs to expose. Structural rather than a
+ *  `z.ZodType` so the frozen copies stay decoupled from the live zod major. */
+interface FrozenSchema {
+  safeParse(data: unknown): {
+    success: boolean;
+    error?: {
+      message: string;
+    };
+  };
+}
+/**
+ * One migration: everything below `version` comes up to `version`'s shape through `up`.
+ *
+ * Filed as `migrations/{version}_{slug}.ts` — mint the version with `date +%Y%m%d%H%M%S`, exactly
+ * like a `supabase/migrations` file. There is no `from`: the chain is the registered versions in
+ * ascending order, and data stamped V walks every migration newer than V.
+ *
+ * `up` transforms the envelope's OWN fields and must not descend into `sources` — the walker owns
+ * that recursion, upgrading each recorded closure by its own stamp before the envelope's chain runs.
+ *
+ * Frozen schemas are declared only when `up` actually transforms (see the two-tier rule in the
+ * migrations folder): an identity migration has nothing to validate, and a transforming one
+ * validates both sides so a transform that mangles fails HERE, named, rather than downstream as a
+ * hydrate refusal.
+ */
+interface SchemaMigration {
+  /** Mint timestamp, `YYYYMMDDHHMMSS` as an integer. */
+  readonly version: number;
+  /** Bring an envelope from the PREVIOUS registered version's shape to this one's. Identity for an
+   *  additive bump. */
+  up(json: RawWireConfig): RawWireConfig;
+  /** Upgrade one stored patch. Absent = patches unaffected (identity). `null` = the patch has no
+   *  meaning under this version and is dropped from replay. */
+  upPatch?(patch: Patch): Patch | null;
+  /** Frozen copy of the shape BEFORE this migration — input validation for a transforming one. */
+  readonly fromSchema?: FrozenSchema;
+  /** Frozen copy of the shape this migration produces — output validation. */
+  readonly toSchema?: FrozenSchema;
+}
+/** Data from a FUTURE schema — written by a newer package/deploy than the one reading it. The remedy
+ *  is always upgrading the reader; message says which side is behind. A `ConfigFormatError`, so the
+ *  surfaces that report an unreadable artifact by name report this one too. */
+declare class SchemaVersionTooNew extends ConfigFormatError {
+  readonly found: number;
+  readonly supported: number;
+  constructor(found: number, supported?: number);
+}
+/** Register migrations. Refuses a duplicate version or a non-timestamp one — the whole point of the
+ *  mint convention is that two branches cannot claim the same slot. The single exception is the
+ *  reserved {@link CUTOVER_VERSION} baseline. */
+declare function registerSchemaMigrations(...migrations: SchemaMigration[]): void;
+/**
+ * The version a wire form claims. Absent means 1 — the corpus written before versioning existed is
+ * retroactively version 1, and nothing needs backfilling for that to be true. The legacy counter
+ * `2` reads as the mint that carries the same shape.
+ */
+declare function schemaVersionOf(json: VersionStamped): number;
+/**
+ * What the WALKER treats a wire form as — {@link schemaVersionOf}, plus pre-cutover detection.
+ *
+ * An unstamped envelope that is not v2-shaped but carries v1 markers is version 0: the flat bag a
+ * pre-config-v2 build wrote. Nothing ever writes a 0 stamp, so the cutover migration runs for
+ * exactly this corpus and nothing else. An unstamped shape matching NEITHER stays 1 — the hydrate
+ * guard refuses it by name, rather than the cutover reader best-efforting garbage into an empty
+ * config (the silent failure the guard exists to prevent).
+ */
+declare function detectedWireVersion(json: VersionStamped): number;
+interface WalkOptions {
+  /** Test seam — the walkers read the registered chain when absent. */
+  readonly migrations?: ReadonlyMap<number, SchemaMigration>;
+  /** Test seam for exercising the walk without touching the real constant. */
+  readonly target?: number;
+}
+/**
+ * One envelope brought up to the current version — the read-time half of the whole design.
+ *
+ * Recorded sources upgrade FIRST, each by its own stamp (a pinned closure was serialized at ITS
+ * write time, not the envelope's), then the envelope walks every migration newer than its own
+ * stamp, oldest first. A migration's `up` therefore never sees or touches `sources`.
+ * Already-current input passes through untouched — same reference, so hot paths pay nothing.
+ */
+declare function upgradeSerializedConfig(json: VersionStamped, options?: WalkOptions): UpgradedWire;
+/**
+ * One stored patch brought up from the version it was written at. `null` means the patch has no
+ * meaning under the current schema and replay skips it — reported by the caller, not swallowed here.
+ */
+declare function upgradePatch(patch: Patch, writtenAt: number, options?: WalkOptions): Patch | null;
+/** What {@link upgradeDraftEntries} did with a shared draft — the entries a session can replay,
+ *  plus what it could not: `held` (stamped newer than this build; valid for newer readers) and
+ *  `retired` (a migration answered `null`; the patch has no meaning under the current schema). */
+interface UpgradedDraft<E> {
+  readonly entries: E[];
+  readonly held: E[];
+  readonly retired: E[];
+}
+/**
+ * A shared draft's entries, each brought up from the version it was written at — the replay-side
+ * counterpart of {@link upgradeSerializedConfig}, over the patch log instead of the envelope.
+ *
+ * Current entries pass through by reference (the hot path after any bump settles). An upgraded
+ * entry is re-stamped at the target: the transform has run, and replaying it again through the same
+ * chain — the double application `upPatch` does not promise to survive — is exactly what a stale
+ * stamp would cause.
+ */
+declare function upgradeDraftEntries<E extends {
+  readonly patch: Patch;
+  readonly schemaVersion?: number;
+}>(draft: readonly E[], options?: WalkOptions): UpgradedDraft<E>;
+//#endregion
+export { CURRENT_SCHEMA_VERSION, SchemaMigration, SchemaVersionTooNew, UpgradedDraft, type WalkOptions, detectedWireVersion, registerSchemaMigrations, schemaVersionOf, upgradeDraftEntries, upgradePatch, upgradeSerializedConfig };

package/dist/framework/schema-version.js

@@ -0,0 +1,214 @@
+import { ConfigFormatError } from "./rejection.js";
+//#region src/framework/schema-version.ts
+/**
+* The schema version this build of the package writes and reads natively — the newest registered
+* migration's version, restated as a constant so writers need no registry at hand.
+*
+* 1 is the baseline: the entire pre-versioning corpus, before any migration exists. The first
+* migration replaces this with its own mint timestamp, and every bump after that does the same.
+*
+* Two tests in `schema-version.test.ts` guard it: the hash tripwire (any schema edit fails until
+* this bumps and a migration registers), and the max-registered assertion — which is also what
+* catches an OUT-OF-DATE PR. A branch that minted its migration before a newer one landed on main
+* sets this constant to its own older timestamp; the merge ref then carries a registered migration
+* newer than the constant, and the assertion fails until the author re-mints.
+*/
+const CURRENT_SCHEMA_VERSION = 20260910212453;
+/** The mint that moved `options` into the `settings` kind — restated here, rather than imported
+*  from the migration that owns it, because that migration imports this module. */
+const SETTINGS_AS_KIND_VERSION = 20260908171448;
+/** Data from a FUTURE schema — written by a newer package/deploy than the one reading it. The remedy
+*  is always upgrading the reader; message says which side is behind. A `ConfigFormatError`, so the
+*  surfaces that report an unreadable artifact by name report this one too. */
+var SchemaVersionTooNew = class extends ConfigFormatError {
+	found;
+	supported;
+	constructor(found, supported = CURRENT_SCHEMA_VERSION) {
+		super(`This config was written at schema version ${found}, but this build understands up to ${supported}. Upgrade to read it: \`npm install @yahoo/uds-create-cli@latest\` in a repo, or reload Studio.`);
+		this.name = "SchemaVersionTooNew";
+		this.found = found;
+		this.supported = supported;
+	}
+};
+/** A plausible mint timestamp — wide bounds, because the point is catching a counter (1, 2, 3…)
+*  or a unix-epoch value slipped in where a `YYYYMMDDHHMMSS` belongs. */
+function isMintTimestamp(version) {
+	return Number.isInteger(version) && version >= 20240101e6 && version <= 99991231235959;
+}
+/** The registered migrations, keyed by version. Module-local; migration modules add themselves via
+*  {@link registerSchemaMigrations}. Empty while CURRENT_SCHEMA_VERSION is the baseline 1. */
+const REGISTERED = /* @__PURE__ */ new Map();
+/** Register migrations. Refuses a duplicate version or a non-timestamp one — the whole point of the
+*  mint convention is that two branches cannot claim the same slot. The single exception is the
+*  reserved {@link CUTOVER_VERSION} baseline. */
+function registerSchemaMigrations(...migrations) {
+	for (const migration of migrations) {
+		if (migration.version !== 1 && !isMintTimestamp(migration.version)) throw new Error(`Schema migration version ${migration.version} is not a mint timestamp — mint one with \`date +%Y%m%d%H%M%S\`, like a supabase migration.`);
+		if (REGISTERED.has(migration.version)) throw new Error(`A schema migration at version ${migration.version} is already registered.`);
+		if (migration.version > 20260910212453) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
+		REGISTERED.set(migration.version, migration);
+	}
+}
+/** The registered migrations — exposed for the guard tests, not for callers. */
+function registeredSchemaMigrations() {
+	return REGISTERED;
+}
+/**
+* The version a wire form claims. Absent means 1 — the corpus written before versioning existed is
+* retroactively version 1, and nothing needs backfilling for that to be true. The legacy counter
+* `2` reads as the mint that carries the same shape.
+*/
+function schemaVersionOf(json) {
+	const version = json.version;
+	if (version === void 0) return 1;
+	if (version === 2) return SETTINGS_AS_KIND_VERSION;
+	if (typeof version === "number" && Number.isInteger(version) && version >= 1) return version;
+	throw new Error(`Config carries a malformed version (${JSON.stringify(version)}) — expected a positive integer.`);
+}
+/** The field names only a pre-cutover artifact spells — the flat bag `uds build` wrote before
+*  config-v2. Enough of them that no v2 envelope or foreign JSON matches by accident. */
+const V1_MARKERS = [
+	"tokenGroups",
+	"styleProps",
+	"compositeStyles",
+	"componentGroups",
+	"assetGroups"
+];
+/**
+* What the WALKER treats a wire form as — {@link schemaVersionOf}, plus pre-cutover detection.
+*
+* An unstamped envelope that is not v2-shaped but carries v1 markers is version 0: the flat bag a
+* pre-config-v2 build wrote. Nothing ever writes a 0 stamp, so the cutover migration runs for
+* exactly this corpus and nothing else. An unstamped shape matching NEITHER stays 1 — the hydrate
+* guard refuses it by name, rather than the cutover reader best-efforting garbage into an empty
+* config (the silent failure the guard exists to prevent).
+*/
+function detectedWireVersion(json) {
+	if (json.version !== void 0) return schemaVersionOf(json);
+	const raw = json;
+	if (Array.isArray(raw.ownedKinds) && typeof raw.items === "object" && raw.items !== null) return 1;
+	return V1_MARKERS.some((marker) => marker in raw) ? 0 : 1;
+}
+/** The migrations data at `version` still has to walk, oldest first. */
+function pendingFor(version, target, options) {
+	return [...(options?.migrations ?? REGISTERED).values()].filter((m) => m.version > version && m.version <= target).sort((a, b) => a.version - b.version);
+}
+/**
+* One envelope brought up to the current version — the read-time half of the whole design.
+*
+* Recorded sources upgrade FIRST, each by its own stamp (a pinned closure was serialized at ITS
+* write time, not the envelope's), then the envelope walks every migration newer than its own
+* stamp, oldest first. A migration's `up` therefore never sees or touches `sources`.
+* Already-current input passes through untouched — same reference, so hot paths pay nothing.
+*/
+function upgradeSerializedConfig(json, options) {
+	const target = options?.target ?? 20260910212453;
+	const version = detectedWireVersion(json);
+	if (version > target) throw new SchemaVersionTooNew(version, target);
+	const raw = json;
+	const sources = upgradedSources(raw, options);
+	let current = sources === void 0 ? raw : {
+		...raw,
+		sources
+	};
+	for (const migration of pendingFor(version, target, options)) current = applyOne(migration, current);
+	if (version === target && sources === void 0) return json;
+	return {
+		...current,
+		version: target
+	};
+}
+function applyOne(migration, json) {
+	refuseInvalid(migration.fromSchema, json, migration, "input");
+	const out = migration.up(json);
+	refuseInvalid(migration.toSchema, out, migration, "output");
+	return out;
+}
+function refuseInvalid(schema, data, migration, side) {
+	if (!schema) return;
+	const result = schema.safeParse(data);
+	if (!result.success) throw new Error(`Schema migration ${migration.version} refused its ${side}: ${result.error?.message ?? "validation failed"}`);
+}
+/** Upgraded recorded-source closures, or undefined when nothing needed touching (so the caller can
+*  keep the original reference). Each closure is a full wire form with its own stamp. */
+function upgradedSources(json, options) {
+	const sources = json.sources;
+	if (sources === void 0 || sources === null) return void 0;
+	if (typeof sources !== "object") return void 0;
+	let changed = false;
+	const out = {};
+	for (const [slug, recorded] of Object.entries(sources)) {
+		const closure = recorded?.config;
+		if (closure === void 0 || typeof closure !== "object") {
+			out[slug] = recorded;
+			continue;
+		}
+		const upgraded = upgradeSerializedConfig(closure, options);
+		if (upgraded === closure) out[slug] = recorded;
+		else {
+			changed = true;
+			out[slug] = {
+				...recorded,
+				config: upgraded
+			};
+		}
+	}
+	return changed ? out : void 0;
+}
+/**
+* One stored patch brought up from the version it was written at. `null` means the patch has no
+* meaning under the current schema and replay skips it — reported by the caller, not swallowed here.
+*/
+function upgradePatch(patch, writtenAt, options) {
+	const target = options?.target ?? 20260910212453;
+	if (writtenAt > target) throw new SchemaVersionTooNew(writtenAt, target);
+	let current = patch;
+	for (const migration of pendingFor(writtenAt, target, options)) {
+		if (current === null) break;
+		current = migration.upPatch ? migration.upPatch(current) : current;
+	}
+	return current;
+}
+/**
+* A shared draft's entries, each brought up from the version it was written at — the replay-side
+* counterpart of {@link upgradeSerializedConfig}, over the patch log instead of the envelope.
+*
+* Current entries pass through by reference (the hot path after any bump settles). An upgraded
+* entry is re-stamped at the target: the transform has run, and replaying it again through the same
+* chain — the double application `upPatch` does not promise to survive — is exactly what a stale
+* stamp would cause.
+*/
+function upgradeDraftEntries(draft, options) {
+	const target = options?.target ?? 20260910212453;
+	const entries = [];
+	const held = [];
+	const retired = [];
+	for (const entry of draft) {
+		const writtenAt = entry.schemaVersion ?? 1;
+		if (writtenAt > target) {
+			held.push(entry);
+			continue;
+		}
+		if (writtenAt === target) {
+			entries.push(entry);
+			continue;
+		}
+		const upgraded = upgradePatch(entry.patch, writtenAt, options);
+		if (upgraded === null) {
+			retired.push(entry);
+			continue;
+		}
+		entries.push({
+			...entry,
+			patch: upgraded,
+			schemaVersion: target
+		});
+	}
+	return {
+		entries,
+		held,
+		retired
+	};
+}
+//#endregion
+export { CURRENT_SCHEMA_VERSION, SETTINGS_AS_KIND_VERSION, SchemaVersionTooNew, detectedWireVersion, registerSchemaMigrations, registeredSchemaMigrations, schemaVersionOf, upgradeDraftEntries, upgradePatch, upgradeSerializedConfig };

package/dist/framework/schemas.d.ts

@@ -0,0 +1,109 @@
+import { FieldsSchema } from "./utils/field-schema.js";
+import { Config } from "./Config.js";
+import { z } from "zod";
+
+//#region src/framework/schemas.d.ts
+/** A tool/op handler — runs the op against a config. Default CRUD/read handlers are wired later
+ *  (the Operation entity's `execute`); a custom op declares its own here. */
+type OpHandler = (input: Record<string, unknown>, config: Config) => unknown;
+/** What a schema is validated against, when the schema itself depends on more than the value: the
+ *  `config` registry (to resolve a ref to another entity) and the `parent` item being edited (to see
+ *  its sibling fields). Absent members are normal — a factory is also called with no parent when a
+ *  concrete schema is needed for tool derivation. */
+interface FieldsCtx {
+  readonly config?: Config;
+  readonly parent?: unknown;
+  /** The whole body being written, for a field whose schema depends on its siblings (a style
+   *  property's values are judged against its properties). Present where a writer has the body in
+   *  hand (`run`, `validateData`); absent for hydration, `register` and tool derivation, which see
+   *  the storage shape. */
+  readonly body?: unknown;
+  /** The body arrived through a linked system's pin, or through a `replace` (the write that carries a
+   *  body across the borrow boundary), rather than being authored here. It was authored and validated
+   *  where it lives and is already what the source emits, so a check that is authoring guidance for
+   *  this config's own writes does not apply; a check on the value domain still does, since that is
+   *  what decides whether this kind can hold the body at all. */
+  readonly linked?: boolean;
+  /** The member being written, for a sub-entity op. An update validates the patch rather than the
+   *  merged result, so a check that depends on a field the patch doesn't set — "may this node be
+   *  given children", which needs its `element` — can only see it by reading the member back off
+   *  `parent`. That needs to know which member. */
+  readonly key?: string;
+}
+/** A schema, or a factory that builds one from its context. A factory is what lets a check be part
+ *  of the schema (`z.enum(the owner's layer names)`) rather than a refinement bolted beside it. */
+type SchemaOrFactory = z.ZodTypeAny | ((ctx: FieldsCtx) => z.ZodTypeAny);
+/** A kind's `data` override built from its context and its own fields — see `UserSchemas`. */
+type DataFactory = (ctx: FieldsCtx & {
+  fields: FieldsSchema;
+}) => z.ZodTypeAny;
+/** One operation the kind exposes — its model-facing input shape, read/mutate axis, and (for a
+ *  custom op) its behavior. `input` may be a factory when the op's data schema depends on the
+ *  Config/parent; `opsForKind` resolves it for consumers that need a concrete schema. */
+interface SchemaEntry {
+  readonly input: SchemaOrFactory;
+  readonly readOnly: boolean;
+  readonly handler?: OpHandler;
+  /** The verb's human name (`Create`, `Add`, `Remove`) — no entity, no field. A UI row whose folder
+   *  already names the entity shows this alone. */
+  readonly label: string;
+  /** What the op does, for a model to choose it by. Written here, next to the input it describes, so
+   *  a custom op is described where it's declared rather than in a switch somewhere downstream. This
+   *  is the derived default — a user can override a tool's description on the Tool entity. */
+  readonly description: string;
+  /**
+   * What the op addresses — the one bit downstream display and examples need, and the reason neither
+   * has to parse a verb:
+   *   `item`        one member (`create`/`update`/`get`/a sub-op on one member)
+   *   `collection`  the whole collection (`list`, `sub-list`, `sub-reorder`) — reads plural
+   *   `group`       a group NODE, not an item (`group-update`)
+   *   `config`      the config itself, not any kind (`info`, `api`) — so a tool name carries no
+   *                 Entity segment and a title names the system
+   */
+  readonly scope: 'item' | 'collection' | 'group' | 'config';
+  /** Whether the innermost address is new — `create` (a new `path`), `sub-create` (a new `key`). An
+   *  example must not reuse an existing one, and `data` must be a full body rather than a patch. */
+  readonly creates?: boolean;
+  /** Mutations whose effect deserves explicit approval even on their native surface. Kept on the
+   *  operation rather than inferred from its verb so custom operations carry the same policy. */
+  readonly approval?: 'destructive' | 'reference-change';
+  /** A composed title, when `<Verb> <Noun>` isn't English. `dependents` is a noun, so it reads
+   *  Entity-first; `validate` takes an object, so the entity sits inside the phrase. */
+  readonly title?: (entity: string) => string;
+  /** An example invocation, for an op whose input isn't the standard `path`/`key`/`data`/`to`/`order`
+   *  address shape. Declared by the op because only it knows what its own input means. */
+  readonly example?: (ctx: {
+    config: Config;
+    kind: string;
+    path: string;
+  }) => Record<string, unknown> | undefined;
+}
+/** The author's `schemas` param — keyed by verb. A base verb (`create`/`update`) takes `{ data }`
+ *  to override just its data schema; `{ description }` changes only a derived op's presentation;
+ *  a new verb takes a full custom op (`{ input, readOnly?, handler }`); `null` removes a derived op
+ *  (any verb, incl. a read). */
+type UserSchemas = Record<string, ({
+  /** The `data` half of the envelope: the body a create/update/replace takes. A factory sees
+   *  the kind's own `fields` beside the context, so a variant that swapped a field is narrowed
+   *  on its own fields rather than on the base's. */
+  data?: z.ZodTypeAny | DataFactory;
+  /** What a `path` of this kind may be, beyond what every path may be: parsed after the
+   *  `<kind>:` marker is stripped. A kind whose path is also a name in generated code declares
+   *  one — a style property's path is the JSX prop a component exposes. */
+  path?: z.ZodType<string, string>; /** The same, for a rename's `to`. */
+  to?: z.ZodType<string, string>;
+} & Partial<Pick<SchemaEntry, 'description' | 'example'>>) | (Pick<SchemaEntry, 'description'> & Partial<Pick<SchemaEntry, 'example'>>) | ({
+  input: z.ZodTypeAny;
+  readOnly?: boolean;
+  handler: OpHandler;
+} & Partial<Pick<SchemaEntry, 'label' | 'description' | 'scope' | 'creates' | 'approval' | 'title' | 'example'>>) | null>;
+/** A resolved operation — a `SchemaEntry` tagged with its kind + verb, the shape `opsForKind`
+ *  (registry.ts) yields and the Operation entity maps over. */
+interface DerivedOp extends Omit<SchemaEntry, 'input'> {
+  readonly kind: string;
+  readonly verb: string;
+  /** Always concrete — `opsForKind` resolves a factory input before handing it out. */
+  readonly input: z.ZodTypeAny;
+}
+//#endregion
+export { DerivedOp, FieldsCtx, OpHandler, SchemaEntry, UserSchemas };