@shrkcrft/templates 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/templates
+
+SharkCraft templates: typed template definitions, registry, variable validation, rendering.
+
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/templates
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './template-definition.js';
+export * from './template-variable.js';
+export * from './template-registry.js';
+export * from './template-renderer.js';
+export * from './template-preview.js';
+export * from './template-loader.js';
+export * from './target-path-resolver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./template-definition.js";
+export * from "./template-variable.js";
+export * from "./template-registry.js";
+export * from "./template-renderer.js";
+export * from "./template-preview.js";
+export * from "./template-loader.js";
+export * from "./target-path-resolver.js";

package/dist/target-path-resolver.d.ts

@@ -0,0 +1,9 @@
+import type { ITemplateDefinition } from './template-definition.js';
+import type { TemplateVariableValues } from './template-variable.js';
+export interface IResolvedTargetPath {
+    rawPath: string;
+    absolutePath: string;
+    isInsideProject: boolean;
+}
+export declare function resolveTargetPath(template: ITemplateDefinition, values: TemplateVariableValues, projectRoot: string): IResolvedTargetPath | null;
+//# sourceMappingURL=target-path-resolver.d.ts.map

package/dist/target-path-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-path-resolver.d.ts","sourceRoot":"","sources":["../src/target-path-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGrE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,sBAAsB,EAC9B,WAAW,EAAE,MAAM,GAClB,mBAAmB,GAAG,IAAI,CAW5B"}

package/dist/target-path-resolver.js

@@ -0,0 +1,15 @@
+import { isAbsolutePath, isPathInside, joinPath, normalizePath } from '@shrkcrft/core';
+export function resolveTargetPath(template, values, projectRoot) {
+    if (!template.targetPath)
+        return null;
+    const raw = typeof template.targetPath === 'function' ? template.targetPath(values) : template.targetPath;
+    if (!raw)
+        return null;
+    const normalized = normalizePath(raw);
+    const absolutePath = isAbsolutePath(normalized) ? normalized : joinPath(projectRoot, normalized);
+    return {
+        rawPath: raw,
+        absolutePath,
+        isInsideProject: isPathInside(absolutePath, projectRoot) || absolutePath === projectRoot,
+    };
+}

package/dist/template-definition.d.ts

