@cleocode/contracts 2026.5.112 → 2026.5.113

package/dist/operations/input-contract.d.ts

@@ -0,0 +1,267 @@
+/**
+ * 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
+ */
+/**
+ * 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>;
+/**
+ * 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;
+}
+/**
+ * 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>>;
+}
+/**
+ * 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;
+}
+/**
+ * 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 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>>;
+//# sourceMappingURL=input-contract.d.ts.map

package/dist/operations/input-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-contract.d.ts","sourceRoot":"","sources":["../../src/operations/input-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAMjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,KAAK,EAAE,CAAC,CAAC;IAET;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,MAAM,EAAE,UAAU,CAAC;IAEnB;;;;;OAKG;IACH,QAAQ,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;CACnD;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAM/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,8BAA8B,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC"}

package/dist/operations/input-contract.js

@@ -0,0 +1,29 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=input-contract.js.map

package/dist/operations/input-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-contract.js","sourceRoot":"","sources":["../../src/operations/input-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/templates/__tests__/manifest.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=manifest.test.d.ts.map

package/dist/templates/__tests__/manifest.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.test.d.ts","sourceRoot":"","sources":["../../../src/templates/__tests__/manifest.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/templates/__tests__/manifest.test.js

@@ -0,0 +1,123 @@
+/**
+ * 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, TemplateManifestEntrySchema, } from '../manifest.js';
+/**
+ * Build a valid baseline entry parameterized by `kind` so each
+ * assertion below stays minimal.
+ */
+function baseEntry(kind) {
+    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 },
+            {},
+        ];
+        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);
+    });
+});
+//# sourceMappingURL=manifest.test.js.map

package/dist/templates/__tests__/manifest.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.test.js","sourceRoot":"","sources":["../../../src/templates/__tests__/manifest.test.ts"],"names":[],"mappings":"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"}

package/dist/templates/manifest.d.ts

@@ -0,0 +1,186 @@
+/**
+ * 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';
+/**
+ * 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 declare const TEMPLATE_KINDS: readonly ["workflow", "config", "agent", "skill", "provider", "doc"];
+/** Discriminator for the category of file a template represents. */
+export type TemplateKind = (typeof TEMPLATE_KINDS)[number];
+/**
+ * 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 declare const TEMPLATE_SUBSTITUTIONS: readonly ["regex-tmpl", "static", "json-merge"];
+/** Strategy the installer uses to materialize a template's `sourcePath`. */
+export type TemplateSubstitution = (typeof TEMPLATE_SUBSTITUTIONS)[number];
+/**
+ * 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 declare const TEMPLATE_UPDATE_STRATEGIES: readonly ["overwrite-on-bump", "diff-prompt", "immutable", "manifest-merge"];
+/** Reconciliation policy for an installed template on upgrade. */
+export type UpdateStrategy = (typeof TEMPLATE_UPDATE_STRATEGIES)[number];
+/**
+ * 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 declare const PLACEHOLDER_SOURCES: readonly ["project-context", "project-info", ".cleo/config", "~/.cleo/config", "tool-resolver", "literal"];
+/** 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 declare const PlaceholderSpecSchema: z.ZodObject<{
+    name: z.ZodString;
+    source: z.ZodEnum<{
+        literal: "literal";
+        "project-info": "project-info";
+        "project-context": "project-context";
+        ".cleo/config": ".cleo/config";
+        "~/.cleo/config": "~/.cleo/config";
+        "tool-resolver": "tool-resolver";
+    }>;
+    sourcePath: z.ZodString;
+    defaultValue: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strip>;
+/**
+ * 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;
+/**
+ * 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 declare const TemplateManifestEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        agent: "agent";
+        config: "config";
+        provider: "provider";
+        workflow: "workflow";
+        doc: "doc";
+        skill: "skill";
+    }>;
+    sourcePath: z.ZodString;
+    installPath: z.ZodString;
+    substitution: z.ZodEnum<{
+        static: "static";
+        "regex-tmpl": "regex-tmpl";
+        "json-merge": "json-merge";
+    }>;
+    placeholders: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        source: z.ZodEnum<{
+            literal: "literal";
+            "project-info": "project-info";
+            "project-context": "project-context";
+            ".cleo/config": ".cleo/config";
+            "~/.cleo/config": "~/.cleo/config";
+            "tool-resolver": "tool-resolver";
+        }>;
+        sourcePath: z.ZodString;
+        defaultValue: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strip>>;
+    updateStrategy: z.ZodEnum<{
+        "overwrite-on-bump": "overwrite-on-bump";
+        "diff-prompt": "diff-prompt";
+        immutable: "immutable";
+        "manifest-merge": "manifest-merge";
+    }>;
+}, z.core.$strip>;
+/**
+ * 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;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/templates/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/templates/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,sEAAuE,CAAC;AAEnG,oEAAoE;AACpE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAI3D;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,iDAAkD,CAAC;AAEtF,4EAA4E;AAC5E,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAI3E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,8EAK7B,CAAC;AAEX,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAIzE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,4GAOtB,CAAC;AAEX,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;iBAmBhC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEzE,+DAA+D;AAC/D,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAInD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAetC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAErF,iEAAiE;AACjE,MAAM,MAAM,qBAAqB,GAAG,0BAA0B,CAAC"}