ue-mcp 1.3.5 → 1.3.6

package/dist/flow/guard-schema.d.ts

@@ -0,0 +1,204 @@
+import { z } from "zod";
+/**
+ * What a guard is, declared once and used by both things that can declare one:
+ * a plugin manifest and a project's `ue-mcp.yml`.
+ *
+ * A guard used to be a task whose NAME encoded everything: `guard.sandbox.
+ * beforeWrite` meant a guard called sandbox, running before the call, applying
+ * only to writes. That encoding could not express anything else, so ordering
+ * was unreachable, a guard wanting both hooks had to be two tasks that did not
+ * know they were related, and a misspelling produced an ordinary task nobody
+ * ever called rather than an error.
+ *
+ * The four "phases" were also never four things. They are two hooks and two
+ * scopes, so they are two fields.
+ */
+/**
+ * Which calls a guard sees.
+ *
+ *   all        every call, including reads. For audit and rate limiting.
+ *   mutations  every call that changes editor state, whether or not it names
+ *              an asset. This is what "block everything that mutates" means:
+ *              spawning an actor and starting a play session are in, reads are
+ *              out.
+ *   writes     calls that modify content already on disk. Narrower than
+ *              mutations on purpose: it is the source-control question, and a
+ *              call that creates something new modifies nothing yet.
+ */
+export declare const GuardScopeSchema: z.ZodDefault<z.ZodEnum<["all", "mutations", "writes"]>>;
+/** One hook: the task to run, and the options it is built with. */
+export declare const GuardHookSchema: z.ZodObject<{
+    class_path: z.ZodString;
+    options: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    options: Record<string, unknown>;
+    class_path: string;
+}, {
+    class_path: string;
+    options?: Record<string, unknown> | undefined;
+}>;
+export declare const GuardDeclarationSchema: z.ZodEffects<z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    /**
+     * `writes` costs nothing on a read: the pipeline only resolves which files
+     * a call touches when a guard asks for it.
+     */
+    scope: z.ZodDefault<z.ZodEnum<["all", "mutations", "writes"]>>;
+    /** Lower runs first before the call, and last after it. */
+    order: z.ZodDefault<z.ZodNumber>;
+    /** Runs before the call. Denying here means the call never happens. */
+    before: z.ZodOptional<z.ZodObject<{
+        class_path: z.ZodString;
+        options: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        options: Record<string, unknown>;
+        class_path: string;
+    }, {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    }>>;
+    /** Runs after a successful call, and may replace its result. */
+    after: z.ZodOptional<z.ZodObject<{
+        class_path: z.ZodString;
+        options: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        options: Record<string, unknown>;
+        class_path: string;
+    }, {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    order: number;
+    scope: "all" | "mutations" | "writes";
+    description?: string | undefined;
+    before?: {
+        options: Record<string, unknown>;
+        class_path: string;
+    } | undefined;
+    after?: {
+        options: Record<string, unknown>;
+        class_path: string;
+    } | undefined;
+}, {
+    description?: string | undefined;
+    order?: number | undefined;
+    scope?: "all" | "mutations" | "writes" | undefined;
+    before?: {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    } | undefined;
+    after?: {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    } | undefined;
+}>, {
+    order: number;
+    scope: "all" | "mutations" | "writes";
+    description?: string | undefined;
+    before?: {
+        options: Record<string, unknown>;
+        class_path: string;
+    } | undefined;
+    after?: {
+        options: Record<string, unknown>;
+        class_path: string;
+    } | undefined;
+}, {
+    description?: string | undefined;
+    order?: number | undefined;
+    scope?: "all" | "mutations" | "writes" | undefined;
+    before?: {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    } | undefined;
+    after?: {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    } | undefined;
+}>;
+/** Guards keyed by name. The name is an identifier, not a phase encoding. */
+export declare const GuardsSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    /**
+     * `writes` costs nothing on a read: the pipeline only resolves which files
+     * a call touches when a guard asks for it.
+     */
+    scope: z.ZodDefault<z.ZodEnum<["all", "mutations", "writes"]>>;
+    /** Lower runs first before the call, and last after it. */
+    order: z.ZodDefault<z.ZodNumber>;
+    /** Runs before the call. Denying here means the call never happens. */
+    before: z.ZodOptional<z.ZodObject<{
+        class_path: z.ZodString;
+        options: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        options: Record<string, unknown>;
+        class_path: string;
+    }, {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    }>>;
+    /** Runs after a successful call, and may replace its result. */
+    after: z.ZodOptional<z.ZodObject<{
+        class_path: z.ZodString;
+        options: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        options: Record<string, unknown>;
+        class_path: string;
+    }, {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    order: number;
+    scope: "all" | "mutations" | "writes";
+    description?: string | undefined;
+    before?: {
+        options: Record<string, unknown>;
+        class_path: string;
+    } | undefined;
+    after?: {
+        options: Record<string, unknown>;
+        class_path: string;
+    } | undefined;
+}, {
+    description?: string | undefined;
+    order?: number | undefined;
+    scope?: "all" | "mutations" | "writes" | undefined;
+    before?: {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    } | undefined;
+    after?: {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    } | undefined;
+}>, {
+    order: number;
+    scope: "all" | "mutations" | "writes";
+    description?: string | undefined;
+    before?: {
+        options: Record<string, unknown>;
+        class_path: string;
+    } | undefined;
+    after?: {
+        options: Record<string, unknown>;
+        class_path: string;
+    } | undefined;
+}, {
+    description?: string | undefined;
+    order?: number | undefined;
+    scope?: "all" | "mutations" | "writes" | undefined;
+    before?: {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    } | undefined;
+    after?: {
+        class_path: string;
+        options?: Record<string, unknown> | undefined;
+    } | undefined;
+}>>>;
+export type GuardScope = z.infer<typeof GuardScopeSchema>;
+export type GuardHook = z.infer<typeof GuardHookSchema>;
+export type GuardDeclaration = z.infer<typeof GuardDeclarationSchema>;
+export type GuardDeclarations = z.infer<typeof GuardsSchema>;

