@xemahq/dsl 0.1.1

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

@@ -0,0 +1,608 @@
+import yaml from 'js-yaml';
+import { ZodError } from 'zod';
+
+import {
+  AWP_V1_SPEC,
+  findSlot,
+  isKnownSlotKey,
+  isWorkingFileBinaryFormat,
+  WORKING_FILE_BINARY_FORMATS,
+} from '@xemahq/kernel-contracts/agent-workspace';
+import {
+  ManifestSurface,
+  OutputSurfaceKind,
+  type CompiledManifestCredential,
+  type CompiledManifestDisplay,
+  type CompiledManifestPermissions,
+  type CompiledManifestPersistence,
+  type CompiledManifestOutputSurface,
+  type CompiledManifestSkillRef,
+  type CompiledSlotPersistenceOverride,
+  type CompiledWorkingFile,
+  type ManifestSurface as ManifestSurfaceType,
+  type ModelRef,
+  type SubAgentBinding,
+} from '@xemahq/kernel-contracts/workflow';
+
+import type { ToolSelectionEntry } from '@xemahq/kernel-contracts/mcp-tool';
+
+import { interpolate } from './interpolate';
+import { WorkspaceManifestSchema } from './schema';
+import type {
+  CompileResult,
+  CompiledMountDeclaration,
+  CompiledSeedFile,
+  CompiledSeedFileSource,
+  ManifestInputDeclaration,
+  CompiledWorkspaceManifest,
+  ManifestIssue,
+  WorkspaceManifest,
+} from './types';
+
+const DEFAULT_SURFACE_COMPAT: readonly ManifestSurfaceType[] = [
+  ManifestSurface.WORKFLOW,
+  ManifestSurface.AGENT_SESSION,
+] as const;
+
+/**
+ * Compile a WorkspaceManifest YAML or object into a `CompiledWorkspaceManifest`.
+ * Stages:
+ *
+ *   1. YAML parse (if input is a string).
+ *   2. Zod schema validation — accumulate every issue.
+ *   3. Apply `bindInputs` defaults from `spec.inputs.*.default`.
+ *   4. Validate required inputs are present after defaulting.
+ *   5. Validate enum constraints on string inputs.
+ *   6. Walk the spec, resolve every `${input.x}` interpolation.
+ *   7. Validate declared mount slots against `AWP_V1_SPEC` (no platform
+ *      slots like `agents-md` declared by hand; they're auto-emitted).
+ *   8. Validate seedFile slots + paths.
+ *   9. Classify seed-file sources (inline vs template) — template names
+ *      are surfaced via `requiredTemplateNames` for the API service to
+ *      resolve against the templates table.
+ *
+ * Returns a `CompileResult` discriminated union — never throws. The
+ * editor's preview path needs every issue at once, and downstream
+ * persistence flows want a fail-fast 400 with the same shape; both get
+ * it without try/catch ceremony.
+ *
+ * The kernel package never resolves templates — that is a fetch of
+ * skill-bundle resources, done by the `agent-session-runtime` template
+ * resolver, not by the compiler.
+ */
+export function compileManifest(
+  input: string | unknown,
+  bindInputs: Readonly<Record<string, unknown>> = {},
+  options: Readonly<CompileManifestOptions> = {},
+): CompileResult {
+  const issues: ManifestIssue[] = [];
+
+  const parsed = parseYamlOrObject(input, issues);
+  if (parsed === undefined) {
+    return { ok: false, errors: issues };
+  }
+
+  const result = WorkspaceManifestSchema.safeParse(parsed);
+  if (!result.success) {
+    return { ok: false, errors: zodIssues(result.error) };
+  }
+  const manifest = result.data as WorkspaceManifest;
+
+  const inputResolutionMode = options.inputResolutionMode ?? 'strict';
+  const inputs = applyInputDefaults(manifest, bindInputs, issues, inputResolutionMode);
+  if (issues.length > 0) {
+    return { ok: false, errors: issues };
+  }
+
+  const { resolved, issues: interpIssues } = interpolate(manifest.spec, { inputs });
+  if (interpIssues.length > 0) {
+    return { ok: false, errors: interpIssues };
+  }
+  const resolvedSpec = resolved as WorkspaceManifest['spec'];
+
+  const compiledMounts = compileMounts(resolvedSpec, issues);
+  const compiledSeedFiles = compileSeedFiles(resolvedSpec, issues);
+  const compiledCredentials = compileCredentials(resolvedSpec, issues);
+  const compiledEnv = compileEnv(resolvedSpec, compiledCredentials, issues);
+  const compiledWorkingFiles = compileWorkingFiles(resolvedSpec, issues);
+
+  if (issues.length > 0) {
+    return { ok: false, errors: issues };
+  }
+
+  const requiredTemplateNames = collectTemplateNames(compiledSeedFiles);
+
+  const compiled: CompiledWorkspaceManifest = {
+    slug: manifest.metadata.slug,
+    version: manifest.metadata.version,
+    surfaceCompat: manifest.metadata.surfaceCompat ?? DEFAULT_SURFACE_COMPAT,
+    display: compileDisplay(manifest.metadata.display),
+    agent: {
+      slug: resolvedSpec.agent.slug,
+      groupKey: resolvedSpec.agent.phase,
+      role: resolvedSpec.agent.role,
+      ...(resolvedSpec.agent.deliverableSpecRef === undefined
+        ? {}
+        : { deliverableSpecRef: resolvedSpec.agent.deliverableSpecRef }),
+      ...(resolvedSpec.agent.defaultModel === undefined
+        ? {}
+        : { defaultModel: resolvedSpec.agent.defaultModel as ModelRef }),
+      subAgents: compileSubAgents(resolvedSpec.agent.subAgents),
+    },
+    mounts: compiledMounts,
+    skills: compileSkills(resolvedSpec.skills),
+    toolSelection: compileToolSelection(resolvedSpec.toolSelection),
+    credentials: compiledCredentials,
+    permissions: compilePermissions(resolvedSpec.permissions),
+    persistence: compilePersistence(resolvedSpec.persistence, issues),
+    outputSurface: compileOutputSurface(resolvedSpec.outputSurface),
+    seedFiles: compiledSeedFiles,
+    env: compiledEnv,
+    workingFiles: compiledWorkingFiles,
+    requiredTemplateNames,
+  };
+
+  return { ok: true, compiled };
+}
+
+function compileDisplay(
+  display: WorkspaceManifest['metadata']['display'],
+): CompiledManifestDisplay {
+  return {
+    ...(display?.title !== undefined ? { title: display.title } : {}),
+    ...(display?.blurb !== undefined ? { blurb: display.blurb } : {}),
+    ...(display?.icon !== undefined ? { icon: display.icon } : {}),
+    ...(display?.category !== undefined ? { category: display.category } : {}),
+    badges: display?.badges ?? [],
+    ...(display?.sortOrder !== undefined ? { sortOrder: display.sortOrder } : {}),
+    hidden: display?.hidden ?? false,
+    ...(display?.ctaText !== undefined ? { ctaText: display.ctaText } : {}),
+    curated: display?.curated ?? false,
+  };
+}
+
+function compileSubAgents(
+  subAgents: WorkspaceManifest['spec']['agent']['subAgents'],
+): readonly SubAgentBinding[] {
+  return (subAgents ?? []).map((s) => ({
+    slug: s.slug,
+    ...(s.alias !== undefined ? { alias: s.alias } : {}),
+    ...(s.defaultModel !== undefined
+      ? { modelOverride: s.defaultModel as ModelRef }
+      : {}),
+  }));
+}
+
+function compileSkills(
+  skills: WorkspaceManifest['spec']['skills'],
+): readonly CompiledManifestSkillRef[] {
+  return (skills ?? []).map((s) => ({
+    slug: s.slug,
+    ...(s.version !== undefined ? { version: s.version } : {}),
+  }));
+}
+
+function compileToolSelection(
+  toolSelection: WorkspaceManifest['spec']['toolSelection'],
+): readonly ToolSelectionEntry[] {
+  return (toolSelection ?? []).map((entry) => ({ ...entry }));
+}
+
+function compileCredentials(
+  spec: WorkspaceManifest['spec'],
+  issues: ManifestIssue[],
+): readonly CompiledManifestCredential[] {
+  const out: CompiledManifestCredential[] = [];
+  const seen = new Set<string>();
+  for (const [idx, c] of (spec.credentials ?? []).entries()) {
+    if (seen.has(c.name)) {
+      issues.push({
+        path: `$.spec.credentials[${idx}].name`,
+        message: `duplicate credential name '${c.name}'`,
+      });
+      continue;
+    }
+    seen.add(c.name);
+    out.push({
+      name: c.name,
+      kind: c.kind,
+      sourceRef: c.sourceRef,
+      required: c.required ?? false,
+    });
+  }
+  return out;
+}
+
+function compilePermissions(
+  permissions: WorkspaceManifest['spec']['permissions'],
+): CompiledManifestPermissions {
+  return {
+    tools: {
+      allow: permissions?.tools.allow ?? [],
+      deny: permissions?.tools.deny ?? [],
+    },
+  };
+}
+
+function compilePersistence(
+  persistence: WorkspaceManifest['spec']['persistence'],
+  issues: ManifestIssue[],
+): CompiledManifestPersistence {
+  const overrides: Record<string, CompiledSlotPersistenceOverride> = {};
+  const sourceOverrides = persistence?.overrides;
+  if (sourceOverrides) {
+    for (const [slotKey, override] of Object.entries(sourceOverrides)) {
+      // Slot key must exist in the kernel spec.
+      if (!isKnownSlotKey(AWP_V1_SPEC, slotKey)) {
+        issues.push({
+          path: `spec.persistence.overrides.${slotKey}`,
+          message: `unknown slot key "${slotKey}" — not present in AWP v1 spec`,
+        });
+        continue;
+      }
+      // Overriding a slot only makes sense if its default policy is
+      // `git-push` — `tarball` and `none` have no fields to tune.
+      const slot = findSlot(AWP_V1_SPEC, slotKey);
+      if (slot?.persistencePolicy?.kind !== 'git-push') {
+        issues.push({
+          path: `spec.persistence.overrides.${slotKey}`,
+          message: `slot "${slotKey}" is not git-push-persisted (default kind: ${slot?.persistencePolicy?.kind ?? 'none'}) — override has no effect`,
+        });
+        continue;
+      }
+      overrides[slotKey] = override;
+    }
+  }
+  return {
+    paths: persistence?.paths ?? [],
+    overrides,
+  };
+}
+
+function compileOutputSurface(
+  outputSurface: WorkspaceManifest['spec']['outputSurface'],
+): CompiledManifestOutputSurface {
+  if (outputSurface === undefined) {
+    return { kind: OutputSurfaceKind.NONE, autoOpen: false, mode: 'single' };
+  }
+  const base = {
+    kind: outputSurface.kind,
+    ...(outputSurface.port !== undefined ? { port: outputSurface.port } : {}),
+    ...(outputSurface.healthPath !== undefined
+      ? { healthPath: outputSurface.healthPath }
+      : {}),
+    autoOpen: outputSurface.autoOpen ?? false,
+    mode: outputSurface.mode ?? 'single',
+  };
+  if (outputSurface.kind === OutputSurfaceKind.STATIC) {
+    // Schema guarantees `root !== undefined` when kind === 'static'.
+    return {
+      ...base,
+      root: outputSurface.root!,
+      defaultDocument: outputSurface.defaultDocument ?? 'index.html',
+    };
+  }
+  return base;
+}
+
+/**
+ * Compile env vars and validate that any `${credential.NAME}` reference
+ * points at a declared credential. Keeps the env block safe from typos
+ * — at compile time the manifest already knows every credential its
+ * runtime resolver will be asked to fetch.
+ */
+function compileEnv(
+  spec: WorkspaceManifest['spec'],
+  credentials: readonly CompiledManifestCredential[],
+  issues: ManifestIssue[],
+): readonly { readonly name: string; readonly value: string }[] {
+  const declaredNames = new Set(credentials.map((c) => c.name));
+  const out: { name: string; value: string }[] = [];
+  for (const [idx, e] of (spec.env ?? []).entries()) {
+    for (const m of e.value.matchAll(/\$\{\s*credential\.([A-Z_][A-Z0-9_]*)\s*\}/g)) {
+      const credName = m[1]!;
+      if (!declaredNames.has(credName)) {
+        issues.push({
+          path: `$.spec.env[${idx}].value`,
+          message: `env var '${e.name}' references undeclared credential '${credName}'`,
+        });
+      }
+    }
+    out.push({ name: e.name, value: e.value });
+  }
+  return out;
+}
+
+function parseYamlOrObject(
+  input: string | unknown,
+  issues: ManifestIssue[],
+): unknown | undefined {
+  if (typeof input !== 'string') return input;
+  try {
+    return yaml.load(input);
+  } catch (error) {
+    issues.push({ path: '$', message: `YAML parse error: ${(error as Error).message}` });
+    return undefined;
+  }
+}
+
+function zodIssues(error: ZodError): ManifestIssue[] {
+  return error.issues.map((iss) => ({
+    path: '$' + (iss.path.length > 0 ? '.' + iss.path.join('.') : ''),
+    message: iss.message,
+  }));
+}
+
+function applyInputDefaults(
+  manifest: WorkspaceManifest,
+  bindInputs: Readonly<Record<string, unknown>>,
+  issues: ManifestIssue[],
+  inputResolutionMode: InputResolutionMode,
+): Record<string, unknown> {
+  const declared = manifest.spec.inputs ?? {};
+  const out: Record<string, unknown> = { ...bindInputs };
+  const synthesizedInputs = new Set<string>();
+  for (const [name, decl] of Object.entries(declared)) {
+    if (out[name] === undefined && decl.default !== undefined) {
+      out[name] = decl.default as unknown;
+    }
+    if (out[name] === undefined) {
+      if (inputResolutionMode === 'deferred') {
+        out[name] = placeholderForInputType(name, decl.type);
+        synthesizedInputs.add(name);
+      } else if (decl.required === true) {
+        issues.push({
+          path: `$.spec.inputs.${name}`,
+          message: `required input '${name}' was not supplied and has no default`,
+        });
+        continue;
+      }
+    }
+    if (
+      decl.enum !== undefined &&
+      out[name] !== undefined &&
+      typeof out[name] === 'string' &&
+      !synthesizedInputs.has(name) &&
+      !decl.enum.includes(out[name] as string)
+    ) {
+      issues.push({
+        path: `$.spec.inputs.${name}`,
+        message: `input '${name}' value '${String(out[name])}' is not in enum [${decl.enum.join(', ')}]`,
+      });
+    }
+  }
+  for (const provided of Object.keys(bindInputs)) {
+    if (!Object.prototype.hasOwnProperty.call(declared, provided)) {
+      issues.push({
+        path: `$.spec.inputs.${provided}`,
+        message: `bind input '${provided}' is not declared in spec.inputs`,
+      });
+    }
+  }
+  return out;
+}
+
+function placeholderForInputType(
+  name: string,
+  type: ManifestInputDeclaration['type'],
+): unknown {
+  switch (type) {
+    case 'string':
+      return `${name}-deferred`;
+    case 'string[]':
+      return [`${name}-deferred`];
+    case 'boolean':
+      return true;
+    case 'number':
+      return 1;
+    case 'object[]':
+      return [];
+  }
+}
+
+type InputResolutionMode = 'strict' | 'deferred';
+
+export interface CompileManifestOptions {
+  /**
+   * strict: missing required inputs fail compilation.
+   * deferred: synthesize typed placeholders for missing declared inputs,
+   * allowing authoring-time compile/validation without runtime bind values.
+   */
+  readonly inputResolutionMode?: InputResolutionMode;
+}
+
+function compileMounts(
+  spec: WorkspaceManifest['spec'],
+  issues: ManifestIssue[],
+): Record<string, CompiledMountDeclaration> {
+  const out: Record<string, CompiledMountDeclaration> = {};
+  const declared = spec.mounts ?? {};
+  const PLATFORM_SLOTS: ReadonlySet<string> = new Set([
+    'agents-md',
+    'context-json',
+    'agent-bundles',
+    'skill-bundles',
+    'instructions',
+  ]);
+
+  for (const [slotKey, value] of Object.entries(declared)) {
+    if (!isKnownSlotKey(AWP_V1_SPEC, slotKey)) {
+      issues.push({
+        path: `$.spec.mounts.${slotKey}`,
+        message: `unknown slot '${slotKey}' — must be one of ${AWP_V1_SPEC.slots.map((s) => s.key).join(', ')}`,
+      });
+      continue;
+    }
+    if (PLATFORM_SLOTS.has(slotKey)) {
+      issues.push({
+        path: `$.spec.mounts.${slotKey}`,
+        message: `slot '${slotKey}' is platform-rendered and auto-emitted by the composer — do not declare it in mounts`,
+      });
+      continue;
+    }
+    if (typeof value === 'boolean') {
+      out[slotKey] = { enabled: value, config: {} };
+      continue;
+    }
+    if (value === null || typeof value !== 'object') {
+      issues.push({
+        path: `$.spec.mounts.${slotKey}`,
+        message: `mount declaration must be a boolean or an object`,
+      });
+      continue;
+    }
+    const config = { ...(value as Record<string, unknown>) };
+    const mode = config['mode'];
+    delete config['mode'];
+    if (mode !== undefined && mode !== 'read-only' && mode !== 'read-write') {
+      issues.push({
+        path: `$.spec.mounts.${slotKey}.mode`,
+        message: `mode must be 'read-only' or 'read-write'`,
+      });
+      continue;
+    }
+    out[slotKey] = {
+      enabled: true,
+      ...(mode === undefined ? {} : { mode: mode as 'read-only' | 'read-write' }),
+      config,
+    };
+  }
+  return out;
+}
+
+function compileSeedFiles(
+  spec: WorkspaceManifest['spec'],
+  issues: ManifestIssue[],
+): readonly CompiledSeedFile[] {
+  const out: CompiledSeedFile[] = [];
+  for (const [idx, sf] of (spec.seedFiles ?? []).entries()) {
+    const slotKey = sf.slot ?? 'inputs';
+    const slotDef = AWP_V1_SPEC.slots.find((s) => s.key === slotKey);
+    if (!slotDef) {
+      issues.push({
+        path: `$.spec.seedFiles[${idx}].slot`,
+        message: `unknown slot '${slotKey}'`,
+      });
+      continue;
+    }
+    if (slotDef.singleFile === true) {
+      issues.push({
+        path: `$.spec.seedFiles[${idx}]`,
+        message: `slot '${slotKey}' is a single-file slot — seed files must target a multi-file slot`,
+      });
+      continue;
+    }
+    if (sf.path.startsWith('/') || sf.path.includes('..')) {
+      issues.push({
+        path: `$.spec.seedFiles[${idx}].path`,
+        message: `path must be relative and contain no '..' segments`,
+      });
+      continue;
+    }
+    let source: CompiledSeedFileSource;
+    if (sf.template !== undefined) {
+      source = {
+        kind: 'template',
+        name: sf.template,
+        vars: sf.vars ?? {},
+      };
+    } else if (sf.content !== undefined) {
+      source = {
+        kind: 'inline',
+        bytesBase64: Buffer.from(sf.content, 'utf8').toString('base64'),
+      };
+    } else {
+      issues.push({
+        path: `$.spec.seedFiles[${idx}]`,
+        message: `seedFile must declare either 'template' or 'content'`,
+      });
+      continue;
+    }
+    out.push({ slot: slotKey, relPath: sf.path, source });
+  }
+  return out;
+}
+
+/**
+ * Compile + validate `spec.workingFiles[]`. Interpolation already ran on
+ * `path` / `sourceRef` values during the `interpolate()` walk earlier in
+ * the pipeline, so this function only enforces cross-binding invariants:
+ *
+ *   - `slug` is unique within the manifest.
+ *   - The file basename (path's last `/`-segment, sans extension) equals
+ *     `slug` — the agent reads $XEMA_WORKING_FILE_PATH and expects the
+ *     basename to match the slug it sees on `context.json.workingFiles`.
+ */
+function compileWorkingFiles(
+  spec: WorkspaceManifest['spec'],
+  issues: ManifestIssue[],
+): readonly CompiledWorkingFile[] {
+  const out: CompiledWorkingFile[] = [];
+  const seenSlugs = new Set<string>();
+  for (const [idx, wf] of (spec.workingFiles ?? []).entries()) {
+    if (seenSlugs.has(wf.slug)) {
+      issues.push({
+        path: `$.spec.workingFiles[${idx}].slug`,
+        message: `duplicate workingFile slug '${wf.slug}'`,
+      });
+      continue;
+    }
+    seenSlugs.add(wf.slug);
+    const basename = wf.path.split('/').pop() ?? '';
+    const basenameNoExt = basename.includes('.')
+      ? basename.slice(0, basename.lastIndexOf('.'))
+      : basename;
+    // Skip the basename↔slug parity check when either side carries an
+    // unresolved `${input.x}` template token — the workspace pipeline
+    // re-runs this check on the resolved literals at session-time.
+    const hasTemplate =
+      basenameNoExt.includes('${') || wf.slug.includes('${');
+    if (!hasTemplate && basenameNoExt !== wf.slug) {
+      issues.push({
+        path: `$.spec.workingFiles[${idx}].path`,
+        message:
+          `workingFile path basename '${basenameNoExt}' must equal slug '${wf.slug}' ` +
+          `so the agent's mental model of <slug> and the on-disk file stay aligned`,
+      });
+      continue;
+    }
+    // `binaryFormat` is the closed-enum hint that signals a companion
+    // binary (XLSX/PPTX/DOCX/PDF) lives alongside the synopsis. Validate now so
+    // a typo cannot reach the worker as a silent no-op — see
+    // `.claude/plans/xlsx-pptx-binary-kb-attachment.md` D6.
+    const binaryFormatRaw = wf.sourceRef['binaryFormat'];
+    if (
+      typeof binaryFormatRaw === 'string' &&
+      binaryFormatRaw.length > 0 &&
+      !binaryFormatRaw.includes('${') &&
+      !isWorkingFileBinaryFormat(binaryFormatRaw)
+    ) {
+      issues.push({
+        path: `$.spec.workingFiles[${idx}].sourceRef.binaryFormat`,
+        message:
+          `unknown binaryFormat '${binaryFormatRaw}'; expected one of ` +
+          `${WORKING_FILE_BINARY_FORMATS.join(', ')}`,
+      });
+      continue;
+    }
+    out.push({
+      slug: wf.slug,
+      path: wf.path,
+      format: wf.format,
+      syncDirection: wf.syncDirection,
+      sourceKind: wf.sourceKind,
+      sourceRef: { ...wf.sourceRef },
+    });
+  }
+  return out;
+}
+
+function collectTemplateNames(seedFiles: readonly CompiledSeedFile[]): readonly string[] {
+  const names = new Set<string>();
+  for (const sf of seedFiles) {
+    if (sf.source.kind === 'template') {
+      names.add(sf.source.name);
+    }
+  }
+  return [...names].sort();
+}