@nwire/please 0.7.1 → 0.8.0

package/README.md

@@ -1,38 +1,78 @@
 # @nwire/please
 
-> Operator CLI — dispatch any registered action or query from the command line.
+> Operator CLI — dispatch any registered action or query (and operator-script commands) from the command line.
 
-## What it does
-
-Looks at every app's registered actions and queries and exposes them as CLI commands. `please submissions.flag-for-review --submissionId xyz` walks the apps registry, finds the owning app, seeds an envelope, dispatches, prints the result. Same handlers as HTTP/queue — operator parity guaranteed.
-
-## Install
+`runPlease({ apps, commands, argv })` boots every registered app, looks
+up the named target in the supplied `commands` first (operator scripts
+take precedence) then in each app's action/query surface, seeds an
+envelope, dispatches, prints the result. Same handlers as HTTP/queue —
+operator parity guaranteed.
 
 ```bash
 pnpm add @nwire/please
 ```
 
-## Quick start
+## Quick example
 
 ```ts
 #!/usr/bin/env node
-import { runPlease } from "@nwire/please";
+import { runPlease, defineCommand } from "@nwire/please";
+import { z } from "zod";
 import { apps } from "../app/apps";
 
-runPlease({ apps, argv: process.argv.slice(2) }).then((code) => process.exit(code));
+const backfillUsers = defineCommand("backfill-users", {
+  describe: "Re-hydrate users from the external source",
+  args: z.object({ since: z.string().optional() }),
+  handler: async ({ args, ctx }) => {
+    const repo = ctx.resolve<UserRepo>("UserRepo");
+    return { updated: await repo.backfill(args) };
+  },
+});
+
+const code = await runPlease({
+  apps,
+  commands: [backfillUsers],
+  argv: process.argv.slice(2),
+});
+process.exit(code);
 ```
 
 ```bash
+please backfill-users --since 2026-01-01    # operator script (takes precedence)
 please submissions.flag-for-review --submissionId xyz --confidence 0.4
 please lessons.start-attempt --lessonId hebrew-1 --studentId avi
 please submissions.by-student --studentId avi --status under-review
 please --help
 ```
 
-## API surface
+## Surface
+
+| Export                                     | Role                                                        |
+| ------------------------------------------ | ----------------------------------------------------------- |
+| `runPlease({ apps, commands?, argv, … })`  | Boot apps, dispatch one target, return exit code (0 / 1).   |
+| `defineCommand(name, meta)`                | Operator-script primitive. `{ describe?, args?, handler }`. |
+| `CommandDefinition` / `CommandContext` / `CommandHandler` / `CommandMeta` / `CommandArgsSchema` | Types for command authors and consumers. |
+
+### Resolution order
+
+`runPlease` resolves `argv[0]` in this order:
+
+1. `commands[]` — operator scripts shadow domain names on purpose.
+2. Any app's action surface.
+3. Any app's query surface (projection-backed reads).
+
+Args parsers are duck-typed — any object with `.parse(input) → output`
+works, so a `z.object({...})` schema is the obvious choice.
+
+`defineCommand` captures `$source` so Studio's Commands page can
+render IDE-link chips.
+
+## Related
 
-- `runPlease({ apps, appInstances?, argv, stdout?, stderr? })` — returns exit code.
+- `@nwire/forge` — supplies the `App` / `AppDefinition` / `HandlerContext` types `runPlease` and `defineCommand` build on.
+- `@nwire/cli` — `nwire please <name>` delegates to this package.
+- `@nwire/scan` — emits `.nwire/commands.json` so Studio + AI surfaces see every operator script.
 
-## When to use
+## Status
 
-Operations work — re-run a stuck workflow, query a projection, kick a one-off action — without writing a script or shelling into a worker.
+v0.x — `runPlease` argv contract + `defineCommand` shape are locked. Scaffolders (`make:module`, `make:action`) land on top in a follow-up.

package/dist/__tests__/define-command.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `defineCommand` — operator-script primitive.
+ *
+ * Verifies the primitive shape, source capture, optional args, and that
+ * commands plumb through `runPlease` to invoke the handler with an injected
+ * resolver + app instance.
+ */
+export {};
+//# sourceMappingURL=define-command.test.d.ts.map

package/dist/__tests__/define-command.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-command.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/define-command.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/__tests__/define-command.test.js

@@ -0,0 +1,93 @@
+/**
+ * `defineCommand` — operator-script primitive.
+ *
+ * Verifies the primitive shape, source capture, optional args, and that
+ * commands plumb through `runPlease` to invoke the handler with an injected
+ * resolver + app instance.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineModule, createApp } from "@nwire/forge";
+import { defineCommand, runPlease } from "../please.js";
+describe("defineCommand", () => {
+    it("returns a $kind=command definition with source location", () => {
+        const cmd = defineCommand("seed-students", {
+            describe: "Seed Dina's starter classroom roster.",
+            args: z.object({ count: z.number().int().positive() }),
+            handler: async ({ args }) => ({ created: args.count }),
+        });
+        expect(cmd.$kind).toBe("command");
+        expect(cmd.name).toBe("seed-students");
+        expect(cmd.describe).toContain("Dina");
+        expect(cmd.args).toBeDefined();
+        // captureSourceLocation populates $source from the call site. The
+        // helper skips nwire-internal frames (including this test file, which
+        // lives under packages/nwire-please), so $source resolves to the next
+        // user-code frame the V8 stack exposes — what matters is that it ran.
+        expect(cmd.$source).toBeDefined();
+        expect(typeof cmd.$source?.line).toBe("number");
+    });
+    it("accepts a command with no args schema (optional field)", () => {
+        const cmd = defineCommand("ping", {
+            describe: "Smoke-test that the wire is up.",
+            handler: async () => ({ ok: true }),
+        });
+        expect(cmd.args).toBeUndefined();
+        expect(cmd.describe).toBe("Smoke-test that the wire is up.");
+    });
+    it("invokes the handler via runPlease with parsed args + ctx.resolve", async () => {
+        let captured = null;
+        const emptyModule = defineModule("ops", {});
+        const app = createApp({ modules: [emptyModule], appName: "ops-app" });
+        app.container.register("Reporter", () => ({ report: () => "reported" }));
+        const cmd = defineCommand("backfill-users", {
+            describe: "Re-hydrate users.",
+            args: z.object({ since: z.string().optional() }),
+            handler: async ({ args, ctx }) => {
+                captured = {
+                    args,
+                    resolved: ctx.resolve("Reporter").report(),
+                    appKind: ctx.app.$nwireApp,
+                };
+                return { ok: true };
+            },
+        });
+        const stdout = [];
+        const stderr = [];
+        const code = await runPlease({
+            apps: [],
+            appInstances: [app],
+            argv: ["backfill-users", "--since", "2026-01-01"],
+            commands: [cmd],
+            stdout: (l) => stdout.push(l),
+            stderr: (l) => stderr.push(l),
+        });
+        expect(code).toBe(0);
+        expect(stderr).toEqual([]);
+        expect(captured).not.toBeNull();
+        expect(captured.args).toEqual({ since: "2026-01-01" });
+        expect(captured.resolved).toBe("reported");
+        expect(captured.appKind).toBe(true);
+        expect(stdout.join("\n")).toContain('"ok": true');
+    });
+    it("surfaces zod validation errors with a non-zero exit code", async () => {
+        const emptyModule = defineModule("ops", {});
+        const app = createApp({ modules: [emptyModule], appName: "ops-app" });
+        const cmd = defineCommand("require-id", {
+            args: z.object({ id: z.string() }),
+            handler: async () => "never",
+        });
+        const stderr = [];
+        const code = await runPlease({
+            apps: [],
+            appInstances: [app],
+            argv: ["require-id"],
+            commands: [cmd],
+            stdout: () => { },
+            stderr: (l) => stderr.push(l),
+        });
+        expect(code).toBe(1);
+        expect(stderr.join("\n")).toMatch(/invalid args for "require-id"/);
+    });
+});
+//# sourceMappingURL=define-command.test.js.map

package/dist/__tests__/define-command.test.js.map

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

package/dist/__tests__/run-please.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `runPlease` — operator CLI dispatcher.
+ *
+ * Covers command-vs-action precedence so domain-action surface stays clean
+ * and operator scripts run via the same `please <name>` UX.
+ */
+export {};
+//# sourceMappingURL=run-please.test.d.ts.map

package/dist/__tests__/run-please.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-please.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/run-please.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/__tests__/run-please.test.js

@@ -0,0 +1,118 @@
+/**
+ * `runPlease` — operator CLI dispatcher.
+ *
+ * Covers command-vs-action precedence so domain-action surface stays clean
+ * and operator scripts run via the same `please <name>` UX.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineAction, defineModule, createApp } from "@nwire/forge";
+import { defineCommand, runPlease } from "../please.js";
+describe("runPlease command dispatch", () => {
+    it("dispatches a registered command by name (precedence over actions)", async () => {
+        let actionRan = false;
+        let commandRan = false;
+        // Domain action sharing the same name as the operator command.
+        const ping = defineAction({
+            name: "ping",
+            description: "Domain ping action — should NOT run when shadowed.",
+            schema: z.object({}),
+            handler: async () => {
+                actionRan = true;
+                return undefined;
+            },
+        });
+        const opsModule = defineModule("ops", { actions: [ping] });
+        const app = createApp({ modules: [opsModule], appName: "ops-app" });
+        const pingCommand = defineCommand("ping", {
+            describe: "Operator ping — shadows the domain action.",
+            handler: async () => {
+                commandRan = true;
+                return { from: "command" };
+            },
+        });
+        const stdout = [];
+        const code = await runPlease({
+            apps: [],
+            appInstances: [app],
+            argv: ["ping"],
+            commands: [pingCommand],
+            stdout: (l) => stdout.push(l),
+            stderr: () => { },
+        });
+        expect(code).toBe(0);
+        expect(commandRan).toBe(true);
+        expect(actionRan).toBe(false);
+        expect(stdout.join("\n")).toContain('"from": "command"');
+    });
+    it("falls back to the action surface when no command matches the name", async () => {
+        let actionInput = null;
+        const flagSubmission = defineAction({
+            name: "submissions.flag",
+            description: "Flag Avi's submission for review.",
+            schema: z.object({ submissionId: z.string() }),
+            handler: async (input) => {
+                actionInput = input;
+                return undefined;
+            },
+        });
+        const submissionsModule = defineModule("submissions", { actions: [flagSubmission] });
+        const app = createApp({ modules: [submissionsModule], appName: "ops-app" });
+        const backfill = defineCommand("backfill-users", {
+            handler: async () => "noop",
+        });
+        const stdout = [];
+        const stderr = [];
+        const code = await runPlease({
+            apps: [],
+            appInstances: [app],
+            argv: ["submissions.flag", "--submissionId", "sub-1"],
+            commands: [backfill],
+            stdout: (l) => stdout.push(l),
+            stderr: (l) => stderr.push(l),
+        });
+        expect(code).toBe(0);
+        expect(stderr).toEqual([]);
+        expect(actionInput).toEqual({ submissionId: "sub-1" });
+        expect(stdout.join("\n")).toContain("OK");
+    });
+    it("reports unknown name when neither a command nor an action matches", async () => {
+        const emptyModule = defineModule("ops", {});
+        const app = createApp({ modules: [emptyModule], appName: "ops-app" });
+        const stderr = [];
+        const code = await runPlease({
+            apps: [],
+            appInstances: [app],
+            argv: ["nope"],
+            commands: [],
+            stdout: () => { },
+            stderr: (l) => stderr.push(l),
+        });
+        expect(code).toBe(1);
+        expect(stderr.join("\n")).toMatch(/unknown command, action, or query: "nope"/);
+    });
+    it("lists commands in --help output alongside actions", async () => {
+        const emptyModule = defineModule("ops", {});
+        const app = createApp({ modules: [emptyModule], appName: "ops-app" });
+        const stdout = [];
+        const code = await runPlease({
+            apps: [],
+            appInstances: [app],
+            argv: ["--help"],
+            commands: [
+                defineCommand("seed-classroom", {
+                    describe: "Seed Dina's starter classroom.",
+                    handler: async () => undefined,
+                }),
+            ],
+            stdout: (l) => stdout.push(l),
+            stderr: () => { },
+        });
+        expect(code).toBe(0);
+        const out = stdout.join("\n");
+        expect(out).toContain("# Commands (operator scripts)");
+        expect(out).toContain("seed-classroom");
+        expect(out).toContain("Seed Dina's starter classroom.");
+    });
+});
+//# sourceMappingURL=run-please.test.js.map

package/dist/__tests__/run-please.test.js.map

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

package/dist/define-command.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `defineCommand` — operator-script primitive.
+ *
+ * Peer to `defineAction` / `defineQuery`, but lives at the *operator* layer:
+ * one-off scripts the team runs from the CLI (backfills, replays, seed loaders,
+ * data fixers). They don't belong on the domain action surface — they're not
+ * intent the system processes through its event-sourced spine, they're
+ * imperative jobs the operator triggers by hand.
+ *
+ *   export const backfillUsers = defineCommand("backfill-users", {
+ *     describe: "Re-hydrate users from external source",
+ *     args: z.object({ since: z.string().optional() }),
+ *     handler: async ({ args, ctx }) => {
+ *       const repo = ctx.resolve("UserRepo")
+ *       return { updated: await repo.backfill(args) }
+ *     },
+ *   })
+ *
+ * Wire commands by listing them on `runPlease({ apps, commands, argv })`.
+ * `runPlease` looks up the named arg in the commands array FIRST, then falls
+ * back to the action/query surface. This keeps the action graph clean and
+ * pushes ops scripts to the layer they belong on.
+ */
+import type * as forge from "@nwire/forge";
+import type { SourceLocation } from "@nwire/messages";
+/**
+ * Minimal zod-like schema contract — anything with `.parse(input) → output`.
+ * Lets `defineCommand` accept a real `z.object({...})` schema, a plain `{}`
+ * marker (treated as "no args"), or any other parser-shaped object without
+ * coupling `@nwire/please` to zod's runtime.
+ */
+export interface CommandArgsSchema<TOut = any> {
+    parse(input: unknown): TOut;
+}
+/**
+ * Context passed to a command's handler. Intentionally minimal — mirrors the
+ * `ctx.resolve` shape from forge's `HandlerContext` plus the booted `App`
+ * instance so operator scripts can `app.runtime.dispatch(...)` an action,
+ * `app.runtime.query(...)` a projection, or pull any DI'd dependency by name.
+ */
+export interface CommandContext {
+    /** Look up a dependency by name (container.resolve shortcut). */
+    resolve<T = unknown>(name: string): T;
+    /** The booted app the command was dispatched against. */
+    readonly app: forge.App;
+}
+export interface CommandHandlerArgs<TArgs> {
+    readonly args: TArgs;
+    readonly ctx: CommandContext;
+}
+export type CommandHandler<TArgs> = (args: CommandHandlerArgs<TArgs>) => Promise<unknown> | unknown;
+export interface CommandMeta<TSchema extends CommandArgsSchema | undefined> {
+    /** Short, human-readable summary printed by `please --help`. */
+    readonly describe?: string;
+    /**
+     * Args parser. Pass a zod schema (`z.object({...})`) for typed/validated
+     * input, or a plain object marker (`{}`) when the command takes no args.
+     * Anything with a `.parse(input) → output` method is accepted.
+     */
+    readonly args?: TSchema;
+    /** Handler executed when the operator runs `please <name>`. */
+    readonly handler: CommandHandler<TSchema extends CommandArgsSchema<infer T> ? T : Record<string, unknown>>;
+}
+export interface CommandDefinition<TSchema extends CommandArgsSchema | undefined = CommandArgsSchema | undefined> {
+    readonly $kind: "command";
+    readonly name: string;
+    readonly describe?: string;
+    readonly args?: TSchema;
+    readonly handler: CommandHandler<TSchema extends CommandArgsSchema<infer T> ? T : Record<string, unknown>>;
+    /** Where the command was declared. Studio/Hooks page uses this for IDE links. */
+    readonly $source?: SourceLocation;
+}
+export declare function defineCommand<TSchema extends CommandArgsSchema | undefined = undefined>(name: string, meta: CommandMeta<TSchema>): CommandDefinition<TSchema>;
+//# sourceMappingURL=define-command.d.ts.map

package/dist/define-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-command.d.ts","sourceRoot":"","sources":["../src/define-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGtD;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB,CAAC,IAAI,GAAG,GAAG;IAC3C,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;IACtC,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB,CAAC,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;CAC9B;AAED,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI,CAElC,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,KAC5B,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAEhC,MAAM,WAAW,WAAW,CAAC,OAAO,SAAS,iBAAiB,GAAG,SAAS;IACxE,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,cAAc,CAC9B,OAAO,SAAS,iBAAiB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACzE,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB,CAChC,OAAO,SAAS,iBAAiB,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS;IAE7E,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAC9B,OAAO,SAAS,iBAAiB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACzE,CAAC;IACF,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CACnC;AAED,wBAAgB,aAAa,CAAC,OAAO,SAAS,iBAAiB,GAAG,SAAS,GAAG,SAAS,EACrF,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,GACzB,iBAAiB,CAAC,OAAO,CAAC,CAU5B"}

package/dist/define-command.js

@@ -0,0 +1,36 @@
+/**
+ * `defineCommand` — operator-script primitive.
+ *
+ * Peer to `defineAction` / `defineQuery`, but lives at the *operator* layer:
+ * one-off scripts the team runs from the CLI (backfills, replays, seed loaders,
+ * data fixers). They don't belong on the domain action surface — they're not
+ * intent the system processes through its event-sourced spine, they're
+ * imperative jobs the operator triggers by hand.
+ *
+ *   export const backfillUsers = defineCommand("backfill-users", {
+ *     describe: "Re-hydrate users from external source",
+ *     args: z.object({ since: z.string().optional() }),
+ *     handler: async ({ args, ctx }) => {
+ *       const repo = ctx.resolve("UserRepo")
+ *       return { updated: await repo.backfill(args) }
+ *     },
+ *   })
+ *
+ * Wire commands by listing them on `runPlease({ apps, commands, argv })`.
+ * `runPlease` looks up the named arg in the commands array FIRST, then falls
+ * back to the action/query surface. This keeps the action graph clean and
+ * pushes ops scripts to the layer they belong on.
+ */
+import { captureSourceLocation } from "@nwire/messages";
+export function defineCommand(name, meta) {
+    const $source = captureSourceLocation();
+    return {
+        $kind: "command",
+        name,
+        describe: meta.describe,
+        args: meta.args,
+        handler: meta.handler,
+        $source,
+    };
+}
+//# sourceMappingURL=define-command.js.map

package/dist/define-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-command.js","sourceRoot":"","sources":["../src/define-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiExD,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,IAA0B;IAE1B,MAAM,OAAO,GAAG,qBAAqB,EAAE,CAAC;IACxC,OAAO;QACL,KAAK,EAAE,SAAS;QAChB,IAAI;QACJ,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@nwire/please` — barrel entry. Mirrors the surface of `./please.ts` so
+ * consumers can import from `@nwire/please` regardless of which entry the
+ * bundler / package.json resolves.
+ */
+export * from "./please.js";
+export * from "./define-command.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * `@nwire/please` — barrel entry. Mirrors the surface of `./please.ts` so
+ * consumers can import from `@nwire/please` regardless of which entry the
+ * bundler / package.json resolves.
+ */
+export * from "./please.js";
+export * from "./define-command.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC"}

package/dist/please.d.ts

@@ -17,6 +17,7 @@
  * follow-up phase — the CLI runner is the primitive, scaffolders compose on top.
  */
 import * as forge from "@nwire/forge";
+import type { CommandDefinition } from "./define-command.js";
 export interface RunPleaseOptions {
     /** Apps to expose. The CLI dispatches against any action/query in any of these. */
     readonly apps: readonly forge.AppDefinition[];
@@ -30,10 +31,18 @@ export interface RunPleaseOptions {
     readonly stderr?: (line: string) => void;
     /** Hook for store/logger overrides at instantiation time. */
     readonly createOverrides?: (appDef: forge.AppDefinition) => Omit<forge.CreateAppOptions, "modules">;
+    /**
+     * Operator-script commands (`defineCommand`). Dispatched by name with
+     * precedence over actions/queries — so a backfill script can shadow a
+     * domain action name on purpose, and ops scripts never leak into the
+     * action surface.
+     */
+    readonly commands?: readonly CommandDefinition[];
 }
 /**
  * Boot every registered app, run the dispatched action/query against the
  * matching app, return the exit code (0 on success, 1 on error).
  */
 export declare function runPlease(options: RunPleaseOptions): Promise<number>;
+export { defineCommand, type CommandArgsSchema, type CommandContext, type CommandDefinition, type CommandHandler, type CommandHandlerArgs, type CommandMeta, } from "./define-command.js";
 //# sourceMappingURL=please.d.ts.map

package/dist/please.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"please.d.ts","sourceRoot":"","sources":["../src/please.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,SAAS,KAAK,CAAC,aAAa,EAAE,CAAC;IAC9C,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,KAAK,CAAC,GAAG,EAAE,CAAC;IAC7C,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,MAAM,EAAE,KAAK,CAAC,aAAa,KACxB,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B1E"}
+{"version":3,"file":"please.d.ts","sourceRoot":"","sources":["../src/please.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,SAAS,KAAK,CAAC,aAAa,EAAE,CAAC;IAC9C,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,KAAK,CAAC,GAAG,EAAE,CAAC;IAC7C,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,MAAM,EAAE,KAAK,CAAC,aAAa,KACxB,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAClD;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2C1E;AA8ID,OAAO,EACL,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC"}

package/dist/please.js

@@ -31,18 +31,121 @@ export async function runPlease(options) {
     const argv = options.argv;
     const stdout = options.stdout;
     const stderr = options.stderr;
+    const commands = options.commands ?? [];
     if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
-        printAllHelp(instances, options.stdout ?? ((l) => console.log(l)));
+        printAllHelp(instances, commands, options.stdout ?? ((l) => console.log(l)));
         return 0;
     }
     const targetName = argv[0];
+    // Commands take precedence: operator scripts shadow the action surface so a
+    // backfill named "submissions.flag" never collides with the domain action of
+    // the same name. The first registered command wins on duplicates.
+    const command = commands.find((c) => c.name === targetName);
+    if (command) {
+        return runCommand(command, instances, argv.slice(1), {
+            stdout: stdout ?? ((l) => console.log(l)),
+            stderr: stderr ?? ((l) => console.error(l)),
+        });
+    }
     const owner = instances.find((a) => actionOrQueryNames(a).includes(targetName));
     if (!owner) {
-        (options.stderr ?? ((l) => console.error(l)))(`unknown action or query: "${targetName}". Run with --help.`);
+        (options.stderr ?? ((l) => console.error(l)))(`unknown command, action, or query: "${targetName}". Run with --help.`);
         return 1;
     }
     return forge.runCli(owner, argv, { stdout, stderr });
 }
+async function runCommand(command, instances, rest, io) {
+    const app = instances[0];
+    if (!app) {
+        io.stderr(`cannot run command "${command.name}": no app is registered with runPlease`);
+        return 1;
+    }
+    const parsed = parseFlagsToObject(rest);
+    let args = parsed;
+    if (command.args && typeof command.args.parse === "function") {
+        try {
+            args = command.args.parse(parsed);
+        }
+        catch (err) {
+            io.stderr(`invalid args for "${command.name}": ${err.message}`);
+            return 1;
+        }
+    }
+    const ctx = {
+        app,
+        resolve(name) {
+            return app.container.resolve(name);
+        },
+    };
+    try {
+        const result = await command.handler({ args: args, ctx });
+        if (result === undefined) {
+            io.stdout("OK");
+        }
+        else {
+            io.stdout(JSON.stringify(result, null, 2));
+        }
+        return 0;
+    }
+    catch (err) {
+        io.stderr(`error running command "${command.name}": ${err.message}`);
+        return 1;
+    }
+}
+/**
+ * Minimal flag parser shared with the action CLI surface. Mirrors the
+ * `--field value` / `--field=value` / repeated-flag / boolean-toggle behavior
+ * `forge.runCli` exposes, so command authors get the same operator UX.
+ */
+function parseFlagsToObject(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith("--"))
+            continue;
+        const eq = arg.indexOf("=");
+        let key;
+        let value;
+        if (eq >= 0) {
+            key = arg.slice(2, eq);
+            value = arg.slice(eq + 1);
+        }
+        else {
+            key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                value = next;
+                i++;
+            }
+            else {
+                value = true;
+            }
+        }
+        const coerced = typeof value === "string" ? coerceFlag(value) : value;
+        if (key in out) {
+            const existing = out[key];
+            if (Array.isArray(existing))
+                existing.push(coerced);
+            else
+                out[key] = [existing, coerced];
+        }
+        else {
+            out[key] = coerced;
+        }
+    }
+    return out;
+}
+function coerceFlag(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (/^-?\d+$/.test(value))
+        return Number(value);
+    if (/^-?\d+\.\d+$/.test(value))
+        return Number(value);
+    return value;
+}
 function actionOrQueryNames(app) {
     const actions = [];
     for (const module of app.modules) {
@@ -53,9 +156,16 @@ function actionOrQueryNames(app) {
     }
     return actions;
 }
-function printAllHelp(instances, out) {
+function printAllHelp(instances, commands, out) {
     out("please — Nwire operator CLI\n");
-    out("Usage: please <action-or-query-name> [--field value ...] [--tenant <id>]\n");
+    out("Usage: please <command-or-action-or-query> [--field value ...] [--tenant <id>]\n");
+    if (commands.length > 0) {
+        out("# Commands (operator scripts)");
+        for (const c of commands) {
+            out(`  ${c.name}${c.describe ? "  — " + c.describe.slice(0, 70) : ""}`);
+        }
+        out("");
+    }
     for (const app of instances) {
         out(`# App: ${describeApp(app)}`);
         for (const module of app.modules) {
@@ -74,4 +184,8 @@ function describeApp(app) {
     // `App` carries its AppDefinition reference. Today: show module count.
     return `${app.modules.length} module${app.modules.length === 1 ? "" : "s"}`;
 }
+// Surface the operator-script primitive alongside `runPlease`. Consumers
+// import them from the same package entry: `import { defineCommand, runPlease }
+// from '@nwire/please'`.
+export { defineCommand, } from "./define-command.js";
 //# sourceMappingURL=please.js.map

package/dist/please.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/please",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Nwire — operator CLI. runPlease dispatches actions/queries by name across all registered apps; --tenant for tenant scoping; --help lists everything. Scaffolding (make:module / make:action) lands on top.",
   "keywords": [
     "ace",
@@ -28,7 +28,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@nwire/forge": "0.7.1"
+    "@nwire/forge": "0.8.0",
+    "@nwire/messages": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",