package/dist/flow/guard-schema.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+/**
+ * What a guard is, declared once and used by both things that can declare one:
+ * a plugin manifest and a project's `ue-mcp.yml`.
+ *
+ * A guard used to be a task whose NAME encoded everything: `guard.sandbox.
+ * beforeWrite` meant a guard called sandbox, running before the call, applying
+ * only to writes. That encoding could not express anything else, so ordering
+ * was unreachable, a guard wanting both hooks had to be two tasks that did not
+ * know they were related, and a misspelling produced an ordinary task nobody
+ * ever called rather than an error.
+ *
+ * The four "phases" were also never four things. They are two hooks and two
+ * scopes, so they are two fields.
+ */
+/**
+ * Which calls a guard sees.
+ *
+ *   all        every call, including reads. For audit and rate limiting.
+ *   mutations  every call that changes editor state, whether or not it names
+ *              an asset. This is what "block everything that mutates" means:
+ *              spawning an actor and starting a play session are in, reads are
+ *              out.
+ *   writes     calls that modify content already on disk. Narrower than
+ *              mutations on purpose: it is the source-control question, and a
+ *              call that creates something new modifies nothing yet.
+ */
+export const GuardScopeSchema = z.enum(["all", "mutations", "writes"]).default("all");
+/** One hook: the task to run, and the options it is built with. */
+export const GuardHookSchema = z.object({
+    class_path: z.string().min(1, "a guard hook needs the class_path of the task that implements it"),
+    options: z.record(z.unknown()).default({}),
+});
+export const GuardDeclarationSchema = z
+    .object({
+    description: z.string().optional(),
+    /**
+     * `writes` costs nothing on a read: the pipeline only resolves which files
+     * a call touches when a guard asks for it.
+     */
+    scope: GuardScopeSchema,
+    /** Lower runs first before the call, and last after it. */
+    order: z.number().int().default(0),
+    /** Runs before the call. Denying here means the call never happens. */
+    before: GuardHookSchema.optional(),
+    /** Runs after a successful call, and may replace its result. */
+    after: GuardHookSchema.optional(),
+})
+    .refine((g) => g.before !== undefined || g.after !== undefined, {
+    message: "a guard needs a before hook, an after hook, or both. One with neither would be "
+        + "registered, reported, and never run, which is indistinguishable from having no guard.",
+});
+/** Guards keyed by name. The name is an identifier, not a phase encoding. */
+export const GuardsSchema = z
+    .record(z.string().regex(/^[a-z][a-z0-9_-]*$/i, {
+    message: "a guard name must start with a letter and hold only letters, digits, underscores "
+        + "and hyphens",
+}), GuardDeclarationSchema)
+    .default({});
+//# sourceMappingURL=guard-schema.js.map