@@ -0,0 +1,169 @@
+import type { ITemplateVariable, TemplateVariableValues } from './template-variable.js';
+/**
+ * Subset of @shrkcrft/generator's `IPlannedChange` re-declared here to
+ * avoid a generator → templates → generator cycle. The two shapes are kept
+ * structurally equal by `IPlannedChange` consumers.
+ */
+export interface ITemplateChange {
+    targetPath: string;
+    operation: {
+        kind: 'create';
+        content: string;
+        description?: string;
+    } | {
+        kind: 'append';
+        snippet: string;
+        ifMissing?: string;
+        description?: string;
+    } | {
+        kind: 'insert-after';
+        anchor: string;
+        snippet: string;
+        ifMissing?: string;
+        description?: string;
+    } | {
+        kind: 'insert-before';
+        anchor: string;
+        snippet: string;
+        ifMissing?: string;
+        description?: string;
+    } | {
+        kind: 'replace';
+        find: string;
+        replaceWith: string;
+        expectMatches?: number;
+        description?: string;
+    } | {
+        kind: 'export';
+        from: string;
+        symbols?: readonly string[];
+        ifMissing?: string;
+        description?: string;
+    } | {
+        kind: 'ensure-import';
+        from: string;
+        symbols?: readonly string[];
+        typeOnly?: boolean;
+        defaultBinding?: string;
+        namespaceBinding?: string;
+        description?: string;
+    } | {
+        kind: 'insert-enum-entry';
+        enumName: string;
+        entryName: string;
+        entryValue: string;
+        description?: string;
+    } | {
+        kind: 'insert-object-entry';
+        objectName: string;
+        entryKey: string;
+        entryValue: string;
+        shorthand?: boolean;
+        description?: string;
+    } | {
+        kind: 'insert-before-closing-brace';
+        containerName: string;
+        snippet: string;
+        ifMissing?: string;
+        description?: string;
+    } | {
+        kind: 'insert-between-anchors';
+        beginAnchor: string;
+        endAnchor: string;
+        snippet: string;
+        ifMissing?: string;
+        description?: string;
+    };
+}
+/**
+ * Anchor metadata declared by a template.
+ *
+ * Templates can declare:
+ *   - `producedAnchors`: anchor strings that the template body GUARANTEES to
+ *     produce (e.g. `// region:plugin-list`). Template drift verifies these
+ *     anchors appear in the rendered output.
+ *   - `requiredAnchors`: anchor strings that the template REQUIRES in its
+ *     target files (for update ops). Self-config doctor / template drift
+ *     verify that some other template or scaffold provides them; missing
+ *     anchors surface as actionable diagnostics.
+ */
+export interface ITemplateAnchorDeclaration {
+    /** Anchor literal as it must appear in the file. */
+    anchor: string;
+    /** Where the anchor lives (file glob or target path). */
+    in: string;
+    /** Why the template needs / produces this anchor. */
+    purpose?: string;
+    /** Operation kinds that use this anchor (informational). */
+    usedBy?: ReadonlyArray<'insert-after' | 'insert-before' | 'insert-between-anchors' | 'insert-before-closing-brace' | 'insert-enum-entry' | 'insert-object-entry'>;
+}
+export interface ITemplateFile {
+    /** Final file path relative to project root. */
+    targetPath: string;
+    /** File contents. */
+    content: string;
+    /** Optional MIME or hint, e.g. "typescript". */
+    language?: string;
+    /** Default: false (do not overwrite if exists). */
+    overwrite?: boolean;
+}
+export type TargetPathResolver = string | ((values: TemplateVariableValues) => string);
+export type ContentResolver = string | ((values: TemplateVariableValues) => string);
+export type FilesResolver = (values: TemplateVariableValues) => ITemplateFile[];
+export type ChangesResolver = (values: TemplateVariableValues) => ITemplateChange[];
+export interface ITemplateDefinition {
+    id: string;
+    name: string;
+    description: string;
+    tags: readonly string[];
+    scope: readonly string[];
+    appliesWhen: readonly string[];
+    variables: readonly ITemplateVariable[];
+    /** Single-file template: target path. */
+    targetPath?: TargetPathResolver;
+    /** Single-file template: content. */
+    content?: ContentResolver;
+    /**
+     * Multi-file template: file factory.
+     * Each returned entry becomes a CREATE planned change.
+     */
+    files?: FilesResolver;
+    /**
+     * v2 template: mixed CREATE / UPDATE planned changes.
+     * Templates may declare both `files()` and `changes()`; the rendered set is
+     * the concatenation, with `files()` entries normalised to CREATE operations.
+     */
+    changes?: ChangesResolver;
+    /** Post-generation notes shown to the user. */
+    postGenerationNotes?: readonly string[];
+    /** Related knowledge entry IDs. */
+    related?: readonly string[];
+    /**
+     * Optional template profile metadata used by template-drift,
+     * scaffold-coverage, and the `shrk task` recommender. All fields are
+     * informational; the renderer ignores them. Generic engine code never
+     * encodes project-specific values here.
+     */
+    metadata?: {
+        /** Files that must NOT be produced by this template (regex fragments). */
+        forbiddenPathFragments?: readonly string[];
+        /** Plugin lifecycle profile ids this template depends on. */
+        requiredProfileIds?: readonly string[];
+        /** Convention ids this template's outputs are expected to satisfy. */
+        requiredConventionIds?: readonly string[];
+        /** Helper ids that complete the workflow around this template. */
+        requiredHelperIds?: readonly string[];
+        /** Language profiles required for this template to make sense. */
+        requiredLanguages?: readonly string[];
+        /** Framework profiles required for this template to make sense. */
+        requiredFrameworks?: readonly string[];
+        /** Anchors the template body GUARANTEES to produce. */
+        producedAnchors?: readonly ITemplateAnchorDeclaration[];
+        /** Anchors the template REQUIRES to exist in its target files. */
+        requiredAnchors?: readonly ITemplateAnchorDeclaration[];
+        /** Optional ids of registration hints applicable to this template. */
+        registrationHintIds?: readonly string[];
+    };
+}
+export declare function defineTemplate(input: ITemplateDefinition): ITemplateDefinition;
+//# sourceMappingURL=template-definition.d.ts.map

