@powerhousedao/codegen 6.0.0-dev.11 → 6.0.0-dev.111

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

@@ -12,6 +12,14 @@ This project creates document models, editors, processors and subgraphs for the
 - **Action**: A proposed change to a document (JSON object with action name and input). Dispatch using "addActions" tool.
 - **Operation**: A completed change to a document containing the action plus metadata (index, timestamp, hash, errors). Actions become operations after dispatch.
 
+## Technology Primer
+
+- **Reactor**: The core Powerhouse engine. It is modular and storage-agnostic, loads document models at runtime, and synchronizes documents across nodes via drives.
+- **Reactor Package**: A deployable bundle that extends the Reactor. It contains one or more document models, editors, processors, and subgraphs. A Vetra project generates a Reactor Package.
+- **Connect**: The Powerhouse web application for document management. End users open Connect to browse drives, create documents, and interact with editors.
+- **Switchboard**: The Powerhouse API service. It exposes GraphQL and MCP endpoints so external tools can read/write documents programmatically.
+- **Vetra**: The local development environment for building Reactor Packages. It includes Vetra Studio (a local Connect instance) and Vetra Switchboard (a local Switchboard with reactor-mcp). Start it with \`ph vetra\`.
+
 ## CRITICAL: MCP Tool Usage Rules
 
 **MANDATORY**: The \`reactor-mcp\` MUST BE USED when handling documents or document-models for the Powerhouse/Vetra ecosystem.
@@ -36,6 +44,12 @@ If the \`reactor-mcp\` server is unavailable, ask the user to run \`ph vetra\` o
 - When in doubt, ask for clarification
 - Break complex models into logical modules and operations
 
+#### Document Type ID Format
+
+- **Type ID**: \`{organization}/{document-type-name}\` (e.g., \`pizza-plaza/order\`, \`acme/invoice\`)
+- **File extension**: 2-4 characters with leading dot (e.g., \`.ordr\`, \`.inv\`)
+- **Name**: Must match \`/[a-zA-Z][a-zA-Z0-9 ]*/\` — human-readable, capitalized (e.g., \`"Order"\`, \`"Invoice"\`)
+
 ### 2. Pre-Implementation Requirements
 
 **MANDATORY**: Check document model schema before making any MCP tool calls.
@@ -64,20 +78,43 @@ After doing changes to the code, or after creating a new document model or a new
 
 ## Document editor creation flow
 
-When the user requests to create or make changes on a document editor, follow these steps:
+**CRITICAL**: Creating a document editor is a **two-phase** process. You must NEVER skip Phase 1 or try to manually create editor files from scratch. The codegen system generates the boilerplate — your job is only to implement the UI inside it.
+
+### Phase 1: Create the editor document via MCP (MANDATORY FIRST STEP)
+
+**NEVER** start by writing editor code, creating component files, or looking at how to scaffold an editor manually. The **only** way to create a new editor is through the MCP tools:
+
+1. Check if the document editor already exists. If it does, ask the user if a new one should be created or if the existing one should be reimplemented
+2. If it's a new editor, get the document editor schema using \`mcp__reactor-mcp__getDocumentModelSchema\` with \`type: "powerhouse/document-editor"\`
+3. Create a new editor document on the \`vetra-{hash}\` drive of type \`powerhouse/document-editor\` using \`mcp__reactor-mcp__addActions\` with the \`ADD_FILE\` action
+4. Configure the editor document with the required actions (set the editor name, target document model, etc.) according to the schema
+
+⚠️ **The editor document MUST be confirmed/published — if it is left as draft state, the codegen will NOT run and no editor files will be generated.** Make sure the document state is not "DRAFT" after creation.
+
+5. Once the editor document is confirmed on the drive, the codegen automatically runs and generates boilerplate files in the \`editors/\` folder, including hooks, type definitions, and the editor component shell
+
+### Phase 2: Implement the editor UI
+
+Only **after** the codegen has produced the boilerplate files, proceed with the UI implementation:
 
-- Check if the document editor already exists and if it does, ask the user if a new one should be created or if the existing one should be reimplemented
-- If it's a new editor, create a new editor document on the "vetra-{hash}" drive if available, of type \`powerhouse/document-editor\`
-- Check the document editor schema and comply with it
-- After adding the editor document to the \`vetra-{hash}\` drive, a new editor will be generated in the \`editors\` folder
+- Inspect the generated files in the \`editors/\` folder — do NOT create new files for the main editor component; edit the generated one
 - Inspect the hooks in \`editors/hooks\` as they should be useful
 - Read the schema of the document model that the editor is for to know how to interact with it
+- Every editor **MUST** include \`<DocumentToolbar />\` imported from \`@powerhousedao/design-system/connect/index\`. Place it at the top of the editor component — do not put anything next to it.
 - Style the editor using tailwind classes or a style tag. If using a style tag, make sure to make the selectors specific to only apply to the editor component.
 - Create modular components for the UI elements and place them on separate files to make it easier to maintain and update
 - Consider using the React Components exported by \`@powerhousedao/design-system\` and \`@powerhousedao/document-engineering\`
 - Separate business logic from presentation logic
 - Use TypeScript for type safety, avoid using any and type casting
 - Always check for type and lint errors after creating or modifying the editor
+- **CRITICAL**: After creating a new editor, verify that \`editors/editors.ts\` includes the new editor module. The codegen should update this file automatically, but if it doesn't, manually add the import and include the editor in the \`editors\` array. Without this registration, Connect won't find an editor for the document type. Example:
+
+  ~~~typescript
+  import type { EditorModule } from "document-model";
+  import { TodoListEditor } from "./todo-list-editor/module.js";
+
+  export const editors: EditorModule[] = [TodoListEditor];
+  ~~~
 
 ### Document Editor Implementation Pattern
 
@@ -90,7 +127,7 @@ The following section is valid for editors that edit a single document type.
 Using a "Todo" document model as example:
 
 ~~~typescript
-import { generateId } from "document-model/core";
+import { generateId } from "@powerhousedao/shared/document-model";
 import { useSelectedTodoDocument } from "../hooks/useTodoDocument.js";
 import {
   addTodo,
@@ -104,6 +141,9 @@ export default function Editor() {
       dispatch(addTodo({ id: generateId(), title: values.title }));
     }
   };
+
+// Note: The \`useSelectedTodoDocument\` hook is auto-generated. Check the \`editors/hooks\` folder for the exact hook name.
+// Action creators like \`addTodo\` are exported from the document model's \`gen/creators.js\` file.
 ~~~
 
 The \`useSelectedTodoDocument\` gets generated automatically so you don't need to implement it yourself.
@@ -222,9 +262,9 @@ Errors referenced in the reducer code will be imported automatically.
 #### Error Definition Requirements
 
 1. **Add error definitions** to operations using \`ADD_OPERATION_ERROR\`:
-   - \`code\`: Uppercase snake_case (e.g., \`"MISSING_ID"\`, \`"ENTRY_NOT_FOUND"\`)
-   - \`name\`: PascalCase ending with "Error" (e.g., \`"MissingIdError"\`, \`"EntryNotFoundError"\`)
-   - \`description\`: Human-readable description of the error condition
+   - \`errorCode\`: Uppercase snake_case (e.g., \`"MISSING_ID"\`, \`"ENTRY_NOT_FOUND"\`)
+   - \`errorName\`: PascalCase ending with "Error" (e.g., \`"MissingIdError"\`, \`"EntryNotFoundError"\`)
+   - \`errorDescription\`: Human-readable description of the error condition
 
 2. **Error names must end with "Error"** for consistency and code generation
 
@@ -264,6 +304,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
@@ -306,6 +387,15 @@ throw new MissingIdError("message");
 - Use required fields \`!\` only when absolutely necessary
 - Defaults handled by operations, not schema
 
+#### Mandatory vs Optional Field Rules
+
+A user must always be able to create an **empty document** without providing any information. This drives the following rules:
+
+- **Root type properties** can only be mandatory (\`!\`) if they have a logical default value (e.g., empty array, enum initial status)
+- **Collections** should always use \`[Type!]!\` — inner \`!\` means no nulls in the array, outer \`!\` means the array itself defaults to empty
+- **Child object fields** can be mandatory only if all their required properties also have logical defaults
+- Use \`enum\` types for workflow statuses (e.g., \`status: OrderStatus!\` where the enum has an initial value like \`DRAFT\`)
+
 ### ⚠️ CRITICAL: State Type Naming Convention
 
 **MANDATORY**: The global state type name MUST follow this exact pattern:
@@ -361,12 +451,51 @@ type TodoListLocalState {
 - **Objects in arrays**: Must include \`OID!\` field for unique identification
 - Include \`OLabel\` for metadata when relevant
 
+#### OID vs PHID Usage
+
+- \`OID\` is used as **primary key** (\`id: OID!\`) and **foreign key** (\`otherObjectId: OID!\`) within a document
+- \`PHID\` is **only** for referencing **external documents** (other documents in the drive), typically alongside cached properties (like a link preview — title/snippet may become stale)
+- **NEVER** use the \`ID\` type — it is a common GraphQL convention but is not used in Powerhouse document models
+
+#### Collection Sorting & Trees
+
+- **No need for \`position\` or \`weight\` properties** — maintain order via array index; operations like \`MOVE_X\` reorder the array directly
+- **Trees**: Always define as a flat list with \`parentId: OID\` (root nodes have \`parentId = null\`); do NOT use recursive/nested types
+
 ### Input Types
 
 - Reflect user intent with descriptive names
 - Simple, specific fields over complex nested types
 - System auto-generates \`OID\` for new objects (users don't provide manually)
 
+#### Input Type Naming Convention
+
+- Root input type **MUST** be named \`<OperationName>Input\` (PascalCase of the operation name)
+- Example: operation \`SET_CATEGORY_LABEL\` → input type \`SetCategoryLabelInput\`
+- **Failing to follow this convention breaks the code generator**
+
+#### Input Types Cannot Reference State Types
+
+- In operation input schemas, **ONLY** \`enum\` types and scalar types from the state schema can be referenced directly
+- All other state types must be **mirrored** with unique input types (e.g., state type \`MenuItem\` → input type \`NewMenuItemInput\` for the ADD operation)
+- State \`enum\` types **MUST NOT** be redefined in input schemas — reference them directly
+- Each operation should have its **own** input types; do not share mirror types across operations
+
+#### Empty Input Workaround
+
+- Input types with **zero fields** are not supported by the code generator
+- Workaround: add \`_: Boolean\` as a dummy optional parameter
+
+~~~graphql
+# ❌ BAD - empty input type breaks codegen
+input ClearAllInput {}
+
+# ✅ GOOD - dummy field workaround
+input ClearAllInput {
+    _: Boolean
+}
+~~~
+
 ## Working with Drives
 
 **MANDATORY**: Check the document-drive schema before performing drive operations.

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAshB/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"}

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

@@ -1,408 +1,2 @@
-import { md } from "@tmpl/core";
-export const claudeTemplate = md `
-# Powerhouse Document Models Assistant
-
-This project creates document models, editors, processors and subgraphs for the Powerhouse ecosystem. Your role is to help users create these modules based on their needs.
-
-## Core Concepts
-
-- **Document Model**: A template for creating documents. Defines schema and allowed operations for a document type.
-- **Document**: An instance of a document model containing actual data that follows the model's structure and can be modified using operations.
-- **Drive**: A document of type "powerhouse/document-drive" representing a collection of documents and folders. Add documents using "addActions" with "ADD_FILE" action.
-- **Action**: A proposed change to a document (JSON object with action name and input). Dispatch using "addActions" tool.
-- **Operation**: A completed change to a document containing the action plus metadata (index, timestamp, hash, errors). Actions become operations after dispatch.
-
-## CRITICAL: MCP Tool Usage Rules
-
-**MANDATORY**: The \`reactor-mcp\` MUST BE USED when handling documents or document-models for the Powerhouse/Vetra ecosystem.
-If the \`reactor-mcp\` server is unavailable, ask the user to run \`ph vetra\` on a separate terminal to start the server and try to reconnect to the MCP server, DO NOT run it yourself.
-
-### Key Requirements:
-
-- Never set document IDs manually - they're auto-generated by 'createDocument'
-- Minimize "addActions" calls by batching multiple actions together
-- Add new document model documents to "vetra-{hash}" drive unless specified otherwise
-- Always check document model schema before calling addActions
-- Use MCP tools for ALL document and document-model operations
-
-## Document Model Creation Workflow
-
-### 1. Planning Phase
-
-**MANDATORY**: Present your proposal to the user and ask for confirmation before implementing ANY document model.
-
-- **ALWAYS** describe the proposed document model structure (state schema, operations, modules) before creating
-- **NEVER** proceed with implementation without explicit user approval of your proposal
-- When in doubt, ask for clarification
-- Break complex models into logical modules and operations
-
-### 2. Pre-Implementation Requirements
-
-**MANDATORY**: Check document model schema before making any MCP tool calls.
-
-- **ALWAYS** use \`mcp__reactor-mcp__getDocumentModelSchema\` with \`type: "powerhouse/document-model"\` first
-- Review input schema requirements for operations like \`ADD_MODULE\`, \`ADD_OPERATION\`, etc.
-- Ensure all required parameters (like \`id\` or \`scope\` fields) are included in action inputs
-- This prevents failed tool calls and reduces iteration
-
-### 3. Implementation Requirements
-
-- Document model reducers must be **pure synchronous functions**
-- Reducers receive current state and operation, always returning the same result
-- Values like dates/IDs must come from operation input, not generated in reducer
-- Reducer code goes into SET_OPERATION_REDUCER action (no function header needed)
-- Reducers are wrapped with Mutative - you can mutate the state object directly
-- External imports go at the beginning of the actual reducer file in \`src/\`
-- Ensure that the reducer code of each operation in the document model schema is applied in \`document-models/<document-model-name>/src/reducers/<module-name>.ts\`
-
-### 4. Quality assurance
-
-After doing changes to the code, or after creating a new document model or a new editor, _YOU MUST RUN_ the following commands to check for errors in your implementation:
-
-- **TypeScript Check**: Run \`npm run tsc\` to validate type safety
-- **ESLint Check**: Run \`npm run lint:fix\` to check for errors with ESLint
-
-## Document editor creation flow
-
-When the user requests to create or make changes on a document editor, follow these steps:
-
-- Check if the document editor already exists and if it does, ask the user if a new one should be created or if the existing one should be reimplemented
-- If it's a new editor, create a new editor document on the "vetra-{hash}" drive if available, of type \`powerhouse/document-editor\`
-- Check the document editor schema and comply with it
-- After adding the editor document to the \`vetra-{hash}\` drive, a new editor will be generated in the \`editors\` folder
-- Inspect the hooks in \`editors/hooks\` as they should be useful
-- Read the schema of the document model that the editor is for to know how to interact with it
-- Style the editor using tailwind classes or a style tag. If using a style tag, make sure to make the selectors specific to only apply to the editor component.
-- Create modular components for the UI elements and place them on separate files to make it easier to maintain and update
-- Consider using the React Components exported by \`@powerhousedao/design-system\` and \`@powerhousedao/document-engineering\`
-- Separate business logic from presentation logic
-- Use TypeScript for type safety, avoid using any and type casting
-- Always check for type and lint errors after creating or modifying the editor
-
-### Document Editor Implementation Pattern
-
-**CRITICAL**: When implementing document editors, use the modern React hooks pattern from \`@powerhousedao/reactor-browser\`.
-
-The following section is valid for editors that edit a single document type.
-
-#### Required Imports and Setup
-
-Using a "Todo" document model as example:
-
-~~~typescript
-import { generateId } from "document-model/core";
-import { useSelectedTodoDocument } from "../hooks/useTodoDocument.js";
-import {
-  addTodo,
-} from "../../document-models/todo/gen/creators.js";
-
-export default function Editor() {
-  const [document, dispatch] = useSelectedTodoDocument();
-
-  function handleAddTodo(values: { title: string }) {
-    if (values.title) {
-      dispatch(addTodo({ id: generateId(), title: values.title }));
-    }
-  };
-~~~
-
-The \`useSelectedTodoDocument\` gets generated automatically so you don't need to implement it yourself.
-
-## ⚠️ CRITICAL: Generated Files & Modification Rules
-
-### Generated Files Rule
-
-**NEVER edit files in \`gen/\` folders** - they are auto-generated and will be overwritten.
-
-### Document Model Modification Process
-
-For ANY document model changes, follow this **mandatory** two-step process:
-
-#### Step 1: Update Document Model via MCP
-
-Use \`mcp__reactor-mcp__addActions\` with operations like:
-
-- \`SET_OPERATION_SCHEMA\` - update input/output schemas
-- \`SET_OPERATION_REDUCER\` - update reducer code
-- \`SET_STATE_SCHEMA\` - update state definitions
-
-#### Step 2: Update Existing Source Files
-
-**ALSO manually update existing reducer files in \`src/\` folder** - these are NOT auto-generated.
-Make sure to check if the operation reducer code needs to be updated after changing the state schema.
-
-### ⚠️ Critical Reminder
-
-**ALWAYS do BOTH steps when fixing reducer issues:**
-
-1. ✅ Fix existing reducer files in \`src/\` manually
-2. ✅ Update document model via MCP with same fixes
-
-**Forgetting step 2 means future code generations will still contain the bugs!**
-
-## Reducer Implementation Guidelines
-
-### ❌ Forbidden in Reducers (Non-Deterministic)
-
-- \`crypto.randomUUID()\`, \`Math.random()\`, \`Date.now()\`, \`new Date()\`
-- External API calls or side effects
-- Asynchronous functions
-- Any non-deterministic functions
-
-### ❌ Forbidden Patterns
-
-~~~typescript
-// NEVER use fallback values with non-deterministic functions
-id: action.input.id || crypto.randomUUID(); // ❌ FORBIDDEN
-timestamp: action.input.timestamp || new Date(); // ❌ FORBIDDEN
-~~~
-
-### ✅ Required Pattern
-
-All dynamic values must come from action input:
-
-- **IDs**: Include \`id: OID!\` in input schema, use \`action.input.id\` in reducer
-- **Timestamps**: Include \`timestamp: DateTime!\` in input schema
-- **Computed values**: Calculate before dispatching action
-
-### Example
-
-~~~typescript
-// ❌ BAD - impure reducer
-const newItem = {
-  id: crypto.randomUUID(), // Non-deterministic
-  createdAt: new Date(), // Non-deterministic
-};
-
-// ✅ GOOD - pure reducer
-const newItem = {
-  id: action.input.id, // From action input
-  createdAt: action.input.createdAt, // From action input
-};
-~~~
-
-### Handling Nullable Input Types
-
-**CRITICAL**: Be careful when handling optional input types:
-
-- Optional input types use \`InputMaybe<T>\` allowing \`null | undefined | T\`.
-- Optional state types use \`Maybe<T>\` = \`T | null\`.
-- If there is no applicable default value then use \`|| null\`.
-
-~~~typescript
-// ❌ BAD - Type error with Maybe<string>
-amount: action.input.amount,
-notes: action.input.notes,
-
-// ✅ GOOD - Matches Maybe<T> = T | null
-amount: action.input.amount || null,
-notes: action.input.notes || [],
-~~~
-
-Use truthy checks when conditionally assigning optional values from input to state:
-
-~~~typescript
-// ❌ BAD - Type 'string | null' is not assignable to type 'string'.
-if (action.input.field !== undefined) entry.field = action.input.field;
-
-// ✅ GOOD - use truthy checks
-if (action.input.field) state.field = action.input.field;
-
-// ✅ GOOD - For booleans use explicit null/undefined checks
-if (action.input.field !== undefined && action.input.field !== null)
-  state.field = action.input.field;
-~~~
-
-### Error Handling in Operations
-
-**MANDATORY**: Define specific error types for each operation to handle invalid inputs and edge cases properly.
-Action inputs are validated so they are guaranteed to respect the input schema.
-Errors referenced in the reducer code will be imported automatically.
-
-#### Error Definition Requirements
-
-1. **Add error definitions** to operations using \`ADD_OPERATION_ERROR\`:
-   - \`code\`: Uppercase snake_case (e.g., \`"MISSING_ID"\`, \`"ENTRY_NOT_FOUND"\`)
-   - \`name\`: PascalCase ending with "Error" (e.g., \`"MissingIdError"\`, \`"EntryNotFoundError"\`)
-   - \`description\`: Human-readable description of the error condition
-
-2. **Error names must end with "Error"** for consistency and code generation
-
-3. **Use specific error types** rather than generic validation
-
-4. **Must use unique error names and ids**
-
-#### Error Usage in Reducers
-
-~~~typescript
-// ✅ GOOD - Throw specific errors by name
-if (!action.input.id) {
-  throw new MissingIdError("ID is required for operation");
-}
-
-if (entryIndex === -1) {
-  throw new EntryNotFoundError(\`Entry not found\`);
-}
-
-// ❌ BAD - Generic Error
-throw new Error("Something went wrong");
-
-// ❌ BAD - Nested error access
-throw new errors.ModuleName.MissingIdError("message");
-
-// ❌ BAD - Do not import error classes in the reducer code,
-import { MissingIdError } from "../../gen/module-name/error.js";
-
-// ✅ GOOD - Simply reference the error and it will be imported automatically
-throw new MissingIdError("message");
-~~~
-
-#### Common Error Patterns
-
-- **EntityNotFoundError**: Referenced entity doesn't exist
-- **DuplicateIdError**: ID already exists when creating new entries
-- **InvalidInputError**: Business logic violations
-- **PermissionDeniedError**: Access control violations
-
-## Document Model Structure
-
-### Core Components
-
-- **Basic Metadata**: \`id\`, \`name\`, \`extension\`, \`description\`, \`author\` (name + website)
-- **Specifications**: Versioned specs with \`version\`, \`changeLog\`, \`state\` (global/local with schema, initialValue, examples)
-- **Modules**: Operational modules containing their operations
-
-## Available Document Model Operations (37 total)
-
-| Category                         | Operations                                                                                                                                                                                                       | Count |
-| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| **Header Management**            | \`SET_MODEL_NAME\`, \`SET_MODEL_ID\`, \`SET_MODEL_EXTENSION\`, \`SET_MODEL_DESCRIPTION\`, \`SET_AUTHOR_NAME\`, \`SET_AUTHOR_WEBSITE\`                                                                                        | 6     |
-| **Versioning**                   | ⚠️ **DO NOT USE** - Not implemented                                                                                                                                                                              | 0     |
-| **Module Management**            | \`ADD_MODULE\`, \`SET_MODULE_NAME\`, \`SET_MODULE_DESCRIPTION\`, \`DELETE_MODULE\`, \`REORDER_MODULES\`                                                                                                                    | 5     |
-| **Operation Management**         | \`ADD_OPERATION\`, \`SET_OPERATION_NAME\`, \`SET_OPERATION_SCHEMA\`, \`SET_OPERATION_DESCRIPTION\`, \`SET_OPERATION_TEMPLATE\`, \`SET_OPERATION_REDUCER\`, \`MOVE_OPERATION\`, \`DELETE_OPERATION\`, \`REORDER_MODULE_OPERATIONS\` | 9     |
-| **Operation Error Management**   | \`ADD_OPERATION_ERROR\`, \`SET_OPERATION_ERROR_CODE\`, \`SET_OPERATION_ERROR_NAME\`, \`SET_OPERATION_ERROR_DESCRIPTION\`, \`SET_OPERATION_ERROR_TEMPLATE\`, \`DELETE_OPERATION_ERROR\`, \`REORDER_OPERATION_ERRORS\`           | 7     |
-| **Operation Example Management** | \`ADD_OPERATION_EXAMPLE\`, \`UPDATE_OPERATION_EXAMPLE\`, \`DELETE_OPERATION_EXAMPLE\`, \`REORDER_OPERATION_EXAMPLES\`                                                                                                    | 4     |
-| **State Management**             | \`SET_STATE_SCHEMA\`, \`SET_INITIAL_STATE\`, \`ADD_STATE_EXAMPLE\`, \`UPDATE_STATE_EXAMPLE\`, \`DELETE_STATE_EXAMPLE\`, \`REORDER_STATE_EXAMPLES\`                                                                           | 6     |
-
-## Best Practices & Design Principles
-
-### Scope Selection
-
-- **\`scope: "global"\`**: State shared among all users with document access
-- **\`scope: "local"\`**: State private to each individual user
-
-### Operation Design
-
-- Use descriptive operation names (e.g., \`ADD_LINE_ITEM\`, \`UPDATE_RECIPIENT\`)
-- One operation per user intent (separate concerns)
-- Include comprehensive examples and error definitions
-- Organize related operations into logical modules
-
-## GraphQL Schema Guidelines
-
-### Document State Schema
-
-- **Most fields optional** to support creating empty documents
-- Use required fields \`!\` only when absolutely necessary
-- Defaults handled by operations, not schema
-
-### ⚠️ CRITICAL: State Type Naming Convention
-
-**MANDATORY**: The global state type name MUST follow this exact pattern:
-
-~~~graphql
-type <DocumentModelName>State {
-    # your fields here
-}
-~~~
-
-**DO NOT** append "Global" to the state type name, even when defining global state:
-
-~~~graphql
-// ❌ WRONG - Do not use "GlobalState" suffix
-type TodoListGlobalState {
-    todos: [Todo!]!
-}
-
-// ✅ CORRECT - Use only "State" suffix
-type TodoListState {
-    todos: [Todo!]!
-}
-
-// ✅ CORRECT - Use "LocalState" suffix for Local scope
-type TodoListLocalState {
-    localTodos: [Todo!]!
-}
-~~~
-
-**Why this matters:**
-
-- The code generator expects the type to be named \`<DocumentModelName>State\`
-- Using \`GlobalState\` or \`LocalState\` suffix will cause TypeScript compilation errors
-- This applies when using \`SET_STATE_SCHEMA\` with \`scope: "global"\`
-
-**Rule**: For global state, the type should be \`<DocumentModelName>State\`. For local state (if needed), the type name should be \`<DocumentModelName>LocalState\`.
-
-### Available Scalar Types
-
-| Standard  | Custom Identity        | Custom Amounts      | Custom Specialized |
-| --------- | ---------------------- | ------------------- | ------------------ |
-| \`String\`  | \`OID\` (Object ID)      | \`Amount\`            | \`EthereumAddress\`  |
-| \`Int\`     | \`PHID\` (Powerhouse ID) | \`Amount_Tokens\`     | \`EmailAddress\`     |
-| \`Float\`   | \`OLabel\`               | \`Amount_Money\`      | \`Date\`             |
-| \`Boolean\` |                        | \`Amount_Fiat\`       | \`DateTime\`         |
-|           |                        | \`Amount_Currency\`   | \`URL\`              |
-|           |                        | \`Amount_Crypto\`     | \`Currency\`         |
-|           |                        | \`Amount_Percentage\` |                    |
-
-### Arrays and Objects
-
-- **Arrays**: Must be mandatory \`[ObjectType!]!\`
-- **Objects in arrays**: Must include \`OID!\` field for unique identification
-- Include \`OLabel\` for metadata when relevant
-
-### Input Types
-
-- Reflect user intent with descriptive names
-- Simple, specific fields over complex nested types
-- System auto-generates \`OID\` for new objects (users don't provide manually)
-
-## Working with Drives
-
-**MANDATORY**: Check the document-drive schema before performing drive operations.
-
-### Drive Types
-
-There might be two drives available with a special use case:
-
-1. **Vetra Drive** (\`vetra-{hash}\`):
-   - Contains **source documents**: document models and document editors
-   - Used for development
-   - Add document model and editor definitions here
-
-2. **Preview Drive** (\`preview-{hash}\`, named "Vetra Preview"):
-   - Contains **demo and preview documents** (document instances)
-   - Used for showcasing and testing document models
-   - Add actual document instances here
-
-### Drive Operations
-
-When working with drives (adding/removing documents, creating folders, etc.):
-
-1. **Always get the drive schema first**:
-
-   ~~~typescript
-   mcp__reactor -
-     mcp__getDocumentModelSchema({ type: "powerhouse/document-drive" });
-   ~~~
-
-2. **Review available operations** in the schema, such as:
-   - \`ADD_FILE\` - Add a document to the drive
-   - \`ADD_FOLDER\` - Create a new folder
-   - \`DELETE_NODE\` - Remove a file or folder (use this, NOT "DELETE_FILE")
-   - \`UPDATE_NODE\` - Update node properties
-   - \`MOVE_NODE\` - Move a node to different location
-
-3. **Check input schemas** for each operation to ensure you're passing correct parameters
-`.raw;
+export { agentsTemplate as claudeTemplate } from "./AGENTS.md.js";
 //# sourceMappingURL=CLAUDE.md.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"CLAUDE.md.js","sourceRoot":"","sources":["../../../../src/templates/boilerplate/CLAUDE.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":"CLAUDE.md.js","sourceRoot":"","sources":["../../../../src/templates/boilerplate/CLAUDE.md.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/src/templates/boilerplate/docker/Dockerfile.d.ts