package/dist/flow/guard-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-schema.js","sourceRoot":"","sources":["../../src/flow/guard-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEtF,mEAAmE;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,kEAAkE,CAAC;IACjG,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC3C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC;KACpC,MAAM,CAAC;IACN,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC;;;OAGG;IACH,KAAK,EAAE,gBAAgB;IACvB,2DAA2D;IAC3D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAClC,uEAAuE;IACvE,MAAM,EAAE,eAAe,CAAC,QAAQ,EAAE;IAClC,gEAAgE;IAChE,KAAK,EAAE,eAAe,CAAC,QAAQ,EAAE;CAClC,CAAC;KACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,EAAE;IAC9D,OAAO,EACL,iFAAiF;UAC/E,uFAAuF;CAC5F,CAAC,CAAC;AAEL,6EAA6E;AAC7E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC;KAC1B,MAAM,CACL,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,EAAE;IACtC,OAAO,EACL,mFAAmF;UACjF,aAAa;CAClB,CAAC,EACF,sBAAsB,CACvB;KACA,OAAO,CAAC,EAAE,CAAC,CAAC"}

package/dist/flow/guard.d.ts

@@ -15,6 +15,7 @@
  */
 import { GuardRegistry as FlowkitGuardRegistry, type Guard, type GuardContext } from "@db-lyon/flowkit/guard";
 import type { IBridge } from "../bridge.js";
+import type { ProjectContext } from "../project.js";
 import type { EditorSession } from "../session.js";
 import { type WriteClassification } from "./write-methods.js";
 /** Resolve a UE content path to an absolute on-disk file, or null if it does not exist. */
@@ -48,5 +49,24 @@ export declare class GuardRegistry extends FlowkitGuardRegistry<CallContext, unk
  * "write" means.
  */
 export declare function writeScope(ctx: CallContext): boolean;
+/**
+ * Every call that changes editor state.
+ *
+ * Wider than `writeScope`, and deliberately so. That one asks which existing
+ * files a call modifies, which is the question a source-control guard has. A
+ * guard told to stand in front of everything that mutates has a different
+ * question: spawning an actor, starting a play session or pressing a dialog
+ * button all change something and name no asset, so they are invisible to the
+ * narrower scope while being exactly what "block every mutation" means.
+ */
+export declare function mutationScope(ctx: CallContext): boolean;
 /** Build the per-call context, wiring the lazy write-enrichment helpers. */
 export declare function makeCallContext(method: string, params: Record<string, unknown>, timeoutMs: number | undefined, rawBridge: IBridge, resolveExistingFile: ResolveExistingFile, session?: EditorSession): CallContext;
+/**
+ * Turn a content path into the file on disk it names, or null.
+ *
+ * This is what lets a guard scoped to writes see which existing files a call
+ * would modify. It is deliberately null-returning rather than throwing: a path
+ * that resolves to nothing is a call that creates something, not an error.
+ */
+export declare function makeResolveExistingFile(project: ProjectContext): ResolveExistingFile;

package/dist/flow/guard.js