package/dist/template-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-definition.d.ts","sourceRoot":"","sources":["../src/template-definition.ts"],"names":[],"mappings":"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"}

package/dist/template-definition.js

@@ -0,0 +1,20 @@
+export function defineTemplate(input) {
+    if (!input.id)
+        throw new Error("defineTemplate: 'id' is required");
+    if (!input.name)
+        throw new Error(`defineTemplate: 'name' is required for ${input.id}`);
+    if (!input.files && !input.changes && !(input.targetPath && input.content)) {
+        throw new Error(`defineTemplate: ${input.id} must provide either 'files', 'changes', or both 'targetPath' and 'content'`);
+    }
+    return {
+        ...input,
+        tags: Object.freeze([...input.tags]),
+        scope: Object.freeze([...input.scope]),
+        appliesWhen: Object.freeze([...input.appliesWhen]),
+        variables: Object.freeze([...input.variables]),
+        postGenerationNotes: input.postGenerationNotes
+            ? Object.freeze([...input.postGenerationNotes])
+            : undefined,
+        related: input.related ? Object.freeze([...input.related]) : undefined,
+    };
+}

package/dist/template-loader.d.ts

@@ -0,0 +1,12 @@
+import { type IImportContext } from '@shrkcrft/core';
+import type { ITemplateDefinition } from './template-definition.js';
+export interface ILoadedTemplates {
+    templates: ITemplateDefinition[];
+    warnings: string[];
+    sourceFiles: string[];
+}
+export interface ILoadTemplatesOptions {
+    importContext?: IImportContext;
+}
+export declare function loadTemplatesFromFile(filePath: string, options?: ILoadTemplatesOptions): Promise<ILoadedTemplates>;
+//# sourceMappingURL=template-loader.d.ts.map

package/dist/template-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-loader.d.ts","sourceRoot":"","sources":["../src/template-loader.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,cAAc,EAAc,MAAM,gBAAgB,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAQpE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,CAAC,EAAE,cAAc,CAAC;CAChC;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,gBAAgB,CAAC,CAuC3B"}

package/dist/template-loader.js

@@ -0,0 +1,48 @@
+import { existsSync } from 'node:fs';
+import { safeImport } from '@shrkcrft/core';
+function isTemplate(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return typeof v.id === 'string' && typeof v.name === 'string';
+}
+export async function loadTemplatesFromFile(filePath, options = {}) {
+    const warnings = [];
+    const templates = [];
+    const sourceFiles = [];
+    if (!existsSync(filePath)) {
+        warnings.push(`Template file not found: ${filePath}`);
+        return { templates, warnings, sourceFiles };
+    }
+    sourceFiles.push(filePath);
+    const result = options.importContext
+        ? await options.importContext.load(filePath)
+        : await safeImport(filePath, { skipExistsCheck: true });
+    if (!result.ok) {
+        const label = result.timedOut ? 'timed out importing' : 'Failed to import';
+        warnings.push(`${label} ${filePath}: ${result.error.message}`);
+        return { templates, warnings, sourceFiles };
+    }
+    const seen = new Set();
+    const tryPush = (v) => {
+        if (!isTemplate(v))
+            return;
+        if (seen.has(v.id))
+            return;
+        seen.add(v.id);
+        templates.push(v);
+    };
+    for (const key of Object.keys(result.module)) {
+        const v = result.module[key];
+        if (isTemplate(v)) {
+            tryPush(v);
+        }
+        else if (Array.isArray(v)) {
+            for (const item of v)
+                tryPush(item);
+        }
+    }
+    if (templates.length === 0)
+        warnings.push(`No templates exported by ${filePath}`);
+    return { templates, warnings, sourceFiles };
+}

package/dist/template-preview.d.ts

