@powerhousedao/codegen 6.0.0-dev.3 → 6.0.0-dev.30

package/dist/src/file-builders/boilerplate/ci-templates.test.js

@@ -0,0 +1,114 @@
+import { describe, expect, test } from "vitest";
+import { connectEntrypointTemplate } from "../../templates/boilerplate/docker/connect-entrypoint.sh.js";
+import { dockerfileTemplate } from "../../templates/boilerplate/docker/Dockerfile.js";
+import { nginxConfTemplate } from "../../templates/boilerplate/docker/nginx.conf.js";
+import { switchboardEntrypointTemplate } from "../../templates/boilerplate/docker/switchboard-entrypoint.sh.js";
+import { syncAndPublishWorkflowTemplate } from "../../templates/boilerplate/github/sync-and-publish.yml.js";
+describe("CI/CD Templates", () => {
+    describe("sync-and-publish.yml", () => {
+        test("should be a non-empty string", () => {
+            expect(typeof syncAndPublishWorkflowTemplate).toBe("string");
+            expect(syncAndPublishWorkflowTemplate.length).toBeGreaterThan(0);
+        });
+        test("should have correct workflow name", () => {
+            expect(syncAndPublishWorkflowTemplate).toContain("name: Sync and Publish");
+        });
+        test("should contain required jobs", () => {
+            expect(syncAndPublishWorkflowTemplate).toContain("prepare:");
+            expect(syncAndPublishWorkflowTemplate).toContain("update-and-publish:");
+            expect(syncAndPublishWorkflowTemplate).toContain("build-docker:");
+            expect(syncAndPublishWorkflowTemplate).toContain("summary:");
+        });
+        test("should have workflow_dispatch trigger with channel options", () => {
+            expect(syncAndPublishWorkflowTemplate).toContain("workflow_dispatch:");
+            expect(syncAndPublishWorkflowTemplate).toContain("- dev");
+            expect(syncAndPublishWorkflowTemplate).toContain("- staging");
+            expect(syncAndPublishWorkflowTemplate).toContain("- latest");
+        });
+        test("should have repository_dispatch trigger", () => {
+            expect(syncAndPublishWorkflowTemplate).toContain("repository_dispatch:");
+            expect(syncAndPublishWorkflowTemplate).toContain("powerhouse-release");
+        });
+        test("should configure Docker and GHCR registries", () => {
+            expect(syncAndPublishWorkflowTemplate).toContain("DOCKER_REGISTRY:");
+            expect(syncAndPublishWorkflowTemplate).toContain("GHCR_REGISTRY:");
+            expect(syncAndPublishWorkflowTemplate).toContain("cr.vetra.io");
+            expect(syncAndPublishWorkflowTemplate).toContain("ghcr.io");
+        });
+    });
+    describe("Dockerfile", () => {
+        test("should be a non-empty string", () => {
+            expect(typeof dockerfileTemplate).toBe("string");
+            expect(dockerfileTemplate.length).toBeGreaterThan(0);
+        });
+        test("should contain base stage", () => {
+            expect(dockerfileTemplate).toContain("FROM node:24-alpine AS base");
+        });
+        test("should contain connect-builder stage", () => {
+            expect(dockerfileTemplate).toContain("FROM base AS connect-builder");
+        });
+        test("should contain connect final stage", () => {
+            expect(dockerfileTemplate).toContain("FROM nginx:alpine AS connect");
+        });
+        test("should contain switchboard final stage", () => {
+            expect(dockerfileTemplate).toContain("FROM node:24-alpine AS switchboard");
+        });
+        test("should configure pnpm", () => {
+            expect(dockerfileTemplate).toContain("corepack enable");
+            expect(dockerfileTemplate).toContain("PNPM_HOME");
+        });
+        test("should install ph-cmd", () => {
+            expect(dockerfileTemplate).toContain("ph-cmd@$TAG");
+        });
+        test("should have health checks", () => {
+            expect(dockerfileTemplate).toContain("HEALTHCHECK");
+        });
+    });
+    describe("nginx.conf", () => {
+        test("should be a non-empty string", () => {
+            expect(typeof nginxConfTemplate).toBe("string");
+            expect(nginxConfTemplate.length).toBeGreaterThan(0);
+        });
+        test("should contain health check endpoint", () => {
+            expect(nginxConfTemplate).toContain("location /health");
+        });
+        test("should configure gzip compression", () => {
+            expect(nginxConfTemplate).toContain("gzip on");
+        });
+        test("should use PORT environment variable", () => {
+            expect(nginxConfTemplate).toContain("${PORT}");
+        });
+        test("should configure caching for assets", () => {
+            expect(nginxConfTemplate).toContain("Cache-Control");
+            expect(nginxConfTemplate).toContain("/assets/");
+        });
+    });
+    describe("connect-entrypoint.sh", () => {
+        test("should be a non-empty string", () => {
+            expect(typeof connectEntrypointTemplate).toBe("string");
+            expect(connectEntrypointTemplate.length).toBeGreaterThan(0);
+        });
+        test("should start with shebang", () => {
+            expect(connectEntrypointTemplate).toMatch(/^#!/);
+        });
+        test("should use envsubst for nginx config", () => {
+            expect(connectEntrypointTemplate).toContain("envsubst");
+        });
+        test("should start nginx", () => {
+            expect(connectEntrypointTemplate).toContain("nginx");
+        });
+    });
+    describe("switchboard-entrypoint.sh", () => {
+        test("should be a non-empty string", () => {
+            expect(typeof switchboardEntrypointTemplate).toBe("string");
+            expect(switchboardEntrypointTemplate.length).toBeGreaterThan(0);
+        });
+        test("should start with shebang", () => {
+            expect(switchboardEntrypointTemplate).toMatch(/^#!/);
+        });
+        test("should start switchboard", () => {
+            expect(switchboardEntrypointTemplate).toContain("ph switchboard");
+        });
+    });
+});
+//# sourceMappingURL=ci-templates.test.js.map

package/dist/src/file-builders/boilerplate/ci-templates.test.js.map

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

package/dist/src/file-builders/boilerplate/package.json.js

@@ -1,5 +1,5 @@
 import { packageJsonTemplate } from "@powerhousedao/codegen/templates";
-import { makeVersionedDependencies, VERSIONED_DEPENDENCIES, VERSIONED_DEV_DEPENDENCIES, } from "@powerhousedao/codegen/utils";
+import { makeVersionedDependencies, VERSIONED_DEPENDENCIES, VERSIONED_DEV_DEPENDENCIES, } from "@powerhousedao/common/clis";
 export async function buildBoilerplatePackageJson(args) {
     const { name, tag, version } = args;
     const versionedDependencies = await makeVersionedDependencies({

package/dist/src/file-builders/boilerplate/package.json.js.map

@@ -1 +1 @@
-{"version":3,"file":"package.json.js","sourceRoot":"","sources":["../../../../src/file-builders/boilerplate/package.json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,8BAA8B,CAAC;AAEtC,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,IAIjD;IACC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACpC,MAAM,qBAAqB,GAAG,MAAM,yBAAyB,CAAC;QAC5D,KAAK,EAAE,sBAAsB;QAC7B,GAAG;QACH,OAAO;KACR,CAAC,CAAC;IACH,MAAM,wBAAwB,GAAG,MAAM,yBAAyB,CAAC;QAC/D,KAAK,EAAE,0BAA0B;QACjC,GAAG;QACH,OAAO;KACR,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,mBAAmB,CAClC,IAAI,EACJ,qBAAqB,EACrB,wBAAwB,CACzB,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"package.json.js","sourceRoot":"","sources":["../../../../src/file-builders/boilerplate/package.json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AAEpC,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,IAIjD;IACC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACpC,MAAM,qBAAqB,GAAG,MAAM,yBAAyB,CAAC;QAC5D,KAAK,EAAE,sBAAsB;QAC7B,GAAG;QACH,OAAO;KACR,CAAC,CAAC;IACH,MAAM,wBAAwB,GAAG,MAAM,yBAAyB,CAAC;QAC/D,KAAK,EAAE,0BAA0B;QACjC,GAAG;QACH,OAAO;KACR,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,mBAAmB,CAClC,IAAI,EACJ,qBAAqB,EACrB,wBAAwB,CACzB,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/src/file-builders/clis/generate-cli-docs.d.ts

@@ -0,0 +1,17 @@
+import type { CommandEntry, CommandHelpInfo } from "@powerhousedao/codegen";
+export declare function getCommandHelpInfo<TEntry extends CommandEntry>(entry: TEntry): CommandHelpInfo;
+export declare function getCommandsHelpInfo<TEntry extends CommandEntry>(entries: TEntry[]): CommandHelpInfo[];
+export declare function makeCliDocsFromHelp<TEntry extends CommandEntry>(args: {
+    cliDescription: string;
+    docsTitle: string;
+    docsIntroduction: string;
+    entries: TEntry[];
+}): string;
+export declare function writeCliDocsMarkdownFile<TEntry extends CommandEntry>(args: {
+    filePath: string;
+    cliDescription: string;
+    docsTitle: string;
+    docsIntroduction: string;
+    entries: TEntry[];
+}): Promise<void>;
+//# sourceMappingURL=generate-cli-docs.d.ts.map

package/dist/src/file-builders/clis/generate-cli-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-cli-docs.d.ts","sourceRoot":"","sources":["../../../../src/file-builders/clis/generate-cli-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAI5E,wBAAgB,kBAAkB,CAAC,MAAM,SAAS,YAAY,EAC5D,KAAK,EAAE,MAAM,GACZ,eAAe,CASjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,SAAS,YAAY,EAC7D,OAAO,EAAE,MAAM,EAAE,qBAGlB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,SAAS,YAAY,EAAE,IAAI,EAAE;IACrE,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,UAcA;AAED,wBAAsB,wBAAwB,CAC5C,MAAM,SAAS,YAAY,EAC3B,IAAI,EAAE;IACN,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,iBAOA"}

package/dist/src/file-builders/clis/generate-cli-docs.js

@@ -0,0 +1,36 @@
+import { docsFromCliHelpTemplate } from "@powerhousedao/codegen/templates";
+import { writeFile } from "node:fs/promises";
+import { stripVTControlCharacters } from "node:util";
+export function getCommandHelpInfo(entry) {
+    const name = entry.name;
+    const description = entry.command.description ?? "";
+    const helpTopics = entry.command.helpTopics?.() ?? [];
+    return {
+        name,
+        description,
+        helpTopics,
+    };
+}
+export function getCommandsHelpInfo(entries) {
+    return entries.map(getCommandHelpInfo);
+}
+export function makeCliDocsFromHelp(args) {
+    const { cliDescription, docsIntroduction, docsTitle, entries } = args;
+    const commandsHelpInfo = getCommandsHelpInfo(entries);
+    const template = docsFromCliHelpTemplate({
+        cliDescription,
+        docsIntroduction,
+        docsTitle,
+        commandsHelpInfo,
+    });
+    const templateWithAnsiEscapesRemoved = stripVTControlCharacters(template);
+    return templateWithAnsiEscapesRemoved;
+}
+export async function writeCliDocsMarkdownFile(args) {
+    const { filePath, ...restArgs } = args;
+    const markdownFileContent = makeCliDocsFromHelp(restArgs);
+    await writeFile(filePath, markdownFileContent, {
+        encoding: "utf-8",
+    });
+}
+//# sourceMappingURL=generate-cli-docs.js.map

package/dist/src/file-builders/clis/generate-cli-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-cli-docs.js","sourceRoot":"","sources":["../../../../src/file-builders/clis/generate-cli-docs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AACrD,MAAM,UAAU,kBAAkB,CAChC,KAAa;IAEb,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;IACpD,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC;IACtD,OAAO;QACL,IAAI;QACJ,WAAW;QACX,UAAU;KACX,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,OAAiB;IAEjB,OAAO,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAA8B,IAKhE;IACC,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACtE,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAEtD,MAAM,QAAQ,GAAG,uBAAuB,CAAC;QACvC,cAAc;QACd,gBAAgB;QAChB,SAAS;QACT,gBAAgB;KACjB,CAAC,CAAC;IAEH,MAAM,8BAA8B,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAE1E,OAAO,8BAA8B,CAAC;AACxC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAE5C,IAMD;IACC,MAAM,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC;IACvC,MAAM,mBAAmB,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAE1D,MAAM,SAAS,CAAC,QAAQ,EAAE,mBAAmB,EAAE;QAC7C,QAAQ,EAAE,OAAO;KAClB,CAAC,CAAC;AACL,CAAC"}

package/dist/src/file-builders/index.d.ts

@@ -7,4 +7,5 @@ export * from "./index-files.js";
 export * from "./module-files.js";
 export * from "./subgraphs.js";
 export type * from "./types.js";
+export * from "./clis/generate-cli-docs.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/file-builders/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/file-builders/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,mBAAmB,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/file-builders/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,mBAAmB,YAAY,CAAC;AAChC,cAAc,6BAA6B,CAAC"}

package/dist/src/file-builders/index.js

@@ -6,4 +6,5 @@ export * from "./editor-common.js";
 export * from "./index-files.js";
 export * from "./module-files.js";
 export * from "./subgraphs.js";
+export * from "./clis/generate-cli-docs.js";
 //# sourceMappingURL=index.js.map

package/dist/src/file-builders/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/file-builders/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/file-builders/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAE/B,cAAc,6BAA6B,CAAC"}

package/dist/src/file-builders/types.d.ts

@@ -63,4 +63,22 @@ export type DocumentModelFileMakerArgs = DocumentModelVariableNames & GenerateDo
     reducersDirPath: string;
     fileExtension: string;
 };
+export type CommandEntry = {
+    name: string;
+    command: {
+        description?: string;
+        helpTopics?: () => HelpTopic[];
+    };
+};
+export type HelpTopic = {
+    category: string;
+    usage: string;
+    description: string;
+    defaults: string[];
+};
+export type CommandHelpInfo = {
+    name: string;
+    description: string;
+    helpTopics: HelpTopic[];
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/src/file-builders/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/file-builders/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,6CAA6C,EAC7C,6BAA6B,EAC7B,sBAAsB,EACvB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACnB,2BAA2B,EAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,6BAA6B,EAAE,MAAM,CAAC;IACtC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,uBAAuB,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E,MAAM,MAAM,0BAA0B,GAAG,UAAU,CACjD,OAAO,6BAA6B,CACrC,CAAC;AAEF,MAAM,MAAM,0CAA0C,GAAG,UAAU,CACjE,OAAO,6CAA6C,CACrD,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG,0BAA0B,GAClE,0BAA0B,CAAC;AAE7B,MAAM,MAAM,qCAAqC,GAAG;IAClD,MAAM,EAAE,mBAAmB,CAAC;CAC7B,GAAG,2BAA2B,GAC7B,0CAA0C,CAAC;AAE7C,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,2BAA2B,EAAE,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,wBAAwB,CAAC;IAC7C,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,0BAA0B,GACjE,yBAAyB,GAAG;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,OAAO,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2BAA2B,EAAE,MAAM,CAAC;IACpC,2BAA2B,EAAE,MAAM,CAAC;IACpC,8BAA8B,EAAE,MAAM,CAAC;IACvC,uCAAuC,EAAE,MAAM,CAAC;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/file-builders/types.ts"],"names":[],"mappings":"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"}

package/dist/src/templates/boilerplate/AGENTS.md.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AGENTS.md.d.ts","sourceRoot":"","sources":["../../../../src/templates/boilerplate/AGENTS.md.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,QAqZtB,CAAC"}
+{"version":3,"file":"AGENTS.md.d.ts","sourceRoot":"","sources":["../../../../src/templates/boilerplate/AGENTS.md.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,QA8btB,CAAC"}

package/dist/src/templates/boilerplate/AGENTS.md.js

@@ -264,6 +264,47 @@ throw new MissingIdError("message");
 - **InvalidInputError**: Business logic violations
 - **PermissionDeniedError**: Access control violations
 
+#### Testing Reducer Errors
+
+**CRITICAL**: When a reducer throws an error, the operation is **still added** to the document but with an \`.error\` property containing the error message as a string.
+
+**DO NOT** use \`.toThrow()\` or \`expect(() => ...).toThrow()\` patterns when testing reducer errors.
+
+##### How Errors Work in Operations
+
+1. The reducer throws an error (e.g., \`throw new InvalidNameError("message")\`)
+2. The operation is still recorded in \`document.operations.global\` (or \`.local\`)
+3. The error message is stored in \`operation.error\` as a string
+4. **The state is NOT mutated** - it remains unchanged from before the operation
+
+##### Accessing the Correct Operation Index
+
+**CRITICAL**: You must access the correct operation index. The index corresponds to how many operations were dispatched before it.
+
+- If this is the **first** operation dispatched, access \`[0]\`
+- If 3 operations were dispatched **before** the failing one, access \`[3]\`
+
+##### Example
+
+~~~typescript
+it("should return error and not mutate state", () => {
+  const document = utils.createDocument();
+  const initialState = document.state.global.name;
+
+  const updatedDocument = reducer(document, setName({ name: "invalid" }));
+
+  // Access the correct operation index (0 = first operation)
+  expect(updatedDocument.operations.global[0].error).toBe(
+    "Name is not allowed",
+  );
+  // State remains unchanged
+  expect(updatedDocument.state.global.name).toBe(initialState);
+});
+
+// ❌ WRONG - Never use toThrow()
+expect(() => reducer(document, setName({ name: "invalid" }))).toThrow();
+~~~
+
 ## Document Model Structure
 
 ### Core Components

package/dist/src/templates/boilerplate/AGENTS.md.js.map

@@ -1 +1 @@
-{"version":3,"file":"AGENTS.md.js","sourceRoot":"","sources":["../../../../src/templates/boilerplate/AGENTS.md.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AAEhC,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqZ/B,CAAC,GAAG,CAAC"}
+{"version":3,"file":"AGENTS.md.js","sourceRoot":"","sources":["../../../../src/templates/boilerplate/AGENTS.md.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AAEhC,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8b/B,CAAC,GAAG,CAAC"}

package/dist/src/templates/boilerplate/CLAUDE.md.d.ts

@@ -1,2 +1,2 @@
-export declare const claudeTemplate: string;
+export { agentsTemplate as claudeTemplate } from "./AGENTS.md.js";
 //# sourceMappingURL=CLAUDE.md.d.ts.map

package/dist/src/templates/boilerplate/CLAUDE.md.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CLAUDE.md.d.ts","sourceRoot":"","sources":["../../../../src/templates/boilerplate/CLAUDE.md.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,QAqZtB,CAAC"}
+{"version":3,"file":"CLAUDE.md.d.ts","sourceRoot":"","sources":["../../../../src/templates/boilerplate/CLAUDE.md.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC"}