@@ -14,6 +14,7 @@
  * is about to modify.
  */
 import { GuardRegistry as FlowkitGuardRegistry, guardContextBase, lazy, } from "@db-lyon/flowkit/guard";
+import * as fs from "node:fs";
 import { classifyWrite } from "./write-methods.js";
 /** The bridge's guard set. Built-in guards register directly; plugin guards are discovered. */
 export class GuardRegistry extends FlowkitGuardRegistry {
@@ -27,6 +28,19 @@ export class GuardRegistry extends FlowkitGuardRegistry {
 export function writeScope(ctx) {
     return ctx.writeFiles().length > 0;
 }
+/**
+ * Every call that changes editor state.
+ *
+ * Wider than `writeScope`, and deliberately so. That one asks which existing
+ * files a call modifies, which is the question a source-control guard has. A
+ * guard told to stand in front of everything that mutates has a different
+ * question: spawning an actor, starting a play session or pressing a dialog
+ * button all change something and name no asset, so they are invisible to the
+ * narrower scope while being exactly what "block every mutation" means.
+ */
+export function mutationScope(ctx) {
+    return ctx.write().mutates;
+}
 /** Build the per-call context, wiring the lazy write-enrichment helpers. */
 export function makeCallContext(method, params, timeoutMs, rawBridge, resolveExistingFile, session) {
     const ctx = {
@@ -46,4 +60,22 @@ export function makeCallContext(method, params, timeoutMs, rawBridge, resolveExi
     });
     return Object.assign(ctx, { write, writeFiles });
 }
+/**
+ * Turn a content path into the file on disk it names, or null.
+ *
+ * This is what lets a guard scoped to writes see which existing files a call
+ * would modify. It is deliberately null-returning rather than throwing: a path
+ * that resolves to nothing is a call that creates something, not an error.
+ */
+export function makeResolveExistingFile(project) {
+    return (contentPath) => {
+        try {
+            const abs = project.resolveContentPath(contentPath);
+            return fs.existsSync(abs) ? abs : null;
+        }
+        catch {
+            return null;
+        }
+    };
+}
 //# sourceMappingURL=guard.js.map

package/dist/flow/guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../src/flow/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,aAAa,IAAI,oBAAoB,EACrC,gBAAgB,EAChB,IAAI,GAGL,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,aAAa,EAA4B,MAAM,oBAAoB,CAAC;AA0B7E,+FAA+F;AAC/F,MAAM,OAAO,aAAc,SAAQ,oBAA0C;CAAG;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAgB;IACzC,OAAO,GAAG,CAAC,UAAU,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AACrC,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,MAA+B,EAC/B,SAA6B,EAC7B,SAAkB,EAClB,mBAAwC,EACxC,OAAuB;IAEvB,MAAM,GAAG,GAAG;QACV,GAAG,gBAAgB,EAAE;QACrB,MAAM;QACN,MAAM;QACN,SAAS;QACT,MAAM,EAAE,SAAS;QACjB,OAAO;KACO,CAAC;IAEjB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtE,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,GAAG,KAAK,EAAE,CAAC;QAClB,OAAO,CAAC,CAAC,MAAM;YACb,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;YAChF,CAAC,CAAC,EAAE,CAAC;IACT,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;AACnD,CAAC"}
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../src/flow/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,aAAa,IAAI,oBAAoB,EACrC,gBAAgB,EAChB,IAAI,GAGL,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAI9B,OAAO,EAAE,aAAa,EAA4B,MAAM,oBAAoB,CAAC;AA0B7E,+FAA+F;AAC/F,MAAM,OAAO,aAAc,SAAQ,oBAA0C;CAAG;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAgB;IACzC,OAAO,GAAG,CAAC,UAAU,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,OAAO,GAAG,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC;AAC7B,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,MAA+B,EAC/B,SAA6B,EAC7B,SAAkB,EAClB,mBAAwC,EACxC,OAAuB;IAEvB,MAAM,GAAG,GAAG;QACV,GAAG,gBAAgB,EAAE;QACrB,MAAM;QACN,MAAM;QACN,SAAS;QACT,MAAM,EAAE,SAAS;QACjB,OAAO;KACO,CAAC;IAEjB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtE,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,GAAG,KAAK,EAAE,CAAC;QAClB,OAAO,CAAC,CAAC,MAAM;YACb,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;YAChF,CAAC,CAAC,EAAE,CAAC;IACT,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAuB;IAC7D,OAAO,CAAC,WAAmB,EAAiB,EAAE;QAC5C,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,OAAO,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC;YACpD,OAAO,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/flow/guards.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Building guards from what somebody declared.
+ *
+ * A guard is a first-class thing here, not a task that happens to be named a
+ * certain way. Two sources declare them in the same shape, a plugin manifest
+ * and a project's `ue-mcp.yml`, and both arrive here as `GuardDeclaration`
+ * records that are turned into pipeline guards directly.
+ *
+ * A guard is IMPLEMENTED BY a task, named by `class_path`, but it is not one.
+ * The task registry holds tasks; this holds guards; a name collision between
+ * the two is now impossible rather than load-bearing.
+ */
+import type { TaskRegistry } from "@db-lyon/flowkit";
+import type { IBridge } from "../bridge.js";
+import type { ToolContext } from "../types.js";
+import { type BridgeGuard } from "./guard.js";
+import type { GuardDeclarations } from "./guard-schema.js";
+/** Where a declaration came from, so an error can say which file to open. */
+export interface GuardSource {
+    /** `ue-mcp.yml`, or a plugin's name. */
+    readonly label: string;
+}
+export interface BuildGuardsDeps {
+    registry: TaskRegistry;
+    ctx: ToolContext;
+    /**
+     * The bridge a guard's own calls go out on when no session is attached.
+     *
+     * Raw on purpose: a guard that calls the editor must not re-enter the flow
+     * pipeline that is running it. That is a statement about the registry and
+     * not about dialogs, so the per-session path below still puts the dialog
+     * gate back, with no pipeline attached.
+     */
+    rawBridge: IBridge;
+}
+/**
+ * Turn declarations into pipeline guards.
+ *
+ * Every guard is one object with the hooks it declared, so a guard wanting
+ * both sides is one guard that knows it is one, and ordering is a number
+ * rather than something the name could not say.
+ */
+export declare function buildGuards(declarations: GuardDeclarations, deps: BuildGuardsDeps, source: GuardSource): Promise<BridgeGuard[]>;
+/**
+ * Refuse to start when a task is still named like a guard.
+ *
+ * Before guards were declared, a task with this name WAS a guard. Under the
+ * declaration model nothing discovers it, so it becomes an ordinary task
+ * nobody calls: a source-control write guard would keep appearing in the
+ * config and stop gating anything, silently.
+ *
+ * That is the exact failure the declaration model exists to prevent, so the
+ * migration must not reintroduce it. A leftover name is fatal and says what to
+ * write instead.
+ */
+export declare function assertNoLegacyGuardTasks(taskNames: string[], source: GuardSource): void;

package/dist/flow/guards.js

@@ -0,0 +1,175 @@
+import { mutationScope, writeScope } from "./guard.js";
+import { withoutDialogActuation } from "../dialog-guard.js";
+import { DialogGatedBridge } from "./guarded-bridge.js";
+import { McpError, ErrorCode } from "../errors.js";
+import { debug } from "../log.js";
+/**
+ * The context a hook task runs in.
+ *
+ * Bound to the editor whose call is being guarded rather than to whichever
+ * bridge was built first, so a guard can neither recurse through the pipeline
+ * nor act on another project's editor. `withoutDialogActuation` sits on top
+ * because arming a dialog policy is served during a modal, so a guard could
+ * otherwise answer the dialog already on screen.
+ */
+function hookContext(cc, deps) {
+    if (!cc.session)
+        return { ...deps.ctx, bridge: deps.rawBridge };
+    return {
+        ...deps.ctx,
+        bridge: withoutDialogActuation(cc.session, new DialogGatedBridge(cc.bridge, cc.session)),
+        project: cc.session.project,
+        session: cc.session,
+    };
+}
+/** What a hook is told about the call it is guarding. */
+function hookOptions(cc, declared, result) {
+    return {
+        // The declaration first, so the call being guarded always wins a
+        // collision: a guard reads its configuration and its subject from one
+        // object, and the subject is never masked by a stale default.
+        ...declared,
+        method: cc.method,
+        params: cc.params,
+        paths: cc.writeFiles(),
+        ...(result !== undefined ? { result } : {}),
+    };
+}
+/** Run one hook and give back what it answered. */
+async function runHook(hook, cc, deps, result) {
+    const task = await deps.registry.create(hook.class_path, hookContext(cc, deps), hookOptions(cc, hook.options, result));
+    return (await task.execute());
+}
+/** The message a denial carries, from wherever the hook put it. */
+function refusalReason(r) {
+    return r.error?.message ?? r.message ?? "no reason given";
+}
+/**
+ * Resolve every declared hook up front.
+ *
+ * A `class_path` that cannot be resolved is fatal at build time, not at the
+ * moment a guarded call arrives. A guard that cannot be constructed would
+ * leave the calls it names ungated while the configuration says otherwise,
+ * which is the one failure this whole mechanism exists to prevent.
+ */
+async function assertResolvable(name, which, hook, deps, source) {
+    try {
+        await deps.registry.resolve(hook.class_path);
+    }
+    catch (e) {
+        const why = e instanceof Error ? e.message : String(e);
+        throw new Error(`${source.label} declares guard '${name}' with a ${which} hook whose class_path `
+            + `'${hook.class_path}' could not be resolved: ${why}. A guard that cannot be built would `
+            + "leave the calls it covers ungated while the configuration says they are guarded, so the "
+            + "server stops here rather than starting without it.");
+    }
+}
+/**
+ * Turn declarations into pipeline guards.
+ *
+ * Every guard is one object with the hooks it declared, so a guard wanting
+ * both sides is one guard that knows it is one, and ordering is a number
+ * rather than something the name could not say.
+ */
+export async function buildGuards(declarations, deps, source) {
+    const guards = [];
+    for (const [name, decl] of Object.entries(declarations)) {
+        if (decl.before)
+            await assertResolvable(name, "before", decl.before, deps, source);
+        if (decl.after)
+            await assertResolvable(name, "after", decl.after, deps, source);
+        const guard = {
+            name,
+            order: decl.order,
+            // Both narrower scopes are lazy: a guard that does not ask pays nothing,
+            // and a pipeline of guards that all ask pays once.
+            ...(decl.scope === "writes" ? { appliesTo: (cc) => writeScope(cc) } : {}),
+            ...(decl.scope === "mutations" ? { appliesTo: (cc) => mutationScope(cc) } : {}),
+            ...(decl.before
+                ? {
+                    before: async (cc) => {
+                        let answered;
+                        try {
+                            answered = await runHook(decl.before, cc, deps);
+                        }
+                        catch (e) {
+                            // A hook that threw denies the call. It is the same outcome as
+                            // returning failure, and a guard that errors is not a guard
+                            // that approved.
+                            const why = e instanceof Error ? e.message : String(e);
+                            throw new McpError(ErrorCode.WRITE_BLOCKED, `guard '${name}' errored on ${cc.method}: ${why}`);
+                        }
+                        if (answered?.success === false) {
+                            const files = cc.writeFiles();
+                            const on = files.length > 0 ? ` on ${files.join(", ")}` : "";
+                            throw new McpError(ErrorCode.WRITE_BLOCKED, `blocked (${cc.method})${on}: ${refusalReason(answered)}`);
+                        }
+                    },
+                }
+                : {}),
+            ...(decl.after
+                ? {
+                    after: async (cc, result) => {
+                        let answered;
+                        try {
+                            answered = await runHook(decl.after, cc, deps, result);
+                        }
+                        catch (e) {
+                            // The call already happened. Failing it now would report a
+                            // mutation as not having occurred, which is worse than an
+                            // audit hook that did not run.
+                            const why = e instanceof Error ? e.message : String(e);
+                            debug("guard", `after hook of '${name}' errored on ${cc.method}: ${why}`);
+                            return undefined;
+                        }
+                        if (answered?.success === false) {
+                            debug("guard", `after hook of '${name}' reported failure on ${cc.method}: ${refusalReason(answered)}`);
+                            return undefined;
+                        }
+                        // Returning data replaces the result; returning nothing leaves it.
+                        return answered?.data;
+                    },
+                }
+                : {}),
+        };
+        guards.push(guard);
+    }
+    return guards;
+}
+/** The dead naming convention: a task called `guard.<name>.<phase>`. */
+const LEGACY_GUARD_TASK = /^guard\.[^.]+\.(before|after)[A-Za-z0-9]*$/;
+/**
+ * Refuse to start when a task is still named like a guard.
+ *
+ * Before guards were declared, a task with this name WAS a guard. Under the
+ * declaration model nothing discovers it, so it becomes an ordinary task
+ * nobody calls: a source-control write guard would keep appearing in the
+ * config and stop gating anything, silently.
+ *
+ * That is the exact failure the declaration model exists to prevent, so the
+ * migration must not reintroduce it. A leftover name is fatal and says what to
+ * write instead.
+ */
+export function assertNoLegacyGuardTasks(taskNames, source) {
+    const legacy = taskNames.filter((n) => LEGACY_GUARD_TASK.test(n));
+    if (legacy.length === 0)
+        return;
+    const examples = legacy.slice(0, 3).map((name) => {
+        const [, guardName, phase] = /^guard\.([^.]+)\.(.+)$/.exec(name);
+        const scope = /Write$/.test(phase) ? "writes" : "all";
+        const hook = phase.startsWith("after") ? "after" : "before";
+        return (`  ${name}\n`
+            + "    becomes:\n"
+            + "      guards:\n"
+            + `        ${guardName}:\n`
+            + `          scope: ${scope}\n`
+            + `          ${hook}:\n`
+            + "            class_path: <the class_path that task had>");
+    });
+    throw new Error(`${source.label} declares ${legacy.length} task(s) named like a guard, which no longer makes `
+        + "them one. A guard is declared in a `guards:` section now, so these are ordinary tasks that "
+        + "nothing calls: whatever they were gating is ungated while the config still says it is "
+        + `guarded.\n\n${examples.join("\n\n")}\n\n`
+        + "See the guards documentation for the full shape, including order and the after hook.");
+}
+//# sourceMappingURL=guards.js.map

package/dist/flow/guards.js.map

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

package/dist/flow/loader.js

@@ -319,6 +319,19 @@ function defaultFlows() {
     // asset domain is a real one (/Game/VFX/Fire); override name/packagePath via
     // runtime params. The last step is the verify gate - the run surfaces whether
     // the system actually emits, catching the empty-shell failure.
+    //
+    // WHAT A GOOD FIRE ACTUALLY IS, from reading a production reference system:
+    // layered emitters, not one. A convincing fire is roughly four:
+    //   - two flame emitters on sprite renderers, doubled for depth
+    //   - a light emitter, so the fire lights its surroundings
+    //   - a heat-distortion emitter
+    // Colour and size are curve-driven over particle age rather than constant,
+    // which is what stops it reading as a flat billboard. Every module involved is
+    // a stock engine script under /Niagara/Modules/.
+    //
+    // This flow builds ONE emitter, which is the honest 0-to-1 starting point and
+    // not the finished look. Extending it toward the shape above is the obvious
+    // next move, and the reason that shape is written down here.
     const FIRE_PKG = "/Game/VFX/Fire";
     const fireSteps = {
         1: { task: "niagara.create_emitter", options: { name: "E_Flame", packagePath: FIRE_PKG } },