@@ -0,0 +1,10 @@
+import type { IRenderedTemplate } from './template-renderer.js';
+import type { ITemplateDefinition } from './template-definition.js';
+import { type TemplateVariableValues, type IVariableValidationResult } from './template-variable.js';
+export interface ITemplatePreview {
+    template: ITemplateDefinition;
+    validation: IVariableValidationResult;
+    rendered: IRenderedTemplate | null;
+}
+export declare function previewTemplate(template: ITemplateDefinition, values: TemplateVariableValues): ITemplatePreview;
+//# sourceMappingURL=template-preview.d.ts.map

package/dist/template-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-preview.d.ts","sourceRoot":"","sources":["../src/template-preview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC/B,MAAM,wBAAwB,CAAC;AAGhC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,yBAAyB,CAAC;IACtC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACpC;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,sBAAsB,GAC7B,gBAAgB,CAOlB"}

package/dist/template-preview.js

@@ -0,0 +1,10 @@
+import { validateTemplateVariables, } from "./template-variable.js";
+import { renderTemplate } from "./template-renderer.js";
+export function previewTemplate(template, values) {
+    const validation = validateTemplateVariables(template.variables, values);
+    if (!validation.valid) {
+        return { template, validation, rendered: null };
+    }
+    const rendered = renderTemplate(template, validation.resolved);
+    return { template, validation, rendered };
+}

package/dist/template-registry.d.ts

@@ -0,0 +1,11 @@
+import type { ITemplateDefinition } from './template-definition.js';
+export declare class TemplateRegistry {
+    private readonly byId;
+    constructor(templates?: readonly ITemplateDefinition[]);
+    register(template: ITemplateDefinition): void;
+    get(id: string): ITemplateDefinition | null;
+    has(id: string): boolean;
+    list(): ITemplateDefinition[];
+    search(query: string): ITemplateDefinition[];
+}
+//# sourceMappingURL=template-registry.d.ts.map

package/dist/template-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-registry.d.ts","sourceRoot":"","sources":["../src/template-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0C;gBAEnD,SAAS,GAAE,SAAS,mBAAmB,EAAO;IAI1D,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAI7C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAI3C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,IAAI,IAAI,mBAAmB,EAAE;IAI7B,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,EAAE;CAc7C"}

package/dist/template-registry.js

@@ -0,0 +1,32 @@
+export class TemplateRegistry {
+    byId = new Map();
+    constructor(templates = []) {
+        for (const t of templates)
+            this.register(t);
+    }
+    register(template) {
+        this.byId.set(template.id, template);
+    }
+    get(id) {
+        return this.byId.get(id) ?? null;
+    }
+    has(id) {
+        return this.byId.has(id);
+    }
+    list() {
+        return [...this.byId.values()];
+    }
+    search(query) {
+        const q = query.trim().toLowerCase();
+        if (!q)
+            return this.list();
+        return this.list().filter((t) => {
+            return (t.id.toLowerCase().includes(q) ||
+                t.name.toLowerCase().includes(q) ||
+                t.description.toLowerCase().includes(q) ||
+                t.tags.some((tag) => tag.toLowerCase().includes(q)) ||
+                t.scope.some((s) => s.toLowerCase().includes(q)) ||
+                t.appliesWhen.some((a) => a.toLowerCase().includes(q)));
+        });
+    }
+}

package/dist/template-renderer.d.ts

@@ -0,0 +1,19 @@
+import type { ITemplateChange, ITemplateDefinition, ITemplateFile } from './template-definition.js';
+import type { TemplateVariableValues } from './template-variable.js';
+export interface IRenderedTemplate {
+    templateId: string;
+    /**
+     * CREATE-only files (legacy `files()` callback). Kept for v1 callers; the
+     * generator package normalises these to CREATE-kind planned changes.
+     */
+    files: ITemplateFile[];
+    /**
+     * v2 planned changes (mixed CREATE/UPDATE). `files()` results are NOT
+     * duplicated here — consumers handle both lists, treating `files` as the
+     * CREATE-only legacy surface.
+     */
+    changes: ITemplateChange[];
+    postGenerationNotes: readonly string[];
+}
+export declare function renderTemplate(template: ITemplateDefinition, values: TemplateVariableValues): IRenderedTemplate;
+//# sourceMappingURL=template-renderer.d.ts.map

