@nwire/please 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @nwire/please
+
+> Operator CLI — dispatch any registered action or query 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
+
+```bash
+pnpm add @nwire/please
+```
+
+## Quick start
+
+```ts
+#!/usr/bin/env node
+import { runPlease } from "@nwire/please";
+import { apps } from "../app/apps";
+
+runPlease({ apps, argv: process.argv.slice(2) }).then((code) => process.exit(code));
+```
+
+```bash
+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
+
+- `runPlease({ apps, appInstances?, argv, stdout?, stderr? })` — returns exit code.
+
+## When to use
+
+Operations work — re-run a stuck workflow, query a projection, kick a one-off action — without writing a script or shelling into a worker. Fits L3 and up.
+
+## Used only within nwire-app
+
+This package is part of the Nwire stack — it only makes sense inside a Nwire application built with `@nwire/app` + `@nwire/forge`. If you're looking for a standalone primitive, see:
+
+- [`@nwire/handler`](../nwire-handler/README.md) — the operation primitive (transport-agnostic)
+- [`@nwire/hooks`](../nwire-hooks/README.md) — universal dispatch (chain + listeners)
+- [`@nwire/http`](../nwire-http/README.md) — typed HTTP without forge
+- [`@nwire/endpoint`](../nwire-endpoint/README.md) — graceful shutdown for any host
+
+## See also
+
+- [Architecture sketch §05 — Tooling](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/cli](../nwire-cli), [@nwire/mcp](../nwire-mcp)

package/dist/please.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `@nwire/please` — operator CLI for Nwire apps.
+ *
+ *   #!/usr/bin/env node
+ *   import { runPlease } from '@nwire/please'
+ *   import { apps } from '../app/apps'
+ *
+ *   runPlease({ apps, argv: process.argv.slice(2) }).then(code => process.exit(code))
+ *
+ * The CLI dispatches against any registered action or query in any app.
+ *   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
+ *
+ * Scaffolding (`make:module`, `make:action`, `make:projection`) lands as a
+ * follow-up phase — the CLI runner is the primitive, scaffolders compose on top.
+ */
+import * as forge from "@nwire/forge";
+export interface RunPleaseOptions {
+    /** Apps to expose. The CLI dispatches against any action/query in any of these. */
+    readonly apps: readonly forge.AppDefinition[];
+    /** Pre-instantiated `App`s (for tests where stores are injected). */
+    readonly appInstances?: readonly forge.App[];
+    /** Argv slice, typically `process.argv.slice(2)`. */
+    readonly argv: readonly string[];
+    /** stdout override (tests). Default: console.log. */
+    readonly stdout?: (line: string) => void;
+    /** stderr override (tests). Default: console.error. */
+    readonly stderr?: (line: string) => void;
+    /** Hook for store/logger overrides at instantiation time. */
+    readonly createOverrides?: (appDef: forge.AppDefinition) => Omit<forge.CreateAppOptions, "modules">;
+}
+/**
+ * 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>;
+//# sourceMappingURL=please.d.ts.map

package/dist/please.d.ts.map

@@ -0,0 +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"}

package/dist/please.js

@@ -0,0 +1,77 @@
+/**
+ * `@nwire/please` — operator CLI for Nwire apps.
+ *
+ *   #!/usr/bin/env node
+ *   import { runPlease } from '@nwire/please'
+ *   import { apps } from '../app/apps'
+ *
+ *   runPlease({ apps, argv: process.argv.slice(2) }).then(code => process.exit(code))
+ *
+ * The CLI dispatches against any registered action or query in any app.
+ *   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
+ *
+ * Scaffolding (`make:module`, `make:action`, `make:projection`) lands as a
+ * follow-up phase — the CLI runner is the primitive, scaffolders compose on top.
+ */
+import * as forge from "@nwire/forge";
+/**
+ * Boot every registered app, run the dispatched action/query against the
+ * matching app, return the exit code (0 on success, 1 on error).
+ */
+export async function runPlease(options) {
+    const instances = options.appInstances?.slice() ??
+        options.apps.map((def) => def.create(options.createOverrides?.(def) ?? {}));
+    await Promise.all(instances.map((a) => a.start()));
+    // Find which app owns the named action/query and run against THAT app.
+    // For now, if argv[0] is a name found in any app, dispatch through that.
+    // Multi-app `please <app>:<action>` syntax lands when needed.
+    const argv = options.argv;
+    const stdout = options.stdout;
+    const stderr = options.stderr;
+    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+        printAllHelp(instances, options.stdout ?? ((l) => console.log(l)));
+        return 0;
+    }
+    const targetName = argv[0];
+    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.`);
+        return 1;
+    }
+    return forge.runCli(owner, argv, { stdout, stderr });
+}
+function actionOrQueryNames(app) {
+    const actions = [];
+    for (const module of app.modules) {
+        for (const action of module.manifest.actions ?? [])
+            actions.push(action.name);
+        for (const query of module.manifest.queries ?? [])
+            actions.push(query.name);
+    }
+    return actions;
+}
+function printAllHelp(instances, out) {
+    out("please — Nwire operator CLI\n");
+    out("Usage: please <action-or-query-name> [--field value ...] [--tenant <id>]\n");
+    for (const app of instances) {
+        out(`# App: ${describeApp(app)}`);
+        for (const module of app.modules) {
+            for (const action of module.manifest.actions ?? []) {
+                out(`  ${action.name}${action.description ? "  — " + action.description.slice(0, 70) : ""}`);
+            }
+            for (const query of module.manifest.queries ?? []) {
+                out(`  ${query.name}${query.description ? "  — " + query.description.slice(0, 70) : ""}`);
+            }
+        }
+        out("");
+    }
+}
+function describeApp(app) {
+    // The runtime doesn't expose the app's name yet; defer naming until
+    // `App` carries its AppDefinition reference. Today: show module count.
+    return `${app.modules.length} module${app.modules.length === 1 ? "" : "s"}`;
+}
+//# sourceMappingURL=please.js.map

package/dist/please.js.map

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

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@nwire/please",
+  "version": "0.7.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",
+    "artisan",
+    "cli",
+    "nwire",
+    "please"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/please.js",
+  "types": "./dist/please.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/please.js",
+      "types": "./dist/please.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/forge": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}