@xemahq/dsl 0.1.1

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

@@ -0,0 +1,612 @@
+import { z } from 'zod';
+
+import {
+  AGENT_RUN_ROLES,
+  type AgentRunRole,
+  CREDENTIAL_KINDS,
+  type CredentialKind,
+  MANIFEST_GIT_PUSH_BRANCH_SUFFIXES,
+  MANIFEST_GIT_PUSH_CONCURRENCY_MODES,
+  MANIFEST_SURFACES,
+  type ManifestGitPushBranchSuffix,
+  type ManifestGitPushConcurrencyMode,
+  type ManifestSurface,
+  ModelClassSchema,
+  OUTPUT_SURFACE_KINDS,
+  type OutputSurfaceKind,
+  TOOLSET_KEYS,
+  type ToolsetKey,
+} from '@xemahq/kernel-contracts/workflow';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Zod schema for WorkspaceManifest YAML ──
+//
+// Mirrors the TypeScript types in `./types.ts`. Used by `compileManifest`
+// for validation; the compiler surfaces issues as `ManifestIssue[]`
+// (inside `CompileResult`) so the Monaco editor can render inline diagnostics.
+// ═══════════════════════════════════════════════════════════════════════════
+
+const SlugRegex = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;
+const VersionRegex = /^\d+\.\d+\.\d+$/;
+
+export const ManifestInputDeclarationSchema = z.object({
+  type: z.enum(['string', 'string[]', 'boolean', 'number', 'object[]']),
+  required: z.boolean().optional(),
+  /**
+   * Default value. The accepted union mirrors `type`:
+   *   - `string`   → string
+   *   - `number`   → number
+   *   - `boolean`  → boolean
+   *   - `string[]` → readonly string[]
+   *   - `object[]` → readonly { [k: string]: unknown }[]  (structured
+   *                   list-of-objects; renderers consume the shape
+   *                   the producing manifest declares — the DSL does
+   *                   not enforce per-object key validation.)
+   */
+  default: z
+    .union([
+      z.string(),
+      z.number(),
+      z.boolean(),
+      z.array(z.string()),
+      z.array(z.record(z.string(), z.unknown())),
+    ])
+    .optional(),
+  enum: z.array(z.string()).optional(),
+  description: z.string().optional(),
+});
+
+/**
+ * Mount declaration: either a literal boolean (true=enable with defaults,
+ * false=disable inherited mount), OR a strict object with a closed set of
+ * configuration keys.
+ *
+ * Previously this was `z.record(z.string(), z.unknown())` which let any
+ * key/value through and made the renderer the de-facto validator. CLAUDE
+ * .md requires enums/closed sets at the boundary, so the object form is
+ * `.strict()` and rejects unknown keys at compile time.
+ */
+export const ManifestMountConfigSchema = z
+  .object({
+    mode: z.enum(['read-only', 'read-write']).optional(),
+    /** Override the mount source path (relative to the upstream root). */
+    source: z.string().min(1).optional(),
+    /** Override the path the mount appears at inside the workspace. */
+    path: z.string().min(1).optional(),
+  })
+  .strict();
+
+export const ManifestMountDeclarationSchema = z.union([
+  z.boolean(),
+  ManifestMountConfigSchema,
+]);
+
+/**
+ * Primitive-only value type for seed-file `vars`. Vars flow into
+ * Handlebars rendering; non-primitive values are a footgun (`.toString()`
+ * on `[object Object]`) and special keys like `__proto__` /
+ * `constructor` / `prototype` can pollute the template context, so we
+ * reject those at the schema layer.
+ */
+const SafeVarKeyRegex = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const RESERVED_VAR_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+export const ManifestVarsSchema = z
+  .record(
+    z
+      .string()
+      .regex(SafeVarKeyRegex, 'var name must match /^[a-zA-Z_][a-zA-Z0-9_]*$/'),
+    z.union([z.string(), z.number(), z.boolean()]),
+  )
+  .refine(
+    (vars) => Object.keys(vars).every((k) => !RESERVED_VAR_KEYS.has(k)),
+    {
+      message:
+        'seed-file vars cannot use reserved keys (__proto__, constructor, prototype)',
+    },
+  );
+
+/**
+ * Zod enum for AgentRunRole, sourced from the canonical kernel array.
+ * The cast to `readonly [AgentRunRole, ...AgentRunRole[]]` preserves
+ * the string-literal union under z.infer, so consumers (compileManifest
+ * → CompiledWorkspaceManifest.agent.role) get a strongly-typed value
+ * back, not a generic `string`.
+ */
+const AgentRunRoleEnumSchema = z.enum(
+  AGENT_RUN_ROLES as readonly [AgentRunRole, ...AgentRunRole[]],
+);
+
+/**
+ * Discriminated `ModelRef` for manifest-level model recommendations.
+ * Closed `kind` values match `@xemahq/workflow-contracts:ModelRef` and
+ * the `xema/agent` action manifest's `model` property.
+ */
+export const ManifestModelRefSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('concrete'),
+    modelId: z.string().min(1),
+    providerSlug: z.string().min(1).optional(),
+    temperature: z.number().min(0).max(2).optional(),
+  }),
+  z.object({
+    kind: z.literal('strategy'),
+    modelClass: ModelClassSchema,
+    temperature: z.number().min(0).max(2).optional(),
+  }),
+]);
+
+export const ManifestSubAgentSchema = z
+  .object({
+    slug: z
+      .string()
+      .min(1)
+      .regex(
+        /^[a-z][a-z0-9-]*$/,
+        'sub-agent slug must match /^[a-z][a-z0-9-]*$/',
+      ),
+    alias: z.string().max(64).optional(),
+    defaultModel: ManifestModelRefSchema.optional(),
+  })
+  .strict();
+
+export const ManifestAgentBlockSchema = z
+  .object({
+    slug: z.string().min(1),
+    phase: z.string().min(1),
+    /**
+     * The agent's role on the surface this manifest provisions. Closed
+     * enum — the canonical list lives in `@xemahq/kernel-contracts/workflow`'s
+     * `AGENT_RUN_ROLES`. Manifest upserts that name a role outside the
+     * list fail at compile time with a typed `ManifestIssue`.
+     */
+    role: AgentRunRoleEnumSchema,
+    deliverableSpecRef: z.string().optional(),
+    defaultModel: ManifestModelRefSchema.optional(),
+    subAgents: z.array(ManifestSubAgentSchema).optional(),
+  })
+  .strict()
+  .refine(
+    (a) => !a.subAgents || a.subAgents.every((s) => s.slug !== a.slug),
+    {
+      message:
+        'manifest agent block cannot bind itself as a sub-agent (no self-delegation)',
+    },
+  );
+
+/**
+ * Closed-set enum schemas built from the canonical kernel arrays. The
+ * cast to `[T, ...T[]]` preserves the literal-union under z.infer so
+ * compileManifest's output stays strongly typed.
+ */
+const ManifestSurfaceEnumSchema = z.enum(
+  MANIFEST_SURFACES as readonly [ManifestSurface, ...ManifestSurface[]],
+);
+
+const ToolsetKeyEnumSchema = z.enum(
+  TOOLSET_KEYS as readonly [ToolsetKey, ...ToolsetKey[]],
+);
+
+const CredentialKindEnumSchema = z.enum(
+  CREDENTIAL_KINDS as readonly [CredentialKind, ...CredentialKind[]],
+);
+
+const OutputSurfaceKindEnumSchema = z.enum(
+  OUTPUT_SURFACE_KINDS as readonly [OutputSurfaceKind, ...OutputSurfaceKind[]],
+);
+
+/** Generic slug used by skill refs. Looser than the manifest slug. */
+const RefSlugRegex = /^[a-z0-9][a-z0-9._-]*$/;
+const SemverRangeRegex = /^[~^]?\d+(\.\d+(\.\d+)?)?(-[a-zA-Z0-9.-]+)?$/;
+
+export const ManifestSkillRefSchema = z
+  .object({
+    slug: z.string().regex(RefSlugRegex, 'skill slug must match /^[a-z0-9][a-z0-9._-]*$/'),
+    version: z.string().regex(SemverRangeRegex, 'version must be a semver pin or range').optional(),
+  })
+  .strict();
+
+export const ManifestCredentialSchema = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .regex(/^[A-Z_][A-Z0-9_]*$/, 'credential names must be UPPER_SNAKE_CASE'),
+    kind: CredentialKindEnumSchema,
+    sourceRef: z.string().min(1),
+    required: z.boolean().optional(),
+  })
+  .strict();
+
+export const ManifestPermissionsSchema = z
+  .object({
+    tools: z
+      .object({
+        allow: z.array(ToolsetKeyEnumSchema).optional(),
+        deny: z.array(ToolsetKeyEnumSchema).optional(),
+      })
+      .strict(),
+  })
+  .strict();
+
+const PersistencePathRegex = /^[a-zA-Z0-9_.][a-zA-Z0-9_./-]*$/;
+
+const GitPushBranchSuffixEnumSchema = z.enum(
+  MANIFEST_GIT_PUSH_BRANCH_SUFFIXES as readonly [
+    ManifestGitPushBranchSuffix,
+    ...ManifestGitPushBranchSuffix[],
+  ],
+);
+
+const GitPushConcurrencyModeEnumSchema = z.enum(
+  MANIFEST_GIT_PUSH_CONCURRENCY_MODES as readonly [
+    ManifestGitPushConcurrencyMode,
+    ...ManifestGitPushConcurrencyMode[],
+  ],
+);
+
+/**
+ * Per-slot persistence policy override. Only `git-push` is overridable
+ * today because `tarball`/`none` have no fields a biome needs to tune.
+ * Schema is `.strict()` so a typo in a closed-set value fails compile.
+ */
+export const ManifestSlotPersistenceOverrideSchema = z
+  .object({
+    kind: z.literal('git-push'),
+    branchPrefix: z
+      .string()
+      .min(1)
+      .regex(
+        /^[a-zA-Z0-9][a-zA-Z0-9._\-/]*\/$/,
+        'branchPrefix must end with `/` and contain only [A-Za-z0-9._-/]',
+      ),
+    branchSuffix: GitPushBranchSuffixEnumSchema.optional(),
+    concurrencyMode: GitPushConcurrencyModeEnumSchema.optional(),
+  })
+  .strict();
+
+/**
+ * Keys allowed inside `persistence.overrides`. Closed to the slot keys
+ * that have a non-`none` persistence policy in the AWP kernel — today
+ * just `repos` (git-push) and `tmp` / `uploads` / `deliverables`
+ * (tarball, no overridable fields, so still rejected at runtime via
+ * the `kind: 'git-push'` literal). The compiler additionally validates
+ * the key is git-push-persisted on the resolved spec.
+ */
+const PersistenceOverrideKeyRegex = /^[a-z][a-z0-9-]*$/;
+
+export const ManifestPersistenceSchema = z
+  .object({
+    paths: z
+      .array(
+        z
+          .string()
+          .min(1)
+          .regex(PersistencePathRegex, 'persistence path must be /workspace/-relative')
+          .refine((p) => !p.includes('..'), {
+            message: "persistence path must not contain '..' segments",
+          })
+          .refine((p) => !p.startsWith('/'), {
+            message: 'persistence path must not start with /',
+          }),
+      )
+      .min(1),
+    /**
+     * Per-slot persistence policy overrides. Replaces the AWP kernel
+     * default for the named slot at session lifecycle time. The compile
+     * step additionally enforces that each key names a slot whose
+     * default policy is `git-push` — overriding a `tarball` or `none`
+     * slot is nonsense and fails fast.
+     */
+    overrides: z
+      .record(
+        z.string().regex(PersistenceOverrideKeyRegex, 'slot key must be kebab-case'),
+        ManifestSlotPersistenceOverrideSchema,
+      )
+      .optional(),
+  })
+  .strict();
+
+const StaticRootPathRegex = /^[a-zA-Z0-9_.][a-zA-Z0-9_./-]*$/;
+
+export const ManifestOutputSurfaceSchema = z
+  .object({
+    kind: OutputSurfaceKindEnumSchema,
+    port: z.number().int().min(1).max(65535).optional(),
+    healthPath: z
+      .string()
+      .min(1)
+      .regex(/^\//, 'healthPath must start with /')
+      .optional(),
+    autoOpen: z.boolean().optional(),
+    /**
+     * Single-port (legacy) vs. multi-app output surface. `single` is
+     * the historical behaviour and the default — one output surface
+     * process per session, pinned to `port`. `multi` flips workspace-proxy's
+     * output-surface supervisor into per-app mode: it discovers app targets
+     * (from `.xema/output-surface.yaml` or autodetection), allocates a port
+     * per app, and emits one gateway route per app. When `mode` is
+     * `multi`, the top-level `port` is ignored and may be omitted.
+     */
+    mode: z.enum(['single', 'multi']).optional(),
+    /**
+     * Workspace-relative directory served by the baked
+     * `static-artifact-server.mjs`. REQUIRED when `kind === 'static'`
+     * and REJECTED for any other kind.
+     */
+    root: z
+      .string()
+      .min(1)
+      .regex(StaticRootPathRegex, 'root must be a /workspace/-relative path')
+      .refine((p) => !p.includes('..'), {
+        message: "root must not contain '..' segments",
+      })
+      .refine((p) => !p.startsWith('/'), {
+        message: 'root must not start with /',
+      })
+      .optional(),
+    /**
+     * Default document name for directory requests under a `static`
+     * surface (e.g. `index.html`). Only meaningful when
+     * `kind === 'static'`.
+     */
+    defaultDocument: z
+      .string()
+      .min(1)
+      .regex(/^[a-zA-Z0-9_.][a-zA-Z0-9_.-]*$/, 'defaultDocument must be a plain filename')
+      .optional(),
+  })
+  .strict()
+  .superRefine((p, ctx) => {
+    if (p.kind === 'static') {
+      if (p.root === undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "outputSurface.root is required when kind === 'static'",
+          path: ['root'],
+        });
+      }
+      if (p.port !== undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "outputSurface.port is not allowed when kind === 'static' — the supervisor assigns the port",
+          path: ['port'],
+        });
+      }
+      if (p.mode !== undefined && p.mode !== 'single') {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "outputSurface.mode must be 'single' (or omitted) when kind === 'static'",
+          path: ['mode'],
+        });
+      }
+      return;
+    }
+    if (p.root !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `outputSurface.root is only valid when kind === 'static' (got kind="${p.kind}")`,
+        path: ['root'],
+      });
+    }
+    if (p.defaultDocument !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `outputSurface.defaultDocument is only valid when kind === 'static' (got kind="${p.kind}")`,
+        path: ['defaultDocument'],
+      });
+    }
+    if (p.kind !== 'none' && p.mode !== 'multi' && p.port === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "outputSurface.port is required when kind !== 'none' and mode !== 'multi'",
+        path: ['port'],
+      });
+    }
+  });
+
+export const ManifestDisplayMetadataSchema = z
+  .object({
+    title: z.string().min(1).optional(),
+    blurb: z.string().min(1).optional(),
+    icon: z.string().min(1).optional(),
+    category: z.string().min(1).optional(),
+    badges: z.array(z.string().min(1)).optional(),
+    sortOrder: z.number().int().optional(),
+    hidden: z.boolean().optional(),
+    ctaText: z.string().min(1).optional(),
+    curated: z.boolean().optional(),
+  })
+  .strict();
+
+export const ManifestSeedFileSchema = z
+  .object({
+    path: z.string().min(1),
+    slot: z.string().optional(),
+    template: z.string().optional(),
+    content: z.string().optional(),
+    vars: ManifestVarsSchema.optional(),
+  })
+  .refine(
+    (sf) => sf.template !== undefined || sf.content !== undefined,
+    { message: 'seedFile must declare either `template` or `content`' },
+  )
+  .refine(
+    (sf) => !(sf.template !== undefined && sf.content !== undefined),
+    { message: 'seedFile cannot declare both `template` and `content`' },
+  );
+
+export const ManifestEnvVarSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .regex(/^[A-Z_][A-Z0-9_]*$/, 'env var names must be UPPER_SNAKE_CASE'),
+  value: z.string(),
+});
+
+/**
+ * Working-file declaration (`spec.workingFiles[]`). Closed-set `format` /
+ * `syncDirection` enums; `path` is workspace-relative; `slug` is the
+ * stable agent-facing identifier; `sourceKind` is an open snake_case
+ * string registered with the worker's working-file engine; `sourceRef`
+ * is a kind-specific string map (values may carry `${input.x}`).
+ */
+const WORKING_FILE_PATH_RE = /^[a-zA-Z0-9_.][a-zA-Z0-9_./-]*$/;
+const WORKING_FILE_SLUG_RE = /^[a-z0-9][a-z0-9._-]*$/;
+const WORKING_FILE_SOURCE_KIND_RE = /^[a-z][a-z0-9-]*(?:_[a-z0-9-]+)*$/;
+
+/**
+ * Strip every `${input.x}` template token before applying a regex check.
+ * `workingFiles[].slug` and `workingFiles[].path` legitimately carry
+ * input-template tokens (one document buddy session per KB page, with
+ * `slug = ${input.pageSlug}`), and the post-`extends:` schema pass runs
+ * BEFORE input interpolation — so the validator MUST tolerate templates
+ * on the same characters the regex enforces on the resolved value.
+ *
+ * After interpolation the workspace pipeline re-validates the resolved
+ * literal, so loosening the schema here does not weaken the contract;
+ * it just moves the literal-shape check past the substitution boundary.
+ */
+const INPUT_TOKEN_RE = /\$\{\s*input\.[a-zA-Z_]\w*\s*\}/g;
+function stripInputTokens(value: string): string {
+  return value.replace(INPUT_TOKEN_RE, '');
+}
+
+export const ManifestWorkingFileSchema = z
+  .object({
+    slug: z
+      .string()
+      .min(1)
+      .refine(
+        (s) => WORKING_FILE_SLUG_RE.test(stripInputTokens(s) || 'a'),
+        'slug must match /^[a-z0-9][a-z0-9._-]*$/ (input-template tokens permitted)',
+      ),
+    path: z
+      .string()
+      .min(1)
+      .refine(
+        (p) => WORKING_FILE_PATH_RE.test(stripInputTokens(p) || 'a'),
+        'path must be a /workspace/-relative slash path (input-template tokens permitted)',
+      )
+      .refine((p) => !p.includes('..'), {
+        message: "path must not contain '..' segments",
+      })
+      .refine((p) => !p.startsWith('/'), {
+        message: 'path must not start with /',
+      }),
+    format: z.enum(['markdown', 'html', 'json', 'yaml', 'text']),
+    syncDirection: z.enum(['down-only', 'up-only', 'bidirectional']),
+    sourceKind: z
+      .string()
+      .min(1)
+      .regex(
+        WORKING_FILE_SOURCE_KIND_RE,
+        'sourceKind must be kebab-or-snake case (e.g. kb-page)',
+      ),
+    sourceRef: z.record(z.string().min(1), z.string()),
+  })
+  .strict();
+
+/**
+ * Default tool selection inherited by every session/run booted on
+ * this workspace. Shape matches the kernel `ToolSelectionEntry` from
+ * `@xemahq/kernel-contracts/mcp-tool`. Resolved at boot via mcp-gateway-api
+ * `POST /mcp-resolve` and dropped into `opencode.json:mcp`. Sessions
+ * may override per-instance via `PATCH /sessions/:id/tools`.
+ */
+export const ManifestToolSelectionEntrySchema = z.discriminatedUnion('kind', [
+  z
+    .object({
+      kind: z.literal('provider'),
+      providerKind: z.enum([
+        'mcp_server',
+        'catalog',
+        'biome_workflow_tools',
+        'biome_code_tools',
+      ]),
+      resourceId: z.string().min(1).max(256),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal('tool'),
+      providerKind: z.enum([
+        'mcp_server',
+        'catalog',
+        'biome_workflow_tools',
+        'biome_code_tools',
+      ]),
+      resourceId: z.string().min(1).max(256),
+      toolName: z.string().min(1).max(256),
+    })
+    .strict(),
+]);
+
+export const WorkspaceManifestSpecSchema = z.object({
+  inputs: z.record(z.string(), ManifestInputDeclarationSchema).optional(),
+  mounts: z.record(z.string(), ManifestMountDeclarationSchema).optional(),
+  agent: ManifestAgentBlockSchema,
+  skills: z.array(ManifestSkillRefSchema).optional(),
+  /**
+   * Default MCP tool selection for sessions/runs booted on this manifest.
+   * Resolved at boot via mcp-gateway-api `POST /mcp-resolve` and merged
+   * into `opencode.json:mcp`.
+   */
+  toolSelection: z.array(ManifestToolSelectionEntrySchema).max(128).optional(),
+  credentials: z.array(ManifestCredentialSchema).optional(),
+  permissions: ManifestPermissionsSchema.optional(),
+  persistence: ManifestPersistenceSchema.optional(),
+  outputSurface: ManifestOutputSurfaceSchema.optional(),
+  seedFiles: z.array(ManifestSeedFileSchema).optional(),
+  env: z.array(ManifestEnvVarSchema).optional(),
+  workingFiles: z.array(ManifestWorkingFileSchema).max(32).optional(),
+});
+
+export const WorkspaceManifestMetadataSchema = z.object({
+  slug: z.string().regex(SlugRegex, 'slug must be lowercase kebab-case'),
+  version: z.string().regex(VersionRegex, 'version must follow semver MAJOR.MINOR.PATCH'),
+  org: z.string().optional(),
+  description: z.string().optional(),
+  /**
+   * Optional in the YAML for additive rollout; the compiler defaults
+   * absent values to `[workflow, agent-session]` so existing
+   * manifests keep compiling. New biome/org manifests SHOULD declare
+   * this explicitly — Phase 9 sweeps the shipped manifests.
+   */
+  surfaceCompat: z
+    .array(ManifestSurfaceEnumSchema)
+    .min(1, 'metadata.surfaceCompat must list at least one surface')
+    .optional(),
+  display: ManifestDisplayMetadataSchema.optional(),
+});
+
+/**
+ * `extends:` URI shape — `xema://manifest/<slug>@<version>` (version
+ * required; resolver pins to a specific row at compile time so old
+ * runs stay deterministic). Validation is lenient on slug chars
+ * because biome / org templates may use richer naming than the
+ * kernel-shipped slugs.
+ */
+const ManifestExtendsRegex = /^xema:\/\/manifest\/[a-z0-9][a-z0-9._-]*@\d+\.\d+\.\d+$/;
+
+export const WorkspaceManifestSchema = z
+  .object({
+    apiVersion: z.literal('xema.dev/workspace/v1'),
+    kind: z.literal('WorkspaceManifest'),
+    extends: z
+      .string()
+      .regex(
+        ManifestExtendsRegex,
+        'extends must look like `xema://manifest/<slug>@<MAJOR.MINOR.PATCH>`',
+      )
+      .optional(),
+    metadata: WorkspaceManifestMetadataSchema,
+    spec: WorkspaceManifestSpecSchema,
+  })
+  .meta({
+    id: 'https://xema.dev/schemas/workspace/v1/WorkspaceManifest.json',
+    title: 'Xema WorkspaceManifest',
+    description:
+      'Declarative shape of /workspace/ for an agent invocation: mounts, agent block, seed files, env vars.',
+  });