@@ -0,0 +1,2 @@
+export declare const dockerfileTemplate = "# =============================================================================\n# Multi-stage Dockerfile for Powerhouse Document Model Packages\n# Produces two images: connect (frontend) and switchboard (backend)\n#\n# Build commands:\n#   docker build --target connect -t <registry>/<project>/connect:<tag> .\n#   docker build --target switchboard -t <registry>/<project>/switchboard:<tag> .\n# =============================================================================\n\n# -----------------------------------------------------------------------------\n# Base stage: Common setup for building\n# -----------------------------------------------------------------------------\nFROM node:24-alpine AS base\n\nWORKDIR /app\n\n# Install build dependencies\nRUN apk add --no-cache python3 make g++ git bash \\\n    && ln -sf /usr/bin/python3 /usr/bin/python\n\n# Setup pnpm\nENV PNPM_HOME=\"/pnpm\"\nENV PATH=\"$PNPM_HOME:$PATH\"\nRUN corepack enable && corepack prepare pnpm@latest --activate\n\n# Configure JSR registry\nRUN pnpm config set @jsr:registry https://npm.jsr.io\n\n# Build arguments\nARG TAG=latest\nARG PH_CONNECT_BASE_PATH=\"/\"\n\n# Install ph-cmd, prisma, and prettier globally\nRUN pnpm add -g ph-cmd@$TAG prisma@5.17.0 prettier\n\n# Initialize project based on tag (dev/staging/latest)\nRUN case \"$TAG\" in \\\n        *dev*) ph init project --dev --package-manager pnpm ;; \\\n        *staging*) ph init project --staging --package-manager pnpm ;; \\\n        *) ph init project --package-manager pnpm ;; \\\n    esac\n\nWORKDIR /app/project\n\n# Copy package files for the current package\nCOPY package.json pnpm-lock.yaml ./\n\n# Install the current package (this package)\nARG PACKAGE_NAME\nRUN if [ -n \"$PACKAGE_NAME\" ]; then \\\n        echo \"Installing package: $PACKAGE_NAME\"; \\\n        ph install \"$PACKAGE_NAME\"; \\\n    else \\\n        echo \"Warning: PACKAGE_NAME not provided, using local build\"; \\\n        pnpm install; \\\n    fi\n\n# Regenerate Prisma client for Alpine Linux\nRUN prisma generate --schema node_modules/document-drive/dist/prisma/schema.prisma || true\n\n# -----------------------------------------------------------------------------\n# Connect build stage\n# -----------------------------------------------------------------------------\nFROM base AS connect-builder\n\nARG PH_CONNECT_BASE_PATH=\"/\"\n\n# Build connect\nRUN ph connect build --base ${PH_CONNECT_BASE_PATH}\n\n# -----------------------------------------------------------------------------\n# Connect final stage - nginx\n# -----------------------------------------------------------------------------\nFROM nginx:alpine AS connect\n\n# Install envsubst for config templating\nRUN apk add --no-cache gettext\n\n# Copy nginx config template\nCOPY docker/nginx.conf /etc/nginx/nginx.conf.template\n\n# Copy built static files from build stage\nCOPY --from=connect-builder /app/project/.ph/connect-build/dist /var/www/html/project\n\n# Environment variables for nginx config\nENV PORT=3001\nENV PH_CONNECT_BASE_PATH=\"/\"\n\n# Copy and setup entrypoint\nCOPY docker/connect-entrypoint.sh /docker-entrypoint.sh\nRUN chmod +x /docker-entrypoint.sh\n\nEXPOSE ${PORT}\n\nHEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \\\n    CMD wget -q --spider http://localhost:${PORT}/health || exit 1\n\nENTRYPOINT [\"/docker-entrypoint.sh\"]\n\n# -----------------------------------------------------------------------------\n# Switchboard final stage - node runtime\n# -----------------------------------------------------------------------------\nFROM node:24-alpine AS switchboard\n\nWORKDIR /app\n\n# Install runtime dependencies\nRUN apk add --no-cache curl openssl\n\n# Setup pnpm\nENV PNPM_HOME=\"/pnpm\"\nENV PATH=\"$PNPM_HOME:$PATH\"\nRUN corepack enable && corepack prepare pnpm@latest --activate\n\n# Configure JSR registry\nRUN pnpm config set @jsr:registry https://npm.jsr.io\n\n# Install ph-cmd and prisma globally (needed at runtime)\nARG TAG=latest\nRUN pnpm add -g ph-cmd@$TAG prisma@5.17.0\n\n# Copy built project from build stage\nCOPY --from=base /app/project /app/project\n\nWORKDIR /app/project\n\n# Copy entrypoint\nCOPY docker/switchboard-entrypoint.sh /app/entrypoint.sh\nRUN chmod +x /app/entrypoint.sh\n\n# Environment variables\nENV NODE_ENV=production\nENV PORT=3000\nENV DATABASE_URL=\"\"\nENV SKIP_DB_MIGRATIONS=\"false\"\n\nEXPOSE ${PORT}\n\nHEALTHCHECK --interval=30s --timeout=3s --start-period=30s --retries=3 \\\n    CMD curl -f http://localhost:${PORT}/health || exit 1\n\nENTRYPOINT [\"/app/entrypoint.sh\"]\n";
+//# sourceMappingURL=Dockerfile.d.ts.map