@xemahq/dsl 0.8.1 → 0.8.3

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

@@ -1,619 +0,0 @@
-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,
-  AgentWorkspaceSpec,
-} from './types';
-
-const DEFAULT_SURFACE_COMPAT: readonly ManifestSurfaceType[] = [
-  ManifestSurface.WORKFLOW,
-  ManifestSurface.AGENT_SESSION,
-] as const;
-
-/**
- * Compile a AgentWorkspaceSpec 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 AgentWorkspaceSpec;
-
-  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 AgentWorkspaceSpec['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,
-      stageKey: resolvedSpec.agent.stage,
-      role: resolvedSpec.agent.role,
-      ...(resolvedSpec.agent.deliverableSpecRef === undefined
-        ? {}
-        : { deliverableSpecRef: resolvedSpec.agent.deliverableSpecRef }),
-      ...(resolvedSpec.agent.defaultModel === undefined
-        ? {}
-        : { defaultModel: resolvedSpec.agent.defaultModel as ModelRef }),
-      ...(resolvedSpec.agent.instructions === undefined
-        ? {}
-        : { instructions: resolvedSpec.agent.instructions }),
-      ...(resolvedSpec.agent.promptMode === undefined
-        ? {}
-        : { promptMode: resolvedSpec.agent.promptMode }),
-      ...(resolvedSpec.agent.permission === undefined
-        ? {}
-        : { permission: resolvedSpec.agent.permission }),
-      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: AgentWorkspaceSpec['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: AgentWorkspaceSpec['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 }),
-    ...(s.instructions === undefined ? {} : { instructions: s.instructions }),
-    ...(s.promptMode === undefined ? {} : { promptMode: s.promptMode }),
-    ...(s.permission === undefined ? {} : { permission: s.permission }),
-  }));
-}
-
-function compileSkills(
-  skills: AgentWorkspaceSpec['spec']['skills'],
-): readonly CompiledManifestSkillRef[] {
-  return (skills ?? []).map((s) => ({
-    slug: s.slug,
-    ...(s.version !== undefined ? { version: s.version } : {}),
-  }));
-}
-
-function compileToolSelection(
-  toolSelection: AgentWorkspaceSpec['spec']['toolSelection'],
-): readonly ToolSelectionEntry[] {
-  return (toolSelection ?? []).map((entry) => ({ ...entry }));
-}
-
-function compileCredentials(
-  spec: AgentWorkspaceSpec['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: AgentWorkspaceSpec['spec']['permissions'],
-): CompiledManifestPermissions {
-  return {
-    tools: {
-      allow: permissions?.tools.allow ?? [],
-      deny: permissions?.tools.deny ?? [],
-    },
-  };
-}
-
-function compilePersistence(
-  persistence: AgentWorkspaceSpec['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: AgentWorkspaceSpec['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: AgentWorkspaceSpec['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: AgentWorkspaceSpec,
-  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: AgentWorkspaceSpec['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: AgentWorkspaceSpec['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: AgentWorkspaceSpec['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.
-    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();
-}