package/dist/template-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-renderer.d.ts","sourceRoot":"","sources":["../src/template-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,aAAa,EACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB;;;;OAIG;IACH,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,sBAAsB,GAC7B,iBAAiB,CAiCnB"}

package/dist/template-renderer.js

@@ -0,0 +1,30 @@
+export function renderTemplate(template, values) {
+    const files = [];
+    const changes = [];
+    if (template.files) {
+        for (const f of template.files(values)) {
+            files.push({
+                targetPath: f.targetPath,
+                content: f.content,
+                language: f.language,
+                overwrite: f.overwrite ?? false,
+            });
+        }
+    }
+    else if (template.targetPath && template.content) {
+        const target = typeof template.targetPath === 'function' ? template.targetPath(values) : template.targetPath;
+        const content = typeof template.content === 'function' ? template.content(values) : template.content;
+        files.push({ targetPath: target, content, overwrite: false });
+    }
+    if (template.changes) {
+        for (const c of template.changes(values)) {
+            changes.push(c);
+        }
+    }
+    return {
+        templateId: template.id,
+        files,
+        changes,
+        postGenerationNotes: template.postGenerationNotes ?? [],
+    };
+}

package/dist/template-variable.d.ts

@@ -0,0 +1,23 @@
+export interface ITemplateVariable {
+    name: string;
+    description?: string;
+    required?: boolean;
+    default?: string;
+    pattern?: RegExp;
+    /** Optional choices, e.g. ['ts', 'tsx']. */
+    choices?: readonly string[];
+    /** Example values to surface in help text and error messages. */
+    examples?: readonly string[];
+}
+export type TemplateVariableValues = Record<string, string>;
+export interface IVariableValidationIssue {
+    variable: string;
+    message: string;
+}
+export interface IVariableValidationResult {
+    valid: boolean;
+    issues: IVariableValidationIssue[];
+    resolved: TemplateVariableValues;
+}
+export declare function validateTemplateVariables(variables: readonly ITemplateVariable[], values: Readonly<TemplateVariableValues>): IVariableValidationResult;
+//# sourceMappingURL=template-variable.d.ts.map

package/dist/template-variable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-variable.d.ts","sourceRoot":"","sources":["../src/template-variable.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACnC,QAAQ,EAAE,sBAAsB,CAAC;CAClC;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,iBAAiB,EAAE,EACvC,MAAM,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GACvC,yBAAyB,CAgC3B"}

package/dist/template-variable.js

@@ -0,0 +1,32 @@
+export function validateTemplateVariables(variables, values) {
+    const issues = [];
+    const resolved = {};
+    for (const v of variables) {
+        let provided = values[v.name];
+        if ((provided === undefined || provided === '') && v.default !== undefined) {
+            provided = v.default;
+        }
+        if (provided === undefined || provided === '') {
+            if (v.required) {
+                issues.push({ variable: v.name, message: `Variable '${v.name}' is required` });
+            }
+            continue;
+        }
+        if (v.pattern && !v.pattern.test(provided)) {
+            issues.push({
+                variable: v.name,
+                message: `Variable '${v.name}' does not match pattern ${v.pattern.source}`,
+            });
+            continue;
+        }
+        if (v.choices && !v.choices.includes(provided)) {
+            issues.push({
+                variable: v.name,
+                message: `Variable '${v.name}' must be one of: ${v.choices.join(', ')}`,
+            });
+            continue;
+        }
+        resolved[v.name] = provided;
+    }
+    return { valid: issues.length === 0, issues, resolved };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@shrkcrft/templates",
+  "version": "0.1.0-alpha.2",
+  "description": "SharkCraft templates: typed template definitions, registry, variable validation, rendering.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shrkcrft/sharkcraft.git",
+    "directory": "packages/templates"
+  },
+  "homepage": "https://github.com/shrkcrft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/shrkcrft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "templates",
+    "generator",
+    "codegen"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}