unspaghettit 0.2.0 → 0.4.0

package/mcp-server/tools/effect.ts

@@ -1,135 +1,139 @@
-import { z } from 'zod';
-import {
-  addEffectToCapability,
-  removeEffectFromCapability,
-  updateEffectOnCapability
-} from '../../src/features/behavior-model/domain/services/FeatureTransforms';
-import type { Effect } from '../../src/features/behavior-model/domain/value-objects/Effect';
-import {
-  asActionId,
-  asEffectId,
-  asFeatureId,
-  asSurfaceId
-} from '../../src/features/behavior-model/domain/value-objects/ids';
-import { runMutation, type ToolDeps } from './_shared';
-
-const effectSchemaDescription =
-  'Discriminated by `type`: set_state{path,value,description} | show_message{message,tone?:info|success|warning|error,description} | emit_event{event,description} | block_action{reason,description} | allow_action{description} | transition_surface{target,description}. description is mandatory. set_state.value can be either a raw literal OR a structured Expression { kind:"literal"|"state"|"param"|"add"|"sub"|"mul"|"div"|"mod"|"min"|"max"|"neg", ... }. See add_action_rule description for the full AST. Example: value:{ kind:"add", left:{kind:"state",path:"player.vx"}, right:{kind:"param",name:"ax"} } writes vx+ax. transition_surface accepts `targetRef` in apply_batch to point at a surface created earlier in the same batch (mirrors add_transition).';
-
-const KNOWN_EFFECT_TYPES = [
-  'set_state',
-  'show_message',
-  'emit_event',
-  'block_action',
-  'allow_action',
-  'transition_surface'
-] as const;
-
-const effectInputSchema = z
-  .record(z.string(), z.unknown())
-  .superRefine((effect, ctx) => {
-    if (typeof effect.description !== 'string' || effect.description.trim().length === 0) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: 'Effect description is required'
-      });
-    }
-    // Validate type up-front so bad data can't land in storage and crash the
-    // simulator later with "Cannot read properties of undefined (reading
-    // 'blocked')". Common slip: writing "block" instead of "block_action".
-    const type = (effect as { type?: unknown }).type;
-    if (typeof type !== 'string' || !(KNOWN_EFFECT_TYPES as readonly string[]).includes(type)) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: `Effect.type must be one of ${KNOWN_EFFECT_TYPES.join(', ')} (got ${JSON.stringify(type)})`
-      });
-    }
-  })
-  .describe(effectSchemaDescription);
-
-export const registerEffectTools = (deps: ToolDeps): void => {
-  const { server, ids } = deps;
-
-  server.registerTool(
-    'add_effect',
-    {
-      description: 'Append Effect that fires on action success. For conditional blocks, use add_action_rule.',
-      inputSchema: {
-        featureId: z.string(),
-        surfaceId: z.string(),
-        actionId: z.string(),
-        effect: effectInputSchema
-      }
-    },
-    async ({ featureId, surfaceId, actionId, effect }) => {
-      const built = {
-        ...(effect as object),
-        id: asEffectId((effect as { id?: string }).id ?? ids())
-      } as unknown as Effect;
-      return runMutation(
-        deps,
-        {
-          featureId: asFeatureId(featureId),
-          transform: (exp) =>
-            addEffectToCapability(
-              exp,
-              asSurfaceId(surfaceId),
-              asActionId(actionId),
-              built
-            )
-        },
-        { createdId: built.id }
-      );
-    }
-  );
-
-  server.registerTool(
-    'update_effect',
-    {
-      description: 'Patch Effect fields. Id fixed.',
-      inputSchema: {
-        featureId: z.string(),
-        surfaceId: z.string(),
-        actionId: z.string(),
-        effectId: z.string(),
-        patch: z.record(z.string(), z.unknown())
-      }
-    },
-    async ({ featureId, surfaceId, actionId, effectId, patch }) =>
-      runMutation(deps, {
-        featureId: asFeatureId(featureId),
-        transform: (exp) =>
-          updateEffectOnCapability(
-            exp,
-            asSurfaceId(surfaceId),
-            asActionId(actionId),
-            asEffectId(effectId),
-            patch as Partial<Effect>
-          )
-      })
-  );
-
-  server.registerTool(
-    'remove_effect',
-    {
-      description: 'Delete Effect from Action.',
-      inputSchema: {
-        featureId: z.string(),
-        surfaceId: z.string(),
-        actionId: z.string(),
-        effectId: z.string()
-      }
-    },
-    async ({ featureId, surfaceId, actionId, effectId }) =>
-      runMutation(deps, {
-        featureId: asFeatureId(featureId),
-        transform: (exp) =>
-          removeEffectFromCapability(
-            exp,
-            asSurfaceId(surfaceId),
-            asActionId(actionId),
-            asEffectId(effectId)
-          )
-      })
-  );
-};
+import { z } from 'zod';
+import {
+  addEffectToCapability,
+  removeEffectFromCapability,
+  updateEffectOnCapability
+} from '../../src/features/behavior-model/domain/services/FeatureTransforms';
+import type { Effect } from '../../src/features/behavior-model/domain/value-objects/Effect';
+import {
+  asActionId,
+  asEffectId,
+  asFeatureId,
+  asSurfaceId
+} from '../../src/features/behavior-model/domain/value-objects/ids';
+import { runMutation, type ToolDeps } from './_shared';
+
+const effectSchemaDescription =
+  'Discriminated by `type`: set_state{path,value,description} | show_message{message,tone?:info|success|warning|error,description} | emit_event{event,description} | block_action{reason,description} | allow_action{description} | transition_surface{target,description} | append_to_list{path,item,description} | remove_from_list{path,where?:{field,equals},value?,description} | update_list_item{path,where:{field,equals},field,value,description}. description is mandatory. set_state.value (and append_to_list.item, the *.where.equals comparand, update_list_item.value) can be either a raw literal OR a structured Expression { kind:"literal"|"state"|"param"|"add"|"sub"|"mul"|"div"|"mod"|"min"|"max"|"neg", ... }. See add_action_rule description for the full AST. Example: value:{ kind:"add", left:{kind:"state",path:"player.vx"}, right:{kind:"param",name:"ax"} } writes vx+ax. The collection effects mutate an array-typed state path WITHOUT overwriting it: append_to_list pushes item; remove_from_list drops elements matching where{field,equals} (objects) or value (scalars/whole-object); update_list_item sets `field` to value on every element matching where. Example: append_to_list{path:"cart.lines",item:{kind:"param",name:"line"}} then update_list_item{path:"cart.lines",where:{field:"productId",equals:{kind:"param",name:"productId"}},field:"qty",value:{kind:"param",name:"qty"}}. advance_time{by} moves the simulation clock (the reserved numeric path `clock.now`, seeded to 0 and readable from any surface) forward by `by` logical time units (never backward); model deadlines as conditions/invariants comparing a stored timestamp to clock.now (e.g. invariant "token valid": { left:"token.expiresAt", operator:"greater_than", right:{kind:"state",path:"clock.now"} }) and advance the clock via this effect or a scenario `timeAdvance` to drive past them. transition_surface accepts `targetRef` in apply_batch to point at a surface created earlier in the same batch (mirrors add_transition).';
+
+const KNOWN_EFFECT_TYPES = [
+  'set_state',
+  'show_message',
+  'emit_event',
+  'block_action',
+  'allow_action',
+  'transition_surface',
+  'append_to_list',
+  'remove_from_list',
+  'update_list_item',
+  'advance_time'
+] as const;
+
+const effectInputSchema = z
+  .record(z.string(), z.unknown())
+  .superRefine((effect, ctx) => {
+    if (typeof effect.description !== 'string' || effect.description.trim().length === 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'Effect description is required'
+      });
+    }
+    // Validate type up-front so bad data can't land in storage and crash the
+    // simulator later with "Cannot read properties of undefined (reading
+    // 'blocked')". Common slip: writing "block" instead of "block_action".
+    const type = (effect as { type?: unknown }).type;
+    if (typeof type !== 'string' || !(KNOWN_EFFECT_TYPES as readonly string[]).includes(type)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Effect.type must be one of ${KNOWN_EFFECT_TYPES.join(', ')} (got ${JSON.stringify(type)})`
+      });
+    }
+  })
+  .describe(effectSchemaDescription);
+
+export const registerEffectTools = (deps: ToolDeps): void => {
+  const { server, ids } = deps;
+
+  server.registerTool(
+    'add_effect',
+    {
+      description: 'Append Effect that fires on action success. For conditional blocks, use add_action_rule.',
+      inputSchema: {
+        featureId: z.string(),
+        surfaceId: z.string(),
+        actionId: z.string(),
+        effect: effectInputSchema
+      }
+    },
+    async ({ featureId, surfaceId, actionId, effect }) => {
+      const built = {
+        ...(effect as object),
+        id: asEffectId((effect as { id?: string }).id ?? ids())
+      } as unknown as Effect;
+      return runMutation(
+        deps,
+        {
+          featureId: asFeatureId(featureId),
+          transform: (exp) =>
+            addEffectToCapability(
+              exp,
+              asSurfaceId(surfaceId),
+              asActionId(actionId),
+              built
+            )
+        },
+        { createdId: built.id }
+      );
+    }
+  );
+
+  server.registerTool(
+    'update_effect',
+    {
+      description: 'Patch Effect fields. Id fixed.',
+      inputSchema: {
+        featureId: z.string(),
+        surfaceId: z.string(),
+        actionId: z.string(),
+        effectId: z.string(),
+        patch: z.record(z.string(), z.unknown())
+      }
+    },
+    async ({ featureId, surfaceId, actionId, effectId, patch }) =>
+      runMutation(deps, {
+        featureId: asFeatureId(featureId),
+        transform: (exp) =>
+          updateEffectOnCapability(
+            exp,
+            asSurfaceId(surfaceId),
+            asActionId(actionId),
+            asEffectId(effectId),
+            patch as Partial<Effect>
+          )
+      })
+  );
+
+  server.registerTool(
+    'remove_effect',
+    {
+      description: 'Delete Effect from Action.',
+      inputSchema: {
+        featureId: z.string(),
+        surfaceId: z.string(),
+        actionId: z.string(),
+        effectId: z.string()
+      }
+    },
+    async ({ featureId, surfaceId, actionId, effectId }) =>
+      runMutation(deps, {
+        featureId: asFeatureId(featureId),
+        transform: (exp) =>
+          removeEffectFromCapability(
+            exp,
+            asSurfaceId(surfaceId),
+            asActionId(actionId),
+            asEffectId(effectId)
+          )
+      })
+  );
+};

package/mcp-server/tools/entity.ts

@@ -1,143 +1,143 @@
-import { z } from 'zod';
-import {
-  addEntity,
-  removeEntity,
-  updateEntity
-} from '../../src/features/behavior-model/domain/services/FeatureTransforms';
-import type { Entity, EntityField } from '../../src/features/behavior-model/domain/entities/Entity';
-import {
-  ALL_DATA_FIELD_TYPES,
-  type EntityFieldType
-} from '../../src/features/behavior-model/domain/value-objects/EntityFieldType';
-import {
-  asEntityFieldId,
-  asEntityId,
-  asFeatureId,
-  asResourceId
-} from '../../src/features/behavior-model/domain/value-objects/ids';
-import { asStatePath } from '../../src/features/behavior-model/domain/value-objects/StatePath';
-import { runMutation, type ToolDeps } from './_shared';
-
-const dataFieldTypeSchema = z.enum(
-  ALL_DATA_FIELD_TYPES as unknown as [EntityFieldType, ...EntityFieldType[]]
-);
-
-// EntityField is recursive; we accept a free-form record and rebuild ids/paths
-// recursively. The validator ensures top-level shape.
-const dataFieldInputSchema = z.record(z.string(), z.unknown());
-
+import { z } from 'zod';
+import {
+  addEntity,
+  removeEntity,
+  updateEntity
+} from '../../src/features/behavior-model/domain/services/FeatureTransforms';
+import type { Entity, EntityField } from '../../src/features/behavior-model/domain/entities/Entity';
+import {
+  ALL_DATA_FIELD_TYPES,
+  type EntityFieldType
+} from '../../src/features/behavior-model/domain/value-objects/EntityFieldType';
+import {
+  asEntityFieldId,
+  asEntityId,
+  asFeatureId,
+  asResourceId
+} from '../../src/features/behavior-model/domain/value-objects/ids';
+import { asStatePath } from '../../src/features/behavior-model/domain/value-objects/StatePath';
+import { runMutation, type ToolDeps } from './_shared';
+
+const dataFieldTypeSchema = z.enum(
+  ALL_DATA_FIELD_TYPES as unknown as [EntityFieldType, ...EntityFieldType[]]
+);
+
+// EntityField is recursive; we accept a free-form record and rebuild ids/paths
+// recursively. The validator ensures top-level shape.
+const dataFieldInputSchema = z.record(z.string(), z.unknown());
+
 type DataFieldInput = {
   name: string;
   type: EntityFieldType;
   description: string;
-  required?: boolean;
-  enumValues?: readonly string[];
-  path?: string;
-  fields?: readonly DataFieldInput[];
-  items?: DataFieldInput;
-};
-
-const buildDataField = (ids: () => string, input: DataFieldInput): EntityField => ({
+  required?: boolean;
+  enumValues?: readonly string[];
+  path?: string;
+  fields?: readonly DataFieldInput[];
+  items?: DataFieldInput;
+};
+
+const buildDataField = (ids: () => string, input: DataFieldInput): EntityField => ({
   id: asEntityFieldId(ids()),
   name: input.name,
   type: input.type,
   description: input.description,
-  ...(input.required !== undefined ? { required: input.required } : {}),
-  ...(input.enumValues ? { enumValues: input.enumValues } : {}),
-  ...(input.path ? { path: asStatePath(input.path) } : {}),
-  ...(input.fields ? { fields: input.fields.map((f) => buildDataField(ids, f)) } : {}),
-  ...(input.items ? { items: buildDataField(ids, input.items) } : {})
-});
-
-const dataFieldsArraySchema = z.array(dataFieldInputSchema);
-
-export const registerEntityTools = (deps: ToolDeps): void => {
-  const { server, ids } = deps;
-
-  server.registerTool(
-    'add_entity',
-    {
-      description: 'Declare a Entity entity (named domain object). Field types: string|number|boolean|enum|object|array|date|timestamp|null|json. Recursive via fields/items for object/array.',
-      inputSchema: {
-        featureId: z.string(),
-        namespace: z.string().min(1),
+  ...(input.required !== undefined ? { required: input.required } : {}),
+  ...(input.enumValues ? { enumValues: input.enumValues } : {}),
+  ...(input.path ? { path: asStatePath(input.path) } : {}),
+  ...(input.fields ? { fields: input.fields.map((f) => buildDataField(ids, f)) } : {}),
+  ...(input.items ? { items: buildDataField(ids, input.items) } : {})
+});
+
+const dataFieldsArraySchema = z.array(dataFieldInputSchema);
+
+export const registerEntityTools = (deps: ToolDeps): void => {
+  const { server, ids } = deps;
+
+  server.registerTool(
+    'add_entity',
+    {
+      description: 'Declare a Entity entity (named domain object). Field types: string|number|boolean|enum|object|array|date|timestamp|null|json. Recursive via fields/items for object/array.',
+      inputSchema: {
+        featureId: z.string(),
+        namespace: z.string().min(1),
         description: z.string().min(1),
-        fields: dataFieldsArraySchema,
-        resourceId: z.string().optional()
-      }
-    },
-    async ({ featureId, namespace, description, fields, resourceId }) => {
-      const data: Entity = {
-        id: asEntityId(ids()),
-        namespace,
+        fields: dataFieldsArraySchema,
+        resourceId: z.string().optional()
+      }
+    },
+    async ({ featureId, namespace, description, fields, resourceId }) => {
+      const data: Entity = {
+        id: asEntityId(ids()),
+        namespace,
         description,
-        fields: fields.map((f) => buildDataField(ids, f as DataFieldInput)),
-        ...(resourceId ? { resourceId: asResourceId(resourceId) } : {})
-      };
-      return runMutation(
-        deps,
-        {
-          featureId: asFeatureId(featureId),
-          transform: (exp) => addEntity(exp, data)
-        },
-        { createdId: data.id }
-      );
-    }
-  );
-
-  server.registerTool(
-    'update_entity',
-    {
-      description: 'Patch Entity fields. Id fixed. When `fields` is provided it fully replaces (field ids regenerated). Use add_entity_field/update_entity_field for in-place field edits.',
-      inputSchema: {
-        featureId: z.string(),
-        entityId: z.string(),
-        namespace: z.string().min(1).optional(),
+        fields: fields.map((f) => buildDataField(ids, f as DataFieldInput)),
+        ...(resourceId ? { resourceId: asResourceId(resourceId) } : {})
+      };
+      return runMutation(
+        deps,
+        {
+          featureId: asFeatureId(featureId),
+          transform: (exp) => addEntity(exp, data)
+        },
+        { createdId: data.id }
+      );
+    }
+  );
+
+  server.registerTool(
+    'update_entity',
+    {
+      description: 'Patch Entity fields. Id fixed. When `fields` is provided it fully replaces (field ids regenerated). Use add_entity_field/update_entity_field for in-place field edits.',
+      inputSchema: {
+        featureId: z.string(),
+        entityId: z.string(),
+        namespace: z.string().min(1).optional(),
         description: z.string().min(1).optional(),
-        fields: dataFieldsArraySchema.optional(),
-        resourceId: z.string().nullable().optional()
-      }
-    },
-    async ({ featureId, entityId, namespace, description, fields, resourceId }) =>
-      runMutation(deps, {
-        featureId: asFeatureId(featureId),
-        transform: (exp) => {
-          const existing = exp.entities.find((d) => d.id === asEntityId(entityId));
-          if (!existing) return exp;
-          const merged: Entity = {
-            ...existing,
-            ...(namespace !== undefined ? { namespace } : {}),
-            ...(description !== undefined ? { description } : {}),
-            ...(fields !== undefined
-              ? { fields: fields.map((f) => buildDataField(ids, f as DataFieldInput)) }
-              : {}),
-            ...(resourceId !== undefined
-              ? resourceId === null
-                ? { resourceId: undefined }
-                : { resourceId: asResourceId(resourceId) }
-              : {})
-          };
-          return updateEntity(exp, merged);
-        }
-      })
-  );
-
-  server.registerTool(
-    'remove_entity',
-    {
-      description: 'Delete Entity entity. State paths it documents stay valid elsewhere.',
-      inputSchema: {
-        featureId: z.string(),
-        entityId: z.string()
-      }
-    },
-    async ({ featureId, entityId }) =>
-      runMutation(deps, {
-        featureId: asFeatureId(featureId),
-        transform: (exp) => removeEntity(exp, asEntityId(entityId))
-      })
-  );
-
-  // Mark types referenced for type checker (avoid unused import warning).
-  void dataFieldTypeSchema;
-};
+        fields: dataFieldsArraySchema.optional(),
+        resourceId: z.string().nullable().optional()
+      }
+    },
+    async ({ featureId, entityId, namespace, description, fields, resourceId }) =>
+      runMutation(deps, {
+        featureId: asFeatureId(featureId),
+        transform: (exp) => {
+          const existing = exp.entities.find((d) => d.id === asEntityId(entityId));
+          if (!existing) return exp;
+          const merged: Entity = {
+            ...existing,
+            ...(namespace !== undefined ? { namespace } : {}),
+            ...(description !== undefined ? { description } : {}),
+            ...(fields !== undefined
+              ? { fields: fields.map((f) => buildDataField(ids, f as DataFieldInput)) }
+              : {}),
+            ...(resourceId !== undefined
+              ? resourceId === null
+                ? { resourceId: undefined }
+                : { resourceId: asResourceId(resourceId) }
+              : {})
+          };
+          return updateEntity(exp, merged);
+        }
+      })
+  );
+
+  server.registerTool(
+    'remove_entity',
+    {
+      description: 'Delete Entity entity. State paths it documents stay valid elsewhere.',
+      inputSchema: {
+        featureId: z.string(),
+        entityId: z.string()
+      }
+    },
+    async ({ featureId, entityId }) =>
+      runMutation(deps, {
+        featureId: asFeatureId(featureId),
+        transform: (exp) => removeEntity(exp, asEntityId(entityId))
+      })
+  );
+
+  // Mark types referenced for type checker (avoid unused import warning).
+  void dataFieldTypeSchema;
+};