ph-cmd 6.0.0-dev.14 → 6.0.0-dev.16

package/build/cli.js

@@ -658661,7 +658661,7 @@ var exports_version = {};
 __export(exports_version, {
   version: () => version2
 });
-var version2 = "6.0.0-dev.13";
+var version2 = "6.0.0-dev.15";
 
 // ../../node_modules/.pnpm/didyoumean@1.2.2/node_modules/didyoumean/didYouMean-1.2.1.js
 var require_didYouMean_1_2_1 = __commonJS((exports, module3) => {
@@ -664654,413 +664654,47 @@ throw new MissingIdError("message");
 - **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;
-// ../../packages/codegen/dist/src/templates/boilerplate/CLAUDE.md.js
-var 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;
+#### Testing Reducer Errors
 
-// ✅ GOOD - use truthy checks
-if (action.input.field) state.field = action.input.field;
+**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.
 
-// ✅ GOOD - For booleans use explicit null/undefined checks
-if (action.input.field !== undefined && action.input.field !== null)
-  state.field = action.input.field;
-~~~
+**DO NOT** use \`.toThrow()\` or \`expect(() => ...).toThrow()\` patterns when testing reducer errors.
 
-### Error Handling in Operations
+##### How Errors Work 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.
+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
 
-#### Error Definition Requirements
+##### Accessing the Correct Operation Index
 
-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
+**CRITICAL**: You must access the correct operation index. The index corresponds to how many operations were dispatched before it.
 
-3. **Use specific error types** rather than generic validation
-
-4. **Must use unique error names and ids**
+- If this is the **first** operation dispatched, access \`[0]\`
+- If 3 operations were dispatched **before** the failing one, access \`[3]\`
 
-#### Error Usage in Reducers
+##### Example
 
 ~~~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\`);
-}
+it("should return error and not mutate state", () => {
+  const document = utils.createDocument();
+  const initialState = document.state.global.name;
 
-// ❌ BAD - Generic Error
-throw new Error("Something went wrong");
-
-// ❌ BAD - Nested error access
-throw new errors.ModuleName.MissingIdError("message");
+  const updatedDocument = reducer(document, setName({ name: "invalid" }));
 
-// ❌ BAD - Do not import error classes in the reducer code,
-import { MissingIdError } from "../../gen/module-name/error.js";
+  // 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);
+});
 
-// ✅ GOOD - Simply reference the error and it will be imported automatically
-throw new MissingIdError("message");
+// ❌ WRONG - Never use toThrow()
+expect(() => reducer(document, setName({ name: "invalid" }))).toThrow();
 ~~~
 
-#### 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
@@ -693303,7 +692937,7 @@ async function writeModuleFiles() {
   await writeFileEnsuringDir("subgraphs/index.ts", subgraphsIndexTemplate);
 }
 async function writeAiConfigFiles() {
-  await writeFileEnsuringDir("CLAUDE.md", claudeTemplate);
+  await writeFileEnsuringDir("CLAUDE.md", agentsTemplate);
   await writeFileEnsuringDir("AGENTS.md", agentsTemplate);
   await writeFileEnsuringDir(".mcp.json", mcpTemplate);
   await writeFileEnsuringDir(".gemini/settings.json", geminiSettingsTemplate);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ph-cmd",
-  "version": "6.0.0-dev.14",
+  "version": "6.0.0-dev.16",
   "description": "",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -29,8 +29,8 @@
     "read-pkg": "^9.0.1",
     "write-package": "^7.2.0",
     "vitest": "^3.2.4",
-    "@powerhousedao/codegen": "6.0.0-dev.14",
-    "@powerhousedao/common": "6.0.0-dev.14"
+    "@powerhousedao/codegen": "6.0.0-dev.16",
+    "@powerhousedao/common": "6.0.0-dev.16"
   },
   "scripts": {
     "tsc": "tsc",