@xemahq/dsl 0.1.1

package/src/workspace-manifest/lib/interpolate.ts

@@ -0,0 +1,140 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Variable interpolation engine ──
+//
+// Resolves `${input.x}` and `${input.x | default: 'foo'}` references in
+// manifest values. Closed grammar — no arbitrary expressions, no
+// arithmetic, no function calls. The Monaco editor renders matching
+// inputs from `spec.inputs.*` for autocomplete; anything else is a
+// validation error.
+//
+// Restricted vs the workflow DSL's full expression engine because
+// manifests are simpler conceptually: they're parameterized templates,
+// not control flow. Keeping the interpolator narrow lets us reason
+// about manifest correctness at compile time.
+// ═══════════════════════════════════════════════════════════════════════════
+
+const INTERPOLATION_RE = /\$\{\s*([^}]+?)\s*\}/g;
+const INPUT_PATH_RE = /^input\.([a-zA-Z_][a-zA-Z0-9_]*)(?:\s*\|\s*default:\s*(.+))?$/;
+
+export interface InterpolationContext {
+  readonly inputs: Readonly<Record<string, unknown>>;
+}
+
+export interface InterpolationIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+/**
+ * Walks `value` recursively, resolving every `${input.x}` reference
+ * against `ctx.inputs`. Returns a fully-resolved deep clone with no
+ * remaining interpolation tokens.
+ *
+ * Issues are accumulated and returned alongside the partially-resolved
+ * tree so the compiler can report all problems together. When `issues`
+ * is non-empty, the returned tree may contain unresolved tokens — the
+ * caller MUST check `issues.length` before treating the result as
+ * authoritative.
+ */
+export function interpolate(
+  value: unknown,
+  ctx: InterpolationContext,
+  basePath = '$',
+): { readonly resolved: unknown; readonly issues: readonly InterpolationIssue[] } {
+  const issues: InterpolationIssue[] = [];
+  const resolved = walk(value, ctx, basePath, issues);
+  return { resolved, issues };
+}
+
+function walk(
+  value: unknown,
+  ctx: InterpolationContext,
+  path: string,
+  issues: InterpolationIssue[],
+): unknown {
+  if (typeof value === 'string') return interpolateString(value, ctx, path, issues);
+  if (Array.isArray(value)) {
+    return value.map((item, idx) => walk(item, ctx, `${path}[${idx}]`, issues));
+  }
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+      out[key] = walk(child, ctx, `${path}.${key}`, issues);
+    }
+    return out;
+  }
+  return value;
+}
+
+function interpolateString(
+  raw: string,
+  ctx: InterpolationContext,
+  path: string,
+  issues: InterpolationIssue[],
+): string | unknown {
+  // Whole-string single-token: preserve original type (e.g.
+  // `${input.kbSpaceIds}` resolves to an array, not its toString).
+  const wholeMatch = /^\$\{\s*([^}]+?)\s*\}$/.exec(raw);
+  if (wholeMatch) {
+    return resolveToken(wholeMatch[1]!, ctx, path, issues);
+  }
+
+  return raw.replace(INTERPOLATION_RE, (_full, token: string) => {
+    const resolved = resolveToken(token, ctx, path, issues);
+    if (resolved === undefined || resolved === null) return '';
+    return Array.isArray(resolved) ? resolved.join(',') : String(resolved);
+  });
+}
+
+function resolveToken(
+  token: string,
+  ctx: InterpolationContext,
+  path: string,
+  issues: InterpolationIssue[],
+): unknown {
+  const m = INPUT_PATH_RE.exec(token);
+  if (!m) {
+    issues.push({
+      path,
+      message: `unsupported interpolation token '\${${token}}' — only \${input.<name>} and \${input.<name> | default: <literal>} are allowed`,
+    });
+    return undefined;
+  }
+  const inputName = m[1]!;
+  const defaultLiteral = m[2];
+  const present = Object.prototype.hasOwnProperty.call(ctx.inputs, inputName);
+  if (present) {
+    return ctx.inputs[inputName];
+  }
+  if (defaultLiteral !== undefined) {
+    return parseLiteral(defaultLiteral, path, issues);
+  }
+  issues.push({
+    path,
+    message: `unresolved input '\${input.${inputName}}' — declare it in spec.inputs or supply a default with '| default: ...'`,
+  });
+  return undefined;
+}
+
+function parseLiteral(
+  raw: string,
+  path: string,
+  issues: InterpolationIssue[],
+): unknown {
+  const trimmed = raw.trim();
+  if (
+    (trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+    (trimmed.startsWith('"') && trimmed.endsWith('"'))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  if (trimmed === 'true') return true;
+  if (trimmed === 'false') return false;
+  const num = Number(trimmed);
+  if (!Number.isNaN(num) && trimmed !== '') return num;
+  issues.push({
+    path,
+    message: `default literal '${raw}' is not a string ('foo'/"foo"), boolean, or number`,
+  });
+  return undefined;
+}

package/src/workspace-manifest/lib/resolve-extends.ts

@@ -0,0 +1,260 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── WorkspaceManifest `extends:` resolver ──
+//
+// Section 4.4 of the engineering plan. Provides a deterministic merge
+// primitive plus a thin orchestrator the composer / preview endpoint /
+// llm-registry calls to materialize the effective manifest.
+//
+// Design constraints:
+//   • Single-level extends only. The base MUST NOT carry its own
+//     `extends:` — keeps semantics deterministic, avoids resolution
+//     cycles, and lets every consumer reason about the merged shape
+//     without recursion. Multi-level inheritance can ship later if
+//     real demand surfaces.
+//   • Caller injects the `lookupBase(ref)` function. The kernel
+//     package stays runtime-dep-free; the llm-registry-api composition
+//     seeder and the composer each provide their own lookup
+//     implementation.
+//   • Failures are typed errors, never silent fallbacks. Missing ref,
+//     base-with-extends, or wrong shape — all surface as
+//     {@link ManifestExtendsError}.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { ToolSelectionEntry } from '@xemahq/kernel-contracts/mcp-tool';
+
+import type {
+  ManifestCredential,
+  ManifestEnvVar,
+  ManifestInputDeclaration,
+  ManifestMountDeclaration,
+  ManifestPermissions,
+  ManifestPersistence,
+  ManifestOutputSurface,
+  ManifestSeedFile,
+  ManifestSkillRef,
+  ManifestWorkingFile,
+  WorkspaceManifest,
+  WorkspaceManifestSpec,
+} from './types';
+
+/**
+ * Caller-supplied lookup function. Returns the parsed manifest for the
+ * given `xema://manifest/<slug>@<version>` reference, or `null` when no
+ * row exists at any scope tier. Implementations:
+ *   • The composition seeder: in-memory map built over every manifest
+ *     enumerated across the biome tree.
+ *   • Tests: in-memory map.
+ */
+export type ManifestBaseLookup = (
+  ref: string,
+) => Promise<WorkspaceManifest | null>;
+
+export class ManifestExtendsError extends Error {
+  constructor(
+    message: string,
+    readonly code:
+      | 'BASE_NOT_FOUND'
+      | 'BASE_HAS_EXTENDS'
+      | 'BASE_MALFORMED'
+      | 'INVALID_REF',
+    readonly ref: string,
+  ) {
+    super(message);
+    this.name = 'ManifestExtendsError';
+  }
+}
+
+/**
+ * Resolve a manifest's `extends:` directive. Returns the manifest
+ * unchanged when no `extends:` was authored. Otherwise fetches the
+ * base via `lookupBase` and merges; the returned manifest carries the
+ * effective shape with `extends` cleared (the merge is one-shot).
+ */
+export async function resolveManifestExtends(
+  authored: WorkspaceManifest,
+  lookupBase: ManifestBaseLookup,
+): Promise<WorkspaceManifest> {
+  if (!authored.extends) return authored;
+  const ref = authored.extends;
+  const base = await lookupBase(ref);
+  if (base === null) {
+    throw new ManifestExtendsError(
+      `manifest base '${ref}' not found at any scope tier (project/org/biome/system)`,
+      'BASE_NOT_FOUND',
+      ref,
+    );
+  }
+  if (base.extends) {
+    throw new ManifestExtendsError(
+      `manifest base '${ref}' itself carries \`extends: ${base.extends}\`; multi-level inheritance is not supported (single-level only)`,
+      'BASE_HAS_EXTENDS',
+      ref,
+    );
+  }
+  if (base.kind !== 'WorkspaceManifest' || base.apiVersion !== 'xema.dev/workspace/v1') {
+    throw new ManifestExtendsError(
+      `manifest base '${ref}' has unexpected envelope (apiVersion=${String(base.apiVersion)}, kind=${String(base.kind)})`,
+      'BASE_MALFORMED',
+      ref,
+    );
+  }
+  const mergedSpec = mergeSpecs(base.spec, authored.spec);
+  return {
+    apiVersion: authored.apiVersion,
+    kind: authored.kind,
+    metadata: authored.metadata,
+    spec: mergedSpec,
+  };
+}
+
+/**
+ * Deterministic merge between a base spec and a child spec.
+ *
+ * Rules (closed set, no surprises):
+ *   • `inputs`             — key-union; child's declaration wins on conflict.
+ *   • `mounts`             — key-union; child's declaration wins on conflict.
+ *   • `seedFiles`          — concatenated (base first); duplicates by
+ *                            `path` keep the LAST occurrence (child wins).
+ *   • `env`                — concatenated (base first); duplicates by
+ *                            `name` keep the LAST occurrence (child wins).
+ *   • `skills`             — concatenated (base first); dedup by `slug`,
+ *                            child wins on version pin conflict.
+ *   • `toolSelection`      — concatenated (base first); dedup by
+ *                            `(providerKind, resourceId, toolName?)`,
+ *                            child wins on conflict.
+ *   • `credentials`        — concatenated (base first); dedup by `name`,
+ *                            child wins on kind/sourceRef/required.
+ *   • `permissions`        — child fully replaces base when present;
+ *                            otherwise base flows through. Permissions
+ *                            are intentionally NOT unioned — narrowing
+ *                            authority on top of a base must be explicit
+ *                            and total, never a piecewise diff.
+ *   • `persistence`        — child fully replaces base when present.
+ *                            Persistence paths are a snapshot contract;
+ *                            unioning silently would leak state across
+ *                            unrelated profiles.
+ *   • `outputSurface`      — child fully replaces base when present.
+ *   • `workingFiles`       — concatenated (base first); dedup by `slug`,
+ *                            child wins on conflict. Lets the base seed
+ *                            shared working files while letting a child
+ *                            add document-buddy bindings without losing
+ *                            them to a silent drop.
+ *   • `agent`              — child's block fully replaces the base's.
+ *                            The agent identity is not inheritable.
+ *
+ * Empty / missing optional fields on either side are tolerated; the
+ * merged spec carries them only when at least one side did.
+ */
+export function mergeSpecs(
+  base: WorkspaceManifestSpec,
+  child: WorkspaceManifestSpec,
+): WorkspaceManifestSpec {
+  const merged: WorkspaceManifestSpec = {
+    agent: child.agent,
+  };
+
+  const inputs = mergeRecord<ManifestInputDeclaration>(base.inputs, child.inputs);
+  if (inputs) (merged as { inputs?: typeof inputs }).inputs = inputs;
+
+  const mounts = mergeRecord<ManifestMountDeclaration>(base.mounts, child.mounts);
+  if (mounts) (merged as { mounts?: typeof mounts }).mounts = mounts;
+
+  const seedFiles = mergeUniqueByKey<ManifestSeedFile>(
+    base.seedFiles,
+    child.seedFiles,
+    (sf) => sf.path,
+  );
+  if (seedFiles) (merged as { seedFiles?: typeof seedFiles }).seedFiles = seedFiles;
+
+  const env = mergeUniqueByKey<ManifestEnvVar>(
+    base.env,
+    child.env,
+    (e) => e.name,
+  );
+  if (env) (merged as { env?: typeof env }).env = env;
+
+  const skills = mergeUniqueByKey<ManifestSkillRef>(
+    base.skills,
+    child.skills,
+    (s) => s.slug,
+  );
+  if (skills) (merged as { skills?: typeof skills }).skills = skills;
+
+  const toolSelection = mergeUniqueByKey<ToolSelectionEntry>(
+    base.toolSelection,
+    child.toolSelection,
+    toolSelectionEntryKey,
+  );
+  if (toolSelection)
+    (merged as { toolSelection?: typeof toolSelection }).toolSelection = toolSelection;
+
+  const credentials = mergeUniqueByKey<ManifestCredential>(
+    base.credentials,
+    child.credentials,
+    (c) => c.name,
+  );
+  if (credentials)
+    (merged as { credentials?: typeof credentials }).credentials = credentials;
+
+  const permissions: ManifestPermissions | undefined =
+    child.permissions ?? base.permissions;
+  if (permissions)
+    (merged as { permissions?: ManifestPermissions }).permissions = permissions;
+
+  const persistence: ManifestPersistence | undefined =
+    child.persistence ?? base.persistence;
+  if (persistence)
+    (merged as { persistence?: ManifestPersistence }).persistence = persistence;
+
+  const outputSurface: ManifestOutputSurface | undefined =
+    child.outputSurface ?? base.outputSurface;
+  if (outputSurface)
+    (merged as { outputSurface?: ManifestOutputSurface }).outputSurface =
+      outputSurface;
+
+  const workingFiles = mergeUniqueByKey<ManifestWorkingFile>(
+    base.workingFiles,
+    child.workingFiles,
+    (wf) => wf.slug,
+  );
+  if (workingFiles)
+    (merged as { workingFiles?: typeof workingFiles }).workingFiles =
+      workingFiles;
+
+  return merged;
+}
+
+function mergeRecord<T>(
+  base: Record<string, T> | undefined,
+  child: Record<string, T> | undefined,
+): Record<string, T> | undefined {
+  if (!base && !child) return undefined;
+  return { ...(base ?? {}), ...(child ?? {}) };
+}
+
+function toolSelectionEntryKey(entry: ToolSelectionEntry): string {
+  return entry.kind === 'tool'
+    ? `tool:${entry.providerKind}:${entry.resourceId}:${entry.toolName}`
+    : `provider:${entry.providerKind}:${entry.resourceId}`;
+}
+
+function mergeUniqueByKey<T>(
+  base: readonly T[] | undefined,
+  child: readonly T[] | undefined,
+  keyOf: (item: T) => string,
+): readonly T[] | undefined {
+  if (!base && !child) return undefined;
+  const out: T[] = [];
+  const indexByKey = new Map<string, number>();
+  for (const item of [...(base ?? []), ...(child ?? [])]) {
+    const key = keyOf(item);
+    const existing = indexByKey.get(key);
+    if (existing === undefined) {
+      indexByKey.set(key, out.length);
+      out.push(item);
+    } else {
+      out[existing] = item;
+    }
+  }
+  return out;
+}