@cleocode/contracts 2026.5.111 → 2026.5.113

package/src/operations/input-contract.ts

@@ -0,0 +1,301 @@
+/**
+ * OperationInputContract — schema-first input contract for CLEO operations.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the schema-first input
+ * validation surface that powers the `mutate(operation, input)` DX
+ * (Saga T9855 / E7). Every CLEO operation that accepts structured input
+ * MUST be describable as an {@link OperationInputContract}: a JSON Schema
+ * draft-07 document, a stable operation identifier, and at least one
+ * worked example payload.
+ *
+ * Validators consume an {@link OperationInputContract} and produce a
+ * {@link ValidationResult} discriminated union — either the typed value
+ * (`ok: true`) or an array of {@link ValidationError} entries with
+ * actionable, JSON-Pointer-anchored remediation hints (`ok: false`).
+ *
+ * ZERO runtime dependencies: `contracts` is a leaf package. JSON Schema
+ * documents are modeled as the loose alias {@link JsonSchema} so this
+ * module does not pull in a JSON Schema typings package.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/operations/input-contract
+ *
+ * @see {@link https://json-schema.org/draft-07/schema}
+ *
+ * @epic T9855
+ * @task T9914
+ */
+
+// ---------------------------------------------------------------------------
+// JSON Schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Loose alias for a JSON Schema draft-07 document.
+ *
+ * Intentionally typed as `Record<string, unknown>` to keep the contracts
+ * package free of any JSON Schema typings runtime/type dependency. The
+ * actual draft-07 shape is enforced by the validator implementation
+ * (T9915) at the point of use, not by the type system here.
+ *
+ * @example
+ * ```ts
+ * const titleSchema: JsonSchema = {
+ *   type: 'object',
+ *   required: ['title'],
+ *   properties: {
+ *     title: { type: 'string', minLength: 1 },
+ *   },
+ * };
+ * ```
+ */
+export type JsonSchema = Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// Examples
+// ---------------------------------------------------------------------------
+
+/**
+ * A single worked example payload for an {@link OperationInputContract}.
+ *
+ * Examples are MANDATORY (the contract requires at least one) — they
+ * double as documentation for human readers AND as conformance fixtures
+ * for the validator self-test that ships with every CLEO release.
+ *
+ * @typeParam T - The validated, typed input shape produced by the contract.
+ *
+ * @example
+ * ```ts
+ * const example: OperationInputExample<{ title: string }> = {
+ *   name: 'minimal',
+ *   value: { title: 'Ship saga T9855' },
+ *   description: 'Smallest valid input — title is the only required field.',
+ * };
+ * ```
+ */
+export interface OperationInputExample<T> {
+  /**
+   * Short, human-readable identifier for the example. Conventionally
+   * kebab-case (`'minimal'`, `'with-all-fields'`, `'edge-empty-array'`).
+   */
+  name: string;
+
+  /**
+   * A concrete value that validates successfully against the contract's
+   * {@link OperationInputContract.schema | schema}. Strongly typed via
+   * the `T` generic so example tables stay in sync with the operation
+   * payload shape at compile time.
+   */
+  value: T;
+
+  /**
+   * Optional prose explaining why this example matters — what edge case
+   * it covers, what default it exercises, etc. Surfaced in generated docs.
+   */
+  description?: string;
+}
+
+// ---------------------------------------------------------------------------
+// OperationInputContract
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema-first input contract for a single CLEO operation.
+ *
+ * Pairs a stable operation identifier with the JSON Schema draft-07
+ * document that describes the operation's accepted input shape, plus a
+ * non-empty (by convention) catalogue of worked examples. The validator
+ * implementation (T9915) ingests an {@link OperationInputContract} and a
+ * raw payload, returning a {@link ValidationResult}.
+ *
+ * Together with the {@link OperationInputContractRegistry}, this type is
+ * the foundation of the schema-first `mutate(operation, input)` DX
+ * surface (Saga T9855 / E7).
+ *
+ * @typeParam T - The validated, typed input shape produced when the
+ * raw payload passes validation. The generic propagates through
+ * {@link ValidationResult} so callers receive a strongly-typed `value`
+ * in the success branch.
+ *
+ * @example
+ * ```ts
+ * interface CreateTaskInput {
+ *   title: string;
+ *   acceptance: string;
+ * }
+ *
+ * const createTaskContract: OperationInputContract<CreateTaskInput> = {
+ *   operation: 'tasks.create',
+ *   schema: {
+ *     type: 'object',
+ *     required: ['title', 'acceptance'],
+ *     properties: {
+ *       title: { type: 'string', minLength: 1, maxLength: 200 },
+ *       acceptance: { type: 'string', minLength: 1 },
+ *     },
+ *     additionalProperties: false,
+ *   },
+ *   examples: [
+ *     {
+ *       name: 'minimal',
+ *       value: { title: 'Ship E7', acceptance: 'PR merged' },
+ *     },
+ *   ],
+ * };
+ * ```
+ */
+export interface OperationInputContract<T> {
+  /**
+   * Stable, fully-qualified operation identifier in
+   * `<domain>.<verb>` form (e.g. `'tasks.create'`, `'docs.publish'`).
+   * Used as the registry key in {@link OperationInputContractRegistry}.
+   */
+  operation: string;
+
+  /**
+   * JSON Schema draft-07 document describing the accepted input shape.
+   * The validator MUST treat absent properties as not-present (it does
+   * NOT inject `default` values) so callers can distinguish "user
+   * omitted" from "user supplied default".
+   */
+  schema: JsonSchema;
+
+  /**
+   * Catalogue of worked example payloads. Conventionally non-empty so
+   * generated docs always have at least one runnable sample. Each
+   * example's {@link OperationInputExample.value | value} is statically
+   * typed to the contract's `T` parameter.
+   */
+  examples: ReadonlyArray<OperationInputExample<T>>;
+}
+
+// ---------------------------------------------------------------------------
+// ValidationError
+// ---------------------------------------------------------------------------
+
+/**
+ * A single validation failure produced by the input validator.
+ *
+ * Every field is REQUIRED — there are no optional remediation hints.
+ * This shape is the wire format the `mutate` DX surface returns to
+ * callers, so it MUST be stable, machine-parseable, AND human-readable.
+ *
+ * @example
+ * ```ts
+ * const err: ValidationError = {
+ *   path: '/title',
+ *   expected: 'string with minLength 1',
+ *   received: 'empty string',
+ *   fix: 'Provide a non-empty title (1-200 chars).',
+ *   errorCode: 'E_INPUT_MIN_LENGTH',
+ *   schemaPath: '#/properties/title/minLength',
+ * };
+ * ```
+ */
+export interface ValidationError {
+  /**
+   * RFC 6901 JSON Pointer to the failing input location, anchored at
+   * the root of the payload (e.g. `'/title'`, `'/owners/0/email'`).
+   * An empty string `''` denotes the root document itself.
+   */
+  path: string;
+
+  /**
+   * Human-readable description of what the validator expected at
+   * {@link ValidationError.path | path} (e.g. `'string'`,
+   * `'integer >= 0'`, `'one of: pending | active | done'`).
+   */
+  expected: string;
+
+  /**
+   * Human-readable description of what was actually received at
+   * {@link ValidationError.path | path}. NEVER includes the raw value
+   * itself — describes type/cardinality only — so logs of errors do
+   * not accidentally leak user payloads.
+   */
+  received: string;
+
+  /**
+   * Actionable, imperative remediation hint targeted at the caller
+   * (e.g. `'Provide a non-empty title (1-200 chars).'`). Surfaced
+   * directly in CLI output and validator return envelopes.
+   */
+  fix: string;
+
+  /**
+   * Stable, screaming-snake-case error code (e.g.
+   * `'E_INPUT_MIN_LENGTH'`, `'E_INPUT_REQUIRED'`). Stable across
+   * releases so callers can branch on it programmatically.
+   */
+  errorCode: string;
+
+  /**
+   * RFC 6901 JSON Pointer into the contract's
+   * {@link OperationInputContract.schema | schema} that produced the
+   * failure (e.g. `'#/properties/title/minLength'`). Lets tooling jump
+   * straight to the offending schema clause.
+   */
+  schemaPath: string;
+}
+
+// ---------------------------------------------------------------------------
+// ValidationResult
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union returned by the input validator.
+ *
+ * Narrows on the `ok` boolean: when `ok === true`, the strongly-typed
+ * `value` is present; when `ok === false`, a non-empty `errors` array
+ * lists every failure (validators are encouraged to surface ALL errors
+ * in one pass, not bail on the first).
+ *
+ * @typeParam T - The validated, typed input shape produced on success.
+ *
+ * @example
+ * ```ts
+ * function handle(result: ValidationResult<{ title: string }>) {
+ *   if (result.ok) {
+ *     // result.value is { title: string }
+ *     return createTask(result.value);
+ *   }
+ *   // result.errors is ValidationError[]
+ *   for (const e of result.errors) {
+ *     console.error(`${e.path}: ${e.fix}`);
+ *   }
+ * }
+ * ```
+ */
+export type ValidationResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly errors: ValidationError[] };
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Registry of every {@link OperationInputContract} known to the CLEO
+ * runtime, keyed by the contract's `operation` identifier (e.g.
+ * `'tasks.create'`).
+ *
+ * The value type uses `unknown` for the contract's generic so registry
+ * lookups stay assignable across operations with different input
+ * shapes. Callers that need the concrete `T` MUST narrow via an
+ * operation-specific accessor — direct `registry[op]` reads are
+ * intentionally not type-narrowed by operation name.
+ *
+ * @example
+ * ```ts
+ * const registry: OperationInputContractRegistry = {
+ *   'tasks.create': createTaskContract,
+ *   'docs.publish': publishDocsContract,
+ * };
+ *
+ * const contract = registry['tasks.create'];
+ * if (contract) {
+ *   // validate(contract, payload) → ValidationResult<unknown>
+ * }
+ * ```
+ */
+export type OperationInputContractRegistry = Record<string, OperationInputContract<unknown>>;

package/src/templates/__tests__/manifest.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Contract tests for the TemplateManifest schema.
+ *
+ * Asserts:
+ *
+ * 1. A valid entry for every {@link TemplateKind} parses successfully.
+ * 2. An entry with an unknown `kind` is rejected.
+ * 3. An entry missing `installPath` is rejected.
+ * 4. The {@link PlaceholderSpec} `source` field is exhaustively typed —
+ *    every member of {@link PLACEHOLDER_SOURCES} parses, and a bogus
+ *    source value is rejected.
+ *
+ * @task T9875
+ * @epic T9874
+ * @saga T9855
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  PLACEHOLDER_SOURCES,
+  PlaceholderSpecSchema,
+  TEMPLATE_KINDS,
+  type TemplateKind,
+  type TemplateManifestEntry,
+  TemplateManifestEntrySchema,
+} from '../manifest.js';
+
+/**
+ * Build a valid baseline entry parameterized by `kind` so each
+ * assertion below stays minimal.
+ */
+function baseEntry(kind: TemplateKind): TemplateManifestEntry {
+  return {
+    id: `sample-${kind}`,
+    kind,
+    sourcePath: `packages/core/templates/${kind}s/sample.tmpl`,
+    installPath: `.cleo/${kind}s/sample`,
+    substitution: 'regex-tmpl',
+    placeholders: [
+      {
+        name: 'NODE_VERSION',
+        source: 'project-context',
+        sourcePath: 'engines.node',
+        defaultValue: 24,
+      },
+    ],
+    updateStrategy: 'overwrite-on-bump',
+  };
+}
+
+describe('TemplateManifestEntrySchema (T9875)', () => {
+  it('accepts a valid entry for every TemplateKind', () => {
+    for (const kind of TEMPLATE_KINDS) {
+      const entry = baseEntry(kind);
+      const parsed = TemplateManifestEntrySchema.parse(entry);
+      expect(parsed.kind, `kind '${kind}' must round-trip`).toBe(kind);
+      expect(parsed.installPath).toBe(entry.installPath);
+    }
+  });
+
+  it('rejects an entry with an unknown kind', () => {
+    const bogus = {
+      ...baseEntry('workflow'),
+      kind: 'not-a-real-kind',
+    };
+    const result = TemplateManifestEntrySchema.safeParse(bogus);
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an entry missing installPath', () => {
+    const { installPath: _drop, ...rest } = baseEntry('config');
+    const result = TemplateManifestEntrySchema.safeParse(rest);
+    expect(result.success).toBe(false);
+  });
+
+  it('accepts an entry whose placeholders array is empty', () => {
+    const entry = { ...baseEntry('doc'), placeholders: [] };
+    const result = TemplateManifestEntrySchema.safeParse(entry);
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts a defaultValue of every supported literal type and null', () => {
+    const types = [
+      { defaultValue: 'string-default' },
+      { defaultValue: 42 },
+      { defaultValue: true },
+      { defaultValue: null },
+      {},
+    ] as const;
+    for (const extra of types) {
+      const result = PlaceholderSpecSchema.safeParse({
+        name: 'X',
+        source: 'literal',
+        sourcePath: 'X',
+        ...extra,
+      });
+      expect(result.success, `defaultValue case ${JSON.stringify(extra)} must parse`).toBe(true);
+    }
+  });
+});
+
+describe('PlaceholderSpecSchema source enum (T9875)', () => {
+  it('exhaustively accepts every member of PLACEHOLDER_SOURCES', () => {
+    for (const source of PLACEHOLDER_SOURCES) {
+      const result = PlaceholderSpecSchema.safeParse({
+        name: 'PLACEHOLDER',
+        source,
+        sourcePath: 'some.path',
+      });
+      expect(result.success, `source '${source}' must parse`).toBe(true);
+    }
+  });
+
+  it('rejects an unknown source value', () => {
+    const result = PlaceholderSpecSchema.safeParse({
+      name: 'PLACEHOLDER',
+      source: 'not-a-source',
+      sourcePath: 'some.path',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an empty name', () => {
+    const result = PlaceholderSpecSchema.safeParse({
+      name: '',
+      source: 'project-context',
+      sourcePath: 'some.path',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects an empty sourcePath', () => {
+    const result = PlaceholderSpecSchema.safeParse({
+      name: 'X',
+      source: 'project-context',
+      sourcePath: '',
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/templates/manifest.ts

@@ -0,0 +1,208 @@
+/**
+ * TemplateManifest contract — SSoT for every template CLEO ships, installs,
+ * or rewrites during `cleo init` / `cleo upgrade` / `cleo scaffold-*`.
+ *
+ * A {@link TemplateManifestEntry} declares one template file: where its
+ * source lives in the monorepo, where it installs into a consumer project,
+ * how its placeholders are substituted, which placeholders it accepts, and
+ * how it MUST be reconciled when the shipped version moves ahead of the
+ * deployed copy.
+ *
+ * This contract is the leaf type. The CORE-side template registry
+ * (T9877) consumes it; the CLI verbs (`cleo init --workflows`,
+ * `cleo upgrade`, the scaffold sweeper) read the manifest at runtime to
+ * decide what to write, what to skip, and what to diff-prompt the user on.
+ *
+ * @example minimal workflow template entry
+ * ```ts
+ * import { TemplateManifestEntrySchema, type TemplateManifestEntry } from '@cleocode/contracts';
+ *
+ * const entry: TemplateManifestEntry = TemplateManifestEntrySchema.parse({
+ *   id: 'ci.yml',
+ *   kind: 'workflow',
+ *   sourcePath: 'packages/core/templates/workflows/ci.yml.tmpl',
+ *   installPath: '.github/workflows/ci.yml',
+ *   substitution: 'regex-tmpl',
+ *   placeholders: [
+ *     {
+ *       name: 'NODE_VERSION',
+ *       source: 'project-context',
+ *       sourcePath: 'engines.node',
+ *       defaultValue: 24,
+ *     },
+ *   ],
+ *   updateStrategy: 'overwrite-on-bump',
+ * });
+ * ```
+ *
+ * @task T9875
+ * @epic T9874
+ * @saga T9855
+ * @see ADR-076 (canonical doc routing — same boundary discipline applies here)
+ */
+
+import { z } from 'zod';
+
+// ─── TemplateKind ─────────────────────────────────────────────────────────────
+
+/**
+ * Allowed categories of template the manifest can describe.
+ *
+ * - `workflow`  — GitHub Actions / CI workflow files.
+ * - `config`    — Configuration files (e.g. `.editorconfig`, `tsconfig.json`).
+ * - `agent`     — Agent definition files shipped to `.claude/agents/` etc.
+ * - `skill`     — Skill markdown shipped to `.claude/skills/` etc.
+ * - `provider`  — Provider-specific bootstrap files (Anthropic, OpenAI, …).
+ * - `doc`       — Documentation scaffolds (e.g. README.md, AGENTS.md).
+ */
+export const TEMPLATE_KINDS = ['workflow', 'config', 'agent', 'skill', 'provider', 'doc'] as const;
+
+/** Discriminator for the category of file a template represents. */
+export type TemplateKind = (typeof TEMPLATE_KINDS)[number];
+
+// ─── TemplateSubstitution ─────────────────────────────────────────────────────
+
+/**
+ * Allowed substitution strategies a template can request.
+ *
+ * - `regex-tmpl` — `{{KEY}}` placeholder substitution via regex.
+ * - `static`     — No substitution; the file is copied byte-for-byte.
+ * - `json-merge` — The template is parsed as JSON and merged into any
+ *                  existing JSON file at `installPath`; placeholders inside
+ *                  string values still go through `regex-tmpl`.
+ */
+export const TEMPLATE_SUBSTITUTIONS = ['regex-tmpl', 'static', 'json-merge'] as const;
+
+/** Strategy the installer uses to materialize a template's `sourcePath`. */
+export type TemplateSubstitution = (typeof TEMPLATE_SUBSTITUTIONS)[number];
+
+// ─── UpdateStrategy ───────────────────────────────────────────────────────────
+
+/**
+ * How an installed template is reconciled with the shipped copy on
+ * `cleo upgrade` / `cleo init --force`.
+ *
+ * - `overwrite-on-bump` — Always overwrite when the manifest version is
+ *                        newer than the deployed copy.
+ * - `diff-prompt`       — Show a diff and ask the user before overwriting.
+ * - `immutable`         — Never overwrite once installed.
+ * - `manifest-merge`    — Apply structural merge (e.g. JSON deep-merge,
+ *                        respecting existing user keys).
+ */
+export const TEMPLATE_UPDATE_STRATEGIES = [
+  'overwrite-on-bump',
+  'diff-prompt',
+  'immutable',
+  'manifest-merge',
+] as const;
+
+/** Reconciliation policy for an installed template on upgrade. */
+export type UpdateStrategy = (typeof TEMPLATE_UPDATE_STRATEGIES)[number];
+
+// ─── PlaceholderSpec ──────────────────────────────────────────────────────────
+
+/**
+ * Allowed resolver sources a {@link PlaceholderSpec} can reference.
+ *
+ * - `project-context` — `.cleo/project-context.json` (detected ecosystem hints).
+ * - `project-info`    — `.cleo/project-info.json` (per-project metadata).
+ * - `.cleo/config`    — Per-project config (`<projectRoot>/.cleo/config.json`).
+ * - `~/.cleo/config`  — User-global config (`$XDG_CONFIG_HOME/cleo/config.json`).
+ * - `tool-resolver`   — Resolved via the per-language tool resolver
+ *                       (e.g. `pnpm` vs `npm` chosen by `primaryType`).
+ * - `literal`         — Hard-coded value baked into the manifest entry.
+ */
+export const PLACEHOLDER_SOURCES = [
+  'project-context',
+  'project-info',
+  '.cleo/config',
+  '~/.cleo/config',
+  'tool-resolver',
+  'literal',
+] as const;
+
+/** Resolver source enum for {@link PlaceholderSpec.source}. */
+export type PlaceholderSource = (typeof PLACEHOLDER_SOURCES)[number];
+
+/**
+ * Zod schema for a single placeholder declaration on a template entry.
+ *
+ * Each placeholder is resolved at install time by reading `sourcePath` from
+ * the named `source`. If resolution returns `undefined`, the installer
+ * falls back to `defaultValue`; if neither yields a value, installation
+ * fails with `E_PLACEHOLDER_UNRESOLVED`.
+ */
+export const PlaceholderSpecSchema = z.object({
+  /**
+   * Placeholder identifier as it appears in the template body
+   * (e.g. `NODE_VERSION` matches `{{NODE_VERSION}}`).
+   */
+  name: z.string().min(1, 'placeholder name must be non-empty'),
+  /** Resolver source the installer consults for this placeholder. */
+  source: z.enum(PLACEHOLDER_SOURCES),
+  /**
+   * Path expression evaluated against `source` (e.g. `engines.node` against
+   * `project-context`, `defaults.branchModel` against `.cleo/config`).
+   * For `literal` source, this MAY be the literal value's identifier.
+   */
+  sourcePath: z.string().min(1, 'placeholder sourcePath must be non-empty'),
+  /**
+   * Fallback value used when `source[sourcePath]` resolves to `undefined`.
+   * `null` is permitted to explicitly mark "no default — failure required".
+   */
+  defaultValue: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
+});
+
+/**
+ * Zod-inferred input shape for a placeholder declaration.
+ *
+ * Identical to {@link PlaceholderSpec} — there are no schema transforms.
+ */
+export type PlaceholderSpecInput = z.infer<typeof PlaceholderSpecSchema>;
+
+/** Declared placeholder on a {@link TemplateManifestEntry}. */
+export type PlaceholderSpec = PlaceholderSpecInput;
+
+// ─── TemplateManifestEntry ────────────────────────────────────────────────────
+
+/**
+ * Zod schema for a single template manifest entry.
+ *
+ * Validates the full descriptor a template registry consumer needs to
+ * install a template file:
+ *
+ * - `id`             — Stable identifier (kebab-case, matches install basename
+ *                      or a domain-unique slug).
+ * - `kind`           — One of {@link TEMPLATE_KINDS}.
+ * - `sourcePath`     — Repo-relative path of the template source.
+ * - `installPath`    — Project-relative path where the rendered file lands.
+ * - `substitution`   — One of {@link TEMPLATE_SUBSTITUTIONS}.
+ * - `placeholders`   — Declared placeholders the installer must resolve.
+ * - `updateStrategy` — Reconciliation policy on upgrade.
+ */
+export const TemplateManifestEntrySchema = z.object({
+  /** Stable identifier for this template entry. */
+  id: z.string().min(1, 'id must be non-empty'),
+  /** Category of file this template represents. */
+  kind: z.enum(TEMPLATE_KINDS),
+  /** Repo-relative path of the template source file. */
+  sourcePath: z.string().min(1, 'sourcePath must be non-empty'),
+  /** Project-relative path where the rendered template installs. */
+  installPath: z.string().min(1, 'installPath must be non-empty'),
+  /** Substitution strategy the installer applies to `sourcePath`. */
+  substitution: z.enum(TEMPLATE_SUBSTITUTIONS),
+  /** Declared placeholders this template requires. May be empty. */
+  placeholders: z.array(PlaceholderSpecSchema),
+  /** Reconciliation policy on upgrade. */
+  updateStrategy: z.enum(TEMPLATE_UPDATE_STRATEGIES),
+});
+
+/**
+ * Zod-inferred input shape for a template manifest entry.
+ *
+ * Identical to {@link TemplateManifestEntry} — there are no schema transforms.
+ */
+export type TemplateManifestEntryInput = z.infer<typeof TemplateManifestEntrySchema>;
+
+/** Public type for a fully-validated template manifest entry. */
+export type TemplateManifestEntry = TemplateManifestEntryInput;