@yahoo/uds-create-config 2.45.0 → 3.0.1

package/dist/entities/system/Tool.d.ts

@@ -0,0 +1,134 @@
+import { DerivedEntityClass } from "../../framework/defineDerivedEntity.js";
+import { Config } from "../../framework/Config.js";
+import { ComputedInput } from "../../framework/registry.js";
+import { z } from "zod";
+
+//#region src/entities/system/Tool.d.ts
+declare const Tool: DerivedEntityClass<z.ZodObject<{
+  operation: DerivedEntityClass<z.ZodObject<{
+    kind: z.ZodString;
+    verb: z.ZodString;
+    readOnly: z.ZodBoolean;
+    label: z.ZodString;
+    description: z.ZodString;
+    scope: z.ZodString;
+    creates: z.ZodBoolean;
+    approval: z.ZodOptional<z.ZodEnum<{
+      destructive: "destructive";
+      "reference-change": "reference-change";
+    }>>;
+  }, z.core.$strip>, {
+    inputSchema: ({
+      member: op,
+      config
+    }: Omit<ComputedInput, "member"> & {
+      member: {
+        kind: string;
+        verb: string;
+        readOnly: boolean;
+        label: string;
+        description: string;
+        scope: string;
+        creates: boolean;
+        approval?: "destructive" | "reference-change" | undefined;
+      };
+    }) => z.ZodTypeAny<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | undefined;
+    execute: ({
+      member: op,
+      config: declaring
+    }: Omit<ComputedInput, "member"> & {
+      member: {
+        kind: string;
+        verb: string;
+        readOnly: boolean;
+        label: string;
+        description: string;
+        scope: string;
+        creates: boolean;
+        approval?: "destructive" | "reference-change" | undefined;
+      };
+    }) => ((input: Record<string, unknown>, config: Config) => unknown) | undefined;
+    field: ({
+      member: op
+    }: Omit<ComputedInput, "member"> & {
+      member: {
+        kind: string;
+        verb: string;
+        readOnly: boolean;
+        label: string;
+        description: string;
+        scope: string;
+        creates: boolean;
+        approval?: "destructive" | "reference-change" | undefined;
+      };
+    }) => string | undefined;
+    title: ({
+      member: op,
+      config
+    }: Omit<ComputedInput, "member"> & {
+      member: {
+        kind: string;
+        verb: string;
+        readOnly: boolean;
+        label: string;
+        description: string;
+        scope: string;
+        creates: boolean;
+        approval?: "destructive" | "reference-change" | undefined;
+      };
+    }) => ((entity: string) => string) | undefined;
+    example: ({
+      member: op,
+      config
+    }: Omit<ComputedInput, "member"> & {
+      member: {
+        kind: string;
+        verb: string;
+        readOnly: boolean;
+        label: string;
+        description: string;
+        scope: string;
+        creates: boolean;
+        approval?: "destructive" | "reference-change" | undefined;
+      };
+    }) => Record<string, unknown> | undefined;
+  }>;
+  name: z.ZodString;
+  description: z.ZodString;
+  enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, {
+  kind: (input: ComputedInput) => string | undefined;
+  verb: (input: ComputedInput) => string | undefined;
+  readOnly: ({
+    member,
+    config
+  }: Omit<ComputedInput, "member"> & {
+    member: {
+      operation: {
+        __ref: string;
+      };
+      name: string;
+      description: string;
+      enabled: boolean;
+    };
+  }) => boolean;
+  inputSchema: (input: ComputedInput) => z.ZodTypeAny<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | undefined;
+  execute: (input: ComputedInput) => ((input: Record<string, unknown>, config: Config) => unknown) | undefined;
+  action: (input: ComputedInput) => string | undefined; /** The sub-entity collection a sub-op targets (`layers`); absent on a kind-level op. */
+  field: (input: ComputedInput) => string | undefined;
+  /** What the op ADDRESSES — `item` | `collection` | `group` | `config` — declared by the op, which is
+   *  the reason a consumer never parses a verb to find out. Projected here so the agent-facing surface
+   *  answers it directly: a caller selecting "tools that resolve one thing" asks for `item` rather than
+   *  listing the verbs that happen to mean that today. */
+  scope: (input: ComputedInput) => string | undefined; /** Approval policy follows the operation into every transport, including compact batches. */
+  approval: (input: ComputedInput) => "destructive" | "reference-change" | undefined;
+  /** The standalone title — composed from the op's own verb word and the labels THIS config gives
+   *  its entities, so it names what this system actually calls things. */
+  label: (input: ComputedInput) => string | undefined;
+  /** The verb alone — for a row whose folder already names the entity/collection. Declared by the
+   *  op, so a custom op's row reads correctly without this file knowing it exists. */
+  shortLabel: (input: ComputedInput) => string | undefined; /** Bound to a real entity in this config — built by the op from its own input shape. */
+  example: (input: ComputedInput) => Record<string, unknown> | undefined;
+}>;
+//#endregion
+export { Tool };

package/dist/entities/system/Tool.js

@@ -0,0 +1,124 @@
+import { defineDerivedEntity } from "../../framework/defineDerivedEntity.js";
+import { Operation, opField } from "./Operation.js";
+import { z } from "zod";
+//#region src/entities/system/Tool.ts
+/**
+* `Tool` — the editable, agent-facing surface over `Operation`, a DERIVED entity with per-field
+* overrides. One member per `Operation` (derived membership — no manual create), each wrapping its
+* operation by a typed ref and carrying an editable `name`/`description`/`enabled`. The transport
+* bits — `inputSchema` (zod), `execute` (fn), and `readOnly` — aren't stored; they're `computed`,
+* delegating to the wrapped operation.
+*
+* `Tool.list(config)` is the whole tool catalog: reads and mutations alike, each with a model-facing
+* name + description, its input shape, a callable, and its display + example derivations — so a
+* consumer needs no second layer to join against. A user renames/re-describes a tool (a sparse
+* override) without touching the operation truth; a consumer that needs a different DEFAULT
+* description extends the kind (`Tool.extend({ deriveMembers })`) rather than branching inside one.
+*
+* What a tool DERIVES here is only what's true of a tool rather than of a capability: the model-facing
+* `name`, and the composed human title. Everything else — the verb's label, the description, what the
+* op addresses, its example — is DECLARED BY THE OPERATION (`schemas.ts`), because that's where the
+* verb is defined. So adding a custom op (a component's `validate`) touches only that entity: no
+* switch here grows a case, and nothing infers meaning from a verb string.
+*
+* What a tool does NOT carry is how its OUTPUT looks: markdown is a format a consumer picks, not a
+* fact about the capability.
+*/
+/**
+* A computed field that reads the wrapped operation — the shape of every field on this entity but
+* one. Resolves the op, hands it to `pick`, and yields `undefined` when the ref doesn't resolve, so
+* no field repeats that guard.
+*/
+function viaOp(pick) {
+	return ({ member, config }) => {
+		const op = Operation.get(config, member.operation);
+		return op ? pick(op, config) : void 0;
+	};
+}
+const Tool = defineDerivedEntity({
+	kind: "tool",
+	label: "Tool",
+	fields: z.object({
+		operation: Operation,
+		name: z.string(),
+		description: z.string(),
+		enabled: z.boolean().default(true)
+	}),
+	deriveMembers: (source) => Object.fromEntries(Operation.list(source).map((op) => [op.path, {
+		operation: Operation.ref(op.path),
+		name: toolNameOf(source.name, op.kind, op.verb, op.scope),
+		description: op.description,
+		enabled: true
+	}])),
+	overridable: [
+		"name",
+		"description",
+		"enabled"
+	],
+	computed: {
+		kind: viaOp((op) => op.kind),
+		verb: viaOp((op) => op.verb),
+		readOnly: ({ member, config }) => Operation.get(config, member.operation)?.readOnly ?? true,
+		inputSchema: viaOp((op) => op.inputSchema),
+		execute: viaOp((op) => op.execute),
+		action: viaOp((op) => op.verb.split("/")[0]),
+		/** The sub-entity collection a sub-op targets (`layers`); absent on a kind-level op. */
+		field: viaOp((op) => opField(op.verb)),
+		/** What the op ADDRESSES — `item` | `collection` | `group` | `config` — declared by the op, which is
+		*  the reason a consumer never parses a verb to find out. Projected here so the agent-facing surface
+		*  answers it directly: a caller selecting "tools that resolve one thing" asks for `item` rather than
+		*  listing the verbs that happen to mean that today. */
+		scope: viaOp((op) => op.scope),
+		/** Approval policy follows the operation into every transport, including compact batches. */
+		approval: viaOp((op) => op.approval),
+		/** The standalone title — composed from the op's own verb word and the labels THIS config gives
+		*  its entities, so it names what this system actually calls things. */
+		label: viaOp((op, source) => titleOf(source, op)),
+		/** The verb alone — for a row whose folder already names the entity/collection. Declared by the
+		*  op, so a custom op's row reads correctly without this file knowing it exists. */
+		shortLabel: viaOp((op) => op.label),
+		/** Bound to a real entity in this config — built by the op from its own input shape. */
+		example: viaOp((op) => op.example)
+	}
+});
+/** A verb/kind → a tool-name segment (`style-prop` → `style_prop`). */
+/** A name segment as it appears in a tool id: `-` and the `/` of a nested collection's path both
+*  become `_`, so `props/value` reads as one more segment rather than as punctuation. */
+const slug = (segment) => segment.replace(/[-/]/g, "_");
+const titleCase = (word) => word.charAt(0).toUpperCase() + word.slice(1);
+/** `uds_<ns>_<verb>_<kind>[_<field>]` — a sub-verb (`sub-create/layers`) drops the `sub-` prefix and
+*  appends its field, matching the flat tool naming a model calls. The one naming rule that IS a
+*  tool concern: an operation has no wire name, a tool does. */
+function toolNameOf(ns, kind, verb, scope) {
+	const field = opField(verb);
+	const action = verb.split("/")[0].replace("sub-", "").replace(/-/g, "_");
+	if (scope === "config") return `uds_${slug(ns)}_${action}`;
+	return `uds_${slug(ns)}_${action}_${slug(kind)}${field ? `_${slug(field)}` : ""}`;
+}
+/** A collection's DECLARED noun at the arity the op acts on — plural for a whole-collection op,
+*  singular for a per-member one. Read off the sub-entity, never title-cased from the field key, so
+*  a collection is named the way it declares itself. */
+function collectionNoun(config, kind, field, scope) {
+	const sub = config.subEntityOf(kind, field);
+	if (!sub) return titleCase(field);
+	return scope === "collection" ? sub.labelPlural : sub.label;
+}
+/**
+* A tool's standalone title — `<Verb> <Entity> <Noun>`. Names the entity because this is a heading (a
+* detail pane, a doc), where a tree row nested under the entity would only repeat it; the row shows
+* the op's own `label` instead.
+*
+* Pure composition: the verb's word and any odd phrasing come from the OP, the nouns from the config's
+* own entity labels. An op whose name isn't a plain verb supplies its own `title` (a `dependents` op
+* reads entity-first) rather than being special-cased here.
+*/
+function titleOf(config, op) {
+	const entity = config.entityLabel(op.kind);
+	if (op.title) return op.title(entity);
+	const field = opField(op.verb);
+	if (field) return `${op.label} ${entity} ${collectionNoun(config, op.kind, field, op.scope)}`;
+	const noun = op.scope === "collection" ? config.entityLabelPlural(op.kind) : entity;
+	return `${op.label} ${noun}`;
+}
+//#endregion
+export { Tool };

package/dist/entities/system/color.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+
+//#region src/entities/system/color.d.ts
+/** A colour: a literal, a token ref, a derived colour, or a gradient. */
+type ColorValue = string | {
+  readonly __ref: string;
+} | DerivedColor | Gradient;
+interface DerivedColor {
+  readonly op: 'darken' | 'lighten' | 'alpha' | 'mix';
+  readonly color: ColorValue;
+  /**
+   * How much, as a PERCENTAGE (0–100) in every case — one unit, so a reader never has to remember
+   * which op takes a fraction. The authoring helpers take whatever's natural for each (`alpha` takes
+   * a 0–1 opacity, matching CSS) and convert.
+   */
+  readonly amount: number;
+  /** `mix`'s second colour. */
+  readonly with?: ColorValue;
+  /** Interpolation space — `oklch` for shading (perceptually even), `srgb` for alpha. */
+  readonly space?: string;
+}
+/**
+ * A gradient — a colour that varies across a direction.
+ *
+ * Here rather than as a string because its stops are COLOURS: each may be a token ref, and a ref is
+ * an edge the dependency graph has to see. Flattened into a CSS string, renaming the token it points
+ * at would leave a gradient quietly pointing at nothing.
+ */
+interface Gradient {
+  readonly gradient: 'linear' | 'radial' | 'conic';
+  /** A CSS angle (`'135deg'`) or a direction keyword (`'to right'`). */
+  readonly angle?: string;
+  readonly stops: readonly {
+    color: ColorValue;
+    at?: string;
+  }[];
+  readonly space?: string;
+  readonly repeating?: boolean;
+}
+/** Whether a value is a gradient. */
+declare function isGradient(value: unknown): value is Gradient;
+/** `linearGradient({ angle: 'to right', stops: [...] })`. */
+declare function linearGradient(spec: Omit<Gradient, 'gradient'>): Gradient;
+/** Whether a value is a derived colour — the test the renderers branch on. */
+declare function isDerivedColor(value: unknown): value is DerivedColor;
+/** Blend toward black in light mode and white in dark — so a hover state darkens in both. */
+declare function darken(color: ColorValue, amount: number): DerivedColor;
+/** Mirror of {@link darken}: toward white in light mode, black in dark. */
+declare function lighten(color: ColorValue, amount: number): DerivedColor;
+/** `alpha(color, 0.2)` — the colour at 20% opacity. Takes a 0–1 opacity, like CSS. */
+declare function alpha(color: ColorValue, opacity: number): DerivedColor;
+/** `mix(a, b, 30)` — 30% of the way from `a` to `b`. */
+declare function mix(color: ColorValue, towards: ColorValue, amount: number, space?: string): DerivedColor;
+/**
+ * A derived colour as CSS.
+ *
+ * `render` resolves the nested colours — passed in rather than imported, because resolving a token
+ * ref to a `var()` is the projection layer's job and this module is the value's shape.
+ */
+declare function renderDerivedColor(value: DerivedColor, render: (color: ColorValue) => string): string;
+/** A gradient as CSS — `linear-gradient(to right, transparent 0%, var(--uds-bg-primary) 50%)`. */
+declare function renderGradient(value: Gradient, render: (color: ColorValue) => string): string;
+//#endregion
+export { ColorValue, DerivedColor, Gradient, alpha, darken, isDerivedColor, isGradient, lighten, linearGradient, mix, renderDerivedColor, renderGradient };

package/dist/entities/system/color.js

@@ -0,0 +1,123 @@
+import { refSchema } from "../../framework/utils/refs.js";
+import { z } from "zod";
+//#region src/entities/system/color.ts
+/**
+* A colour COMPUTED from another colour — `darken(Token.ref('bg/brand'), 10)`.
+*
+* A design system doesn't only name colours, it derives them: a hover state is the brand colour a
+* little darker, a scrim is black at 40%. Without a value form for that, the derivation has to happen
+* somewhere outside the config — and then the config no longer says what the component looks like.
+*
+* It resolves to native CSS `color-mix()`, NOT to a flattened literal. That's the point: the base
+* stays a `var(--…)`, so a mode override or a theme swap flows through the derived colour too. A
+* literal computed at build time would freeze the hover state to whatever the light-mode brand was.
+*
+* Usable wherever a colour is — a token's value, a style bag, a composite — because it IS a colour.
+* That's also why this isn't a separate entity: a derived colour is a value, and making it its own
+* kind would split the token store and break every `token:` ref that points into it.
+*/
+const colorValue = z.lazy(() => z.union([
+	z.string(),
+	refSchema,
+	derivedColor,
+	gradient
+]));
+const gradient = z.lazy(() => z.strictObject({
+	gradient: z.enum([
+		"linear",
+		"radial",
+		"conic"
+	]),
+	angle: z.string().optional(),
+	stops: z.array(z.strictObject({
+		color: colorValue,
+		at: z.string().optional()
+	})),
+	space: z.string().optional(),
+	repeating: z.boolean().optional()
+}));
+/** Whether a value is a gradient. */
+function isGradient(value) {
+	return typeof value === "object" && value !== null && typeof value.gradient === "string" && Array.isArray(value.stops);
+}
+/** `linearGradient({ angle: 'to right', stops: [...] })`. */
+function linearGradient(spec) {
+	return {
+		gradient: "linear",
+		...spec
+	};
+}
+const derivedColor = z.lazy(() => z.strictObject({
+	op: z.enum([
+		"darken",
+		"lighten",
+		"alpha",
+		"mix"
+	]),
+	color: colorValue,
+	amount: z.number(),
+	with: colorValue.optional(),
+	space: z.string().optional()
+}));
+/** Whether a value is a derived colour — the test the renderers branch on. */
+function isDerivedColor(value) {
+	return typeof value === "object" && value !== null && typeof value.op === "string" && "color" in value;
+}
+/** Blend toward black in light mode and white in dark — so a hover state darkens in both. */
+function darken(color, amount) {
+	return {
+		op: "darken",
+		color,
+		amount,
+		space: "oklch"
+	};
+}
+/** Mirror of {@link darken}: toward white in light mode, black in dark. */
+function lighten(color, amount) {
+	return {
+		op: "lighten",
+		color,
+		amount,
+		space: "oklch"
+	};
+}
+/** `alpha(color, 0.2)` — the colour at 20% opacity. Takes a 0–1 opacity, like CSS. */
+function alpha(color, opacity) {
+	return {
+		op: "alpha",
+		color,
+		amount: Math.round(Math.max(0, Math.min(1, opacity)) * 100),
+		space: "srgb"
+	};
+}
+/** `mix(a, b, 30)` — 30% of the way from `a` to `b`. */
+function mix(color, towards, amount, space = "oklch") {
+	return {
+		op: "mix",
+		color,
+		with: towards,
+		amount,
+		space
+	};
+}
+/**
+* A derived colour as CSS.
+*
+* `render` resolves the nested colours — passed in rather than imported, because resolving a token
+* ref to a `var()` is the projection layer's job and this module is the value's shape.
+*/
+function renderDerivedColor(value, render) {
+	const space = value.space ?? "oklch";
+	const base = render(value.color);
+	if (value.op === "darken" || value.op === "lighten") return `color-mix(in ${space}, ${base}, ${value.op === "darken" ? "light-dark(black, white)" : "light-dark(white, black)"} ${value.amount}%)`;
+	if (value.op === "alpha") return `color-mix(in ${space}, ${base} ${value.amount}%, transparent)`;
+	return `color-mix(in ${space}, ${base}, ${render(value.with ?? "transparent")} ${value.amount}%)`;
+}
+/** A gradient as CSS — `linear-gradient(to right, transparent 0%, var(--uds-bg-primary) 50%)`. */
+function renderGradient(value, render) {
+	const stops = value.stops.map((stop) => [render(stop.color), stop.at].filter(Boolean).join(" ")).join(", ");
+	const head = [value.angle, value.space ? `in ${value.space}` : void 0].filter(Boolean);
+	return `${value.repeating ? "repeating-" : ""}${value.gradient}-gradient(${[...head, stops].join(", ")})`;
+}
+//#endregion
+export { alpha, darken, derivedColor, gradient, isDerivedColor, isGradient, lighten, linearGradient, mix, renderDerivedColor, renderGradient };

package/dist/entities/system/component-module.d.ts

@@ -0,0 +1,63 @@
+import { Ref } from "../../framework/utils/refs.js";
+import { Config } from "../../framework/Config.js";
+
+//#region src/entities/system/component-module.d.ts
+/** The runtime address of one locally-built component export. */
+interface ComponentModuleSource {
+  /** The stable registry identity (`component:actions/Button`). */
+  readonly componentRef: string;
+  /** Config-relative sealed source path. One file is one compiled module. */
+  readonly filePath: string;
+  /** Content identity for the file and its complete config-visible build closure. */
+  readonly moduleKey: string;
+  /** The component export in the authored source module. */
+  readonly exportName: string;
+  /** The ctx-shaped registry export emitted beside the component. */
+  readonly entryExportName: string;
+}
+/** One component export an authored import can resolve through the runtime registry. */
+interface ComponentRegistryImportBinding {
+  readonly componentRef: string;
+  readonly exportName: string;
+}
+/**
+ * One authored module edge whose complete runtime surface is component exports.
+ *
+ * These imports can be replaced with stable registry refs in a standalone component build. An edge
+ * that also imports a helper, hook, namespace, or side effect is deliberately absent: that target's
+ * source remains part of the ordinary static build closure.
+ */
+interface ComponentRegistryImport {
+  readonly specifier: string;
+  readonly targetFilePath: string;
+  readonly bindings: readonly ComponentRegistryImportBinding[];
+}
+/**
+ * Component-only imports made by one sealed file, expressed in config-v2's existing identities.
+ *
+ * `File.imports` already records the authored specifier, resolved File, and imported names;
+ * `Component.file` + `Component.export` already say which of those names are registry components.
+ * Joining those facts here avoids inventing another dependency graph for incremental modules.
+ */
+declare function componentRegistryImports(config: Config, filePath: string): readonly ComponentRegistryImport[];
+/**
+ * Local sealed files required to rebuild one component module. This is the File half of the exact
+ * build plan used by {@link componentModuleKey}: the entry and its statically imported helpers.
+ * Component-only imports stop at stable registry refs; package pins and linked-system files stay in
+ * the key but have no local bytes for this branch to fetch.
+ */
+declare function componentModuleFilePaths(config: Config, filePath: string): readonly string[];
+/**
+ * One sealed local file's web module key, or `undefined` when the file is not sealed. Stable across
+ * clients: the key is a sorted-serialization content hash, so two holders of one config spell it
+ * identically.
+ */
+declare function componentModuleKey(config: Config, filePath: string): string | undefined;
+/**
+ * Resolve a component ref through config-v2's existing Component -> File facts to the independently
+ * rebuildable module that owns it. Studio-authored anatomy has no File and linked source files are
+ * not owned by this config's branch, so neither claims a local runtime URL.
+ */
+declare function componentModuleSource(config: Config, componentPathOrRef: string | Ref): ComponentModuleSource | undefined;
+//#endregion
+export { ComponentModuleSource, ComponentRegistryImport, ComponentRegistryImportBinding, componentModuleFilePaths, componentModuleKey, componentModuleSource, componentRegistryImports };