@anna-ai/cli 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# @anna-ai/cli
+
+Anna App developer CLI — scaffold, validate, run a local dev harness, drive
+fixture-based regression tests, and program against the harness from
+`vitest`/`pytest`. Phases 2–9 (MVP) are done.
+
+## Install
+
+End-user install (after first npm publish):
+
+```bash
+npm i -g @anna-ai/cli
+anna-app --help
+```
+
+The `dev` and `fixture replay` commands transparently fetch the pinned Python
+runtime via `uvx` (no matrix-nexus checkout required). Install
+[uv](https://docs.astral.sh/uv/) once:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Local dev (this repo):
+
+```bash
+pnpm install
+pnpm sync:schema   # vendors @anna-ai/app-schema from sibling matrix-nexus checkout
+pnpm build
+node dist/cli.js --help
+```
+
+## Commands
+
+### `anna-app init <dir> [--slug <slug>] [--template minimal] [--force]`
+
+Scaffolds a new Anna App project (manifest + bundle + a stdio plugin
+template). `__TOOL_ID__` becomes `tool-dev-<slug>`.
+
+```bash
+anna-app init my-app --slug my-app
+cd my-app
+anna-app validate
+```
+
+### `anna-app validate [--manifest manifest.json] [--bundle bundle] [--strict]`
+
+Layered fail-fast checks: JSON Schema → `ui` static → cross-file `tool_id`
+linter (with Levenshtein-1 typo detection) → `--strict` host_api ACL grep
+of bundle JS/TS.
+
+### `anna-app dev [--manifest …] [--bundle …] [--port 5180] [--matrix-nexus-root <path>]`
+
+Boots the local harness:
+
+- Spawns the Python `anna-app-bridge` (production dispatcher reused via
+  `WindowStoreProtocol`).
+- Serves a mock dashboard at `http://localhost:<port>/`.
+- Auto-discovers `<manifest-dir>/executas/<name>/pyproject.toml` and
+  registers them in the in-process `ExecutaPool`.
+- Hot-reloads the bundle on disk changes (use `--no-watch` to disable).
+
+Two runtime modes (auto-selected):
+
+| Mode | When | Command |
+| --- | --- | --- |
+| `uvx` (default) | No matrix-nexus checkout nearby | `uvx anna-app-runtime-local@<pinned> anna-app-bridge` |
+| `nexus-source` | `--matrix-nexus-root` set, `$ANNA_NEXUS_ROOT` set, or running from inside a checkout | `uv run --project <root> python -m anna_app_runtime_local.bridge` |
+
+The pinned wheel version is exported as `PINNED_RUNTIME_VERSION` from
+[src/harness/bridge.ts](src/harness/bridge.ts) — bump in lock-step with
+`packages/VERSIONS.md` in matrix-nexus.
+
+### `anna-app doctor [--matrix-nexus-root <path>]`
+
+Environment sanity check: `uv` on PATH, `uvx` cache state for the pinned
+runtime, optional matrix-nexus checkout, dev signing key permissions.
+Exit `0` if all required checks pass.
+
+### `anna-app fixture verify <file.jsonl>`
+
+Strict syntactic + semantic validation of a recorded fixture (envelope
+ordering, response⇄request pairing, host_api allowlist).
+
+### `anna-app fixture summarize <file.jsonl>`
+
+Pretty stats: counts per `(ns, method)`, error breakdown, event totals.
+
+### `anna-app fixture replay <file.jsonl> [--manifest …]`
+
+Dry-run replay (MVP): re-executes the recorded request sequence against
+a fresh `LocalDispatcherSession` and diffs each response. Live executa
+re-invocation is deferred to a future minor.
+
+## Programmatic harness (vitest)
+
+```ts
+import { mountBundle } from "@anna-ai/cli/test";
+
+const h = await mountBundle({
+  manifest: "./examples/hello/manifest.json",
+  bundle:   "./examples/hello/bundle",
+});
+await h.call("storage", "set", { key: "k", value: 1 });
+const events = h.drainEvents();
+await h.close();
+```
+
+See [src/test/index.ts](src/test/index.ts) for the full surface
+(`call`, `expectAcl`, `drainEvents`, `dispose`).
+
+## Pytest plugin (`anna-executa-test`)
+
+For executa authors. Lives in matrix-nexus at
+`packages/anna-executa-test/`. Provides `executa_session` /
+`executa_invoke` fixtures — see that package's README.
+
+## Schema bundle sync
+
+The CLI vendors `@anna-ai/app-schema` until the npm bundle ships:
+
+```bash
+pnpm sync:schema                          # default: ../matrix-nexus
+pnpm sync:schema -- --from /path/to/...   # override
+```
+
+## Roadmap
+
+| Phase | Status | Scope |
+| --- | --- | --- |
+| 2 — `init` + `validate` | ✅ MVP | Schema/ACL checks |
+| 3 — `dev` harness | ✅ MVP | Stdio bridge, dashboard, hot-reload |
+| 4 — `@anna-ai/cli/test` | ✅ MVP | Programmatic `mountBundle` |
+| 5 — `anna-executa-test` (pytest) | ✅ MVP | Plugin shipped from matrix-nexus |
+| 6 — `fixture {verify,summarize,replay}` | ✅ MVP (dry-run replay) | Live re-invoke deferred |
+| 7 — Publish & distribution | ✅ done | uvx default + full `anna-app-core@0.2.0a1` extraction; end-users no longer need a matrix-nexus checkout |
+| 8 — `manifest.dev` block + init template + 4 docs | ✅ done | See [matrix-nexus/docs/developers/apps/](https://github.com/openclaw/matrix-nexus/tree/main/docs/developers/apps): `local-dev.md`, `testing-bundle.md`, `testing-plugin.md`, `recording-replay.md` |
+| 9 — Reference example upgraded | ✅ done | [`anna-executa-examples/examples/anna-app-focus-flow`](https://github.com/openclaw/anna-executa-examples/tree/main/examples/anna-app-focus-flow) ships `tests/{bundle,plugin}/`, fixtures, and `.github/workflows/anna-app.yml` |
+
+## Pinned versions
+
+- `PINNED_RUNTIME_VERSION = "0.2.0a1"` ([src/harness/bridge.ts](src/harness/bridge.ts))
+- See `matrix-nexus/packages/VERSIONS.md` for the full toolchain matrix.
+
+## Tests
+
+```bash
+pnpm test
+```

package/dist/bridge-CzEs7jaN.js

@@ -0,0 +1,145 @@
+import { delimiter, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+//#region src/harness/bridge.ts
+/**
+* Pinned `anna-app-runtime-local` version for uvx mode. Bump in lock-step
+* with `packages/VERSIONS.md` (matrix-nexus). The bridge passes this to
+* `uvx <pkg>@<version>` so end users always run the dispatcher version
+* the CLI was tested against.
+*/
+const PINNED_RUNTIME_VERSION = "0.2.0a1";
+var PythonBridge = class {
+	proc = null;
+	nextId = 1;
+	pending = new Map();
+	readyPromise = null;
+	closed = false;
+	constructor(opts) {
+		this.opts = opts;
+	}
+	/**
+	* Build the default launch command from `opts.mode`. uvx by default; for
+	* `nexus-source` mode, `matrixNexusRoot` must be set.
+	*/
+	buildDefaultCommand() {
+		const mode = this.opts.mode ?? "uvx";
+		if (mode === "nexus-source") {
+			if (!this.opts.matrixNexusRoot) throw new Error("BridgeOptions.matrixNexusRoot is required when mode=\"nexus-source\"");
+			return [
+				"uv",
+				"run",
+				"--project",
+				this.opts.matrixNexusRoot,
+				"python",
+				"-m",
+				"anna_app_runtime_local.bridge"
+			];
+		}
+		const version = this.opts.runtimeVersion ?? PINNED_RUNTIME_VERSION;
+		return [
+			"uvx",
+			`anna-app-runtime-local@${version}`,
+			"anna-app-bridge"
+		];
+	}
+	/** Spawn the Python process and wait for the `_ready` notification. */
+	async start() {
+		if (this.proc) return;
+		const cmd = this.opts.runtimeCommand ?? this.buildDefaultCommand();
+		const [bin, ...args] = cmd;
+		const useNexusPathInjection = !this.opts.runtimeCommand && (this.opts.mode ?? "uvx") === "nexus-source" && !!this.opts.matrixNexusRoot;
+		const env = { ...process.env };
+		if (useNexusPathInjection) {
+			const wheelSrc = resolve(this.opts.matrixNexusRoot, "packages/anna-app-runtime-local/src");
+			const existingPath = process.env.PYTHONPATH ?? "";
+			env.PYTHONPATH = existingPath ? `${wheelSrc}${delimiter}${existingPath}` : wheelSrc;
+		}
+		const cwd = (this.opts.mode ?? "uvx") === "nexus-source" ? this.opts.matrixNexusRoot : process.cwd();
+		if (!bin) throw new Error("PythonBridge: empty launch command (no executable)");
+		this.proc = spawn(bin, args, {
+			cwd,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			env
+		});
+		this.proc.on("exit", (code, signal) => {
+			this.closed = true;
+			const err = new Error(`python bridge exited (code=${code} signal=${signal ?? "-"})`);
+			for (const p of this.pending.values()) p.reject(err);
+			this.pending.clear();
+		});
+		const stderrSink = this.opts.onStderr ?? ((l) => process.stderr.write(`[bridge] ${l}\n`));
+		createInterface({ input: this.proc.stderr }).on("line", stderrSink);
+		this.readyPromise = new Promise((resolve$1, reject) => {
+			const rl = createInterface({ input: this.proc.stdout });
+			let ready = false;
+			rl.on("line", (line) => {
+				if (!line.trim()) return;
+				let env$1;
+				try {
+					env$1 = JSON.parse(line);
+				} catch (e) {
+					stderrSink(`non-json from bridge stdout: ${line}`);
+					return;
+				}
+				if (!ready && env$1.method === "_ready") {
+					ready = true;
+					resolve$1();
+					return;
+				}
+				this.handleResponse(env$1);
+			});
+			this.proc.on("error", (e) => reject(e));
+			setTimeout(() => {
+				if (!ready) reject(new Error("python bridge did not signal ready in 8s"));
+			}, 8e3);
+		});
+		await this.readyPromise;
+	}
+	handleResponse(env) {
+		const id = env.id;
+		if (id == null) return;
+		const pending = this.pending.get(id);
+		if (!pending) return;
+		this.pending.delete(id);
+		if (env.error) {
+			const e = env.error;
+			const err = new Error(`[${e.code}] ${e.message}`);
+			err.rpc = e;
+			pending.reject(err);
+		} else pending.resolve(env.result);
+	}
+	/** Send one JSON-RPC request and await its response. */
+	call(method, params = {}) {
+		if (this.closed || !this.proc) return Promise.reject(new Error("python bridge not running"));
+		const id = this.nextId++;
+		const env = {
+			jsonrpc: "2.0",
+			id,
+			method,
+			params
+		};
+		return new Promise((resolve$1, reject) => {
+			this.pending.set(id, {
+				resolve: (v) => resolve$1(v),
+				reject
+			});
+			this.proc.stdin.write(`${JSON.stringify(env)}\n`);
+		});
+	}
+	async stop() {
+		if (!this.proc) return;
+		this.closed = true;
+		this.proc.stdin.end();
+		this.proc.kill("SIGTERM");
+		this.proc = null;
+	}
+};
+
+//#endregion
+export { PINNED_RUNTIME_VERSION, PythonBridge };

package/dist/bridge-t2Qqu3hC.js

@@ -0,0 +1,3 @@
+import { PINNED_RUNTIME_VERSION, PythonBridge } from "./bridge-CzEs7jaN.js";
+
+export { PINNED_RUNTIME_VERSION, PythonBridge };

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/cli.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import kleur from "kleur";
+
+//#region src/commands/init.ts
+const here = dirname(fileURLToPath(import.meta.url));
+function templateRoot(template) {
+	for (const cand of [resolve(here, "..", "..", "templates", template), resolve(here, "..", "templates", template)]) if (existsSync(cand)) return cand;
+	throw new Error(`template not found: ${template}`);
+}
+function substitute(content, slug) {
+	const toolId = `tool-dev-${slug}`;
+	return content.replace(/__SLUG__/g, slug).replace(/__TOOL_ID__/g, toolId);
+}
+function copyDirWithSubst(src, dst, slug) {
+	mkdirSync(dst, { recursive: true });
+	for (const entry of readdirSync(src, { withFileTypes: true })) {
+		const s = join(src, entry.name);
+		const d = join(dst, entry.name);
+		if (entry.isDirectory()) copyDirWithSubst(s, d, slug);
+		else if (entry.isFile()) {
+			const stat = statSync(s);
+			if (stat.size < 256 * 1024) {
+				const buf = readFileSync(s);
+				const looksText = !buf.includes(0);
+				if (looksText) {
+					writeFileSync(d, substitute(buf.toString("utf-8"), slug), "utf-8");
+					continue;
+				}
+			}
+			cpSync(s, d);
+		}
+	}
+}
+function runInit(opts) {
+	const target = resolve(process.cwd(), opts.targetDir);
+	if (existsSync(target) && !opts.force) {
+		if (readdirSync(target).filter((n) => !n.startsWith(".")).length > 0) {
+			console.error(kleur.red(`✗ target dir not empty: ${target} (use --force to override)`));
+			return 1;
+		}
+	}
+	if (!/^[a-z][a-z0-9-]{1,40}$/.test(opts.slug)) {
+		console.error(kleur.red(`✗ invalid slug "${opts.slug}": must match /^[a-z][a-z0-9-]{1,40}$/`));
+		return 1;
+	}
+	const tplRoot = templateRoot(opts.template);
+	copyDirWithSubst(tplRoot, target, opts.slug);
+	console.log(kleur.green(`✓ scaffolded "${opts.slug}" at ${target}`));
+	console.log(kleur.gray(`  next: cd ${opts.targetDir} && anna-app validate`));
+	return 0;
+}
+
+//#endregion
+//#region src/cli.ts
+const program = new Command();
+program.name("anna-app").description("Anna App developer CLI (scaffold, validate, harness)").version("0.1.0");
+program.command("init <dir>").description("Scaffold a new Anna App project").option("--slug <slug>", "App slug (lowercase, hyphens)", "").option("--template <name>", "Template to use", "minimal").option("--force", "Overwrite existing dir if non-empty", false).action((dir, opts) => {
+	const slug = opts.slug || dir.split(/[\\/]/).pop() || "my-anna-app";
+	const code = runInit({
+		targetDir: dir,
+		slug,
+		template: opts.template,
+		force: opts.force
+	});
+	process.exit(code);
+});
+program.command("dev").description("Run a local harness (in-process dispatcher + iframe + SSE relay)").option("--manifest <path>", "manifest.json path", "manifest.json").option("--bundle <dir>", "bundle directory (default: ./bundle)").option("--slug <slug>", "App slug (overrides manifest.slug/name)").option("--view <name>", "View name to open (default: manifest default)").option("--matrix-nexus-root <path>", "matrix-nexus checkout (auto-detected if omitted; can also use $ANNA_NEXUS_ROOT)").option("--port <number>", "HTTP port", "5180").option("--user-id <id>", "Harness user_id", "1").option("--cwd <dir>", "Project root (default: cwd)").option("--no-watch", "Disable bundle file watcher (default: enabled)").action(async (opts) => {
+	const { runDev } = await import("./dev-Bgku5ngL.js");
+	const code = await runDev({
+		cwd: opts.cwd ?? process.cwd(),
+		manifestPath: opts.manifest,
+		bundleDir: opts.bundle,
+		slug: opts.slug,
+		view: opts.view,
+		matrixNexusRoot: opts.matrixNexusRoot,
+		port: Number.parseInt(opts.port, 10),
+		userId: Number.parseInt(opts.userId, 10),
+		noWatch: opts.watch === false
+	});
+	process.exit(code);
+});
+const fixture = program.command("fixture").description("Inspect / replay harness recordings (Phase 6)");
+fixture.command("verify <file>").description("Schema + invariant checks on a harness JSONL recording").option("--json", "Emit machine-readable JSON", false).action(async (file, opts) => {
+	const { runFixtureVerify } = await import("./fixture-BGjMtqWA.js");
+	const code = await runFixtureVerify({
+		file,
+		json: opts.json
+	});
+	process.exit(code);
+});
+fixture.command("summarize <file>").description("Print a human-readable digest of a harness recording").option("--json", "Emit machine-readable JSON", false).action(async (file, opts) => {
+	const { runFixtureSummarize } = await import("./fixture-BGjMtqWA.js");
+	const code = await runFixtureSummarize({
+		file,
+		json: opts.json
+	});
+	process.exit(code);
+});
+fixture.command("replay <file>").description("Dry-run replay of a harness recording (Phase 6 MVP)").option("--manifest <path>", "manifest.json path", "manifest.json").action(async (file, opts) => {
+	const { runFixtureReplay } = await import("./fixture-BGjMtqWA.js");
+	const code = await runFixtureReplay({
+		file,
+		manifest: opts.manifest
+	});
+	process.exit(code);
+});
+program.command("doctor").description("Check environment for `anna-app dev` (uv, matrix-nexus, dev key)").option("--matrix-nexus-root <path>", "matrix-nexus checkout (optional)").action(async (opts) => {
+	const { runDoctor } = await import("./doctor-D3z4YslL.js");
+	const code = await runDoctor({ matrixNexusRoot: opts.matrixNexusRoot });
+	process.exit(code);
+});
+program.parseAsync(process.argv).catch((e) => {
+	console.error(e);
+	process.exit(2);
+});
+
+//#endregion