@mindees/cli 0.1.0

package/LICENSE

@@ -0,0 +1,31 @@
+# License
+
+MindeesNative is dual-licensed under either of:
+
+- **Apache License, Version 2.0** ([LICENSE-APACHE](./LICENSE-APACHE) or
+  <https://www.apache.org/licenses/LICENSE-2.0>)
+- **MIT license** ([LICENSE-MIT](./LICENSE-MIT) or
+  <https://opensource.org/licenses/MIT>)
+
+at your option.
+
+This `MIT OR Apache-2.0` dual-license is the same model used by the Rust
+ecosystem and many modern open-source projects. It gives downstream users
+maximum flexibility: the MIT option is short and permissive, while the Apache
+option adds an explicit patent grant.
+
+## SPDX identifier
+
+```
+SPDX-License-Identifier: MIT OR Apache-2.0
+```
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the Apache-2.0
+license, shall be dual-licensed as above, without any additional terms or
+conditions.
+
+Contributions are accepted under the **Developer Certificate of Origin (DCO)**.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on signing off your commits.

package/README.md

@@ -0,0 +1,70 @@
+# @mindees/cli
+
+**Forge** — the `mindees` command-line interface. Scaffold apps, type-check +
+build them with the Mindees Compiler, and diagnose your environment. Zero
+third-party dependencies (built on `node:util` `parseArgs`).
+
+> **Status: 🧪 Experimental (Phase 5).** `create`, `build`, `doctor`, `info`,
+> and the dev **rebuild orchestrator** are implemented and tested. The live
+> dev-server **HTTP/HMR transport** is a developer preview. On-device NL→app
+> generation is Phase 10 — today `--prompt` maps to a template deterministically.
+
+## Commands
+
+```bash
+mindees create <name-or-path> [--template blank|counter] [--prompt "..."] [--force]
+mindees build [--out-dir <dir>] [--no-source-map]
+mindees doctor          # diagnose Node / package manager / project / deps
+mindees info            # CLI + environment info
+mindees dev             # rebuild-on-change (developer preview)
+mindees help
+```
+
+```text
+$ mindees create my-app --template counter
+Created "my-app" from the counter template (6 files).
+Next: cd "my-app" && pnpm install && mindees dev
+
+$ mindees build
+Built 3 module(s); flattened 4/9 elements.
+
+$ mindees doctor
+✓ Node.js: v24.7.0
+✓ Package manager: pnpm 11.5.0
+! Dependencies: node_modules missing
+    → Install dependencies: `pnpm install` (or `npm exec --yes --package=pnpm@11.5.0 -- pnpm install` if the pnpm shim is unavailable).
+```
+
+## Design: a testable core, a thin shell
+
+Every command is a **pure function** of injected capabilities — a `FileSystem`,
+an `EnvProbe`, and a `Writer` — so the entire CLI is deterministic in tests. The
+`mindees` executable (`bin`) is a thin adapter that wires real `node:fs` /
+`process` into `runCli`. Highlights:
+
+- **`scaffold`** — writes a template through the injected FS (templates are
+  in-memory; no on-disk fixtures). Refuses a non-empty target without `--force`.
+- **`resolveCreateTarget`** — normalizes simple names, relative paths, and
+  absolute Windows/POSIX paths into a target directory plus npm-safe package
+  name, so path separators never leak into generated `package.json` files.
+- **`buildProject`** — compiles `src/**` via `@mindees/compiler` (the type-check
+  gate + emit), writing `dist/` and a `routes.manifest.json` when `src/routes/`
+  exists. Genuine type errors fail the build; isolation-only diagnostics
+  (unresolved cross-module imports, missing ambient JSX types) are reported as
+  warnings (full project-graph checking is future work).
+- **`runDoctor`** — environment checks with actionable fixes, over an injected
+  `EnvProbe`.
+- **`startDev`** — the rebuild orchestrator: builds once, rebuilds on each
+  `Watcher` change, tracks build count + last result. The watcher and HMR
+  transport are injected (the live server is the preview layer).
+
+## Library API
+
+Forge's internals are exported so other tooling (and `create-mindees`) can reuse
+them: `runCli`, `scaffold`, `buildProject`, `startDev`, `runDoctor`,
+`resolveCreateTarget`, `createMemoryFileSystem`, `TEMPLATES`,
+`naturalLanguageToTemplate`, and their types.
+
+## License
+
+`MIT OR Apache-2.0`

package/dist/ai.d.ts

@@ -0,0 +1,15 @@
+import { CommandResult, Writer } from "./types.js";
+import { AiBackend } from "@mindees/ai";
+
+//#region src/ai.d.ts
+/** What `runAiCommand` needs (injected for testability). */
+interface AiCommandContext {
+  write: Writer;
+  /** The AI backend; absent when no `MINDEES_AI_*` env is configured. */
+  backend?: AiBackend;
+}
+/** Run an `ai` subcommand. Async because it talks to a model. */
+declare function runAiCommand(args: readonly string[], ctx: AiCommandContext): Promise<CommandResult>;
+//#endregion
+export { AiCommandContext, runAiCommand };
+//# sourceMappingURL=ai.d.ts.map

package/dist/ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","names":[],"sources":["../src/ai.ts"],"mappings":";;;;;UAeiB,gBAAA;EACf,KAAA,EAAO,MAAA;EAwBa;EAtBpB,OAAA,GAAU,SAAS;AAAA;;iBAsBC,YAAA,CACpB,IAAA,qBACA,GAAA,EAAK,gBAAA,GACJ,OAAA,CAAQ,aAAA"}

package/dist/ai.js

@@ -0,0 +1,57 @@
+import { explainError, formatExplanation } from "@mindees/ai/devtools";
+//#region src/ai.ts
+const AI_HELP = `mindees ai — dev-time AI helpers
+
+Usage:
+  mindees ai explain <error message...>   Explain an error and suggest fixes
+
+Configure a backend with environment variables:
+  MINDEES_AI_BASE_URL   e.g. https://api.openai.com/v1
+  MINDEES_AI_MODEL      e.g. gpt-4o-mini
+  MINDEES_AI_API_KEY    your key
+  MINDEES_AI_ADAPTER    openai (default) | anthropic`;
+function out(write, text) {
+	write({
+		stream: "out",
+		text
+	});
+}
+function err(write, text) {
+	write({
+		stream: "err",
+		text
+	});
+}
+/** Run an `ai` subcommand. Async because it talks to a model. */
+async function runAiCommand(args, ctx) {
+	const [sub, ...rest] = args;
+	if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+		out(ctx.write, AI_HELP);
+		return { exitCode: 0 };
+	}
+	if (sub !== "explain") {
+		err(ctx.write, `Unknown ai command "${sub}". Try \`mindees ai explain <error>\`.`);
+		return { exitCode: 1 };
+	}
+	const message = rest.join(" ").trim();
+	if (!message) {
+		err(ctx.write, "ai explain: provide an error message. Usage: mindees ai explain <error>");
+		return { exitCode: 1 };
+	}
+	if (!ctx.backend) {
+		err(ctx.write, "No AI backend configured. Set MINDEES_AI_BASE_URL and MINDEES_AI_MODEL (and MINDEES_AI_API_KEY if your provider needs one).");
+		return { exitCode: 1 };
+	}
+	try {
+		const explanation = await explainError(ctx.backend, { message });
+		out(ctx.write, formatExplanation(explanation));
+		return { exitCode: 0 };
+	} catch (e) {
+		err(ctx.write, `ai explain failed: ${e instanceof Error ? e.message : String(e)}`);
+		return { exitCode: 1 };
+	}
+}
+//#endregion
+export { runAiCommand };
+
+//# sourceMappingURL=ai.js.map

package/dist/ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.js","names":[],"sources":["../src/ai.ts"],"sourcesContent":["/**\n * `mindees ai` — dev-time AI helpers. Currently `ai explain <error>`, which runs Synapse's\n * {@link explainError} (from `@mindees/ai/devtools`) over an injected backend and prints a\n * structured explanation. Like every command, it's a pure function of injected capabilities\n * (the backend + writer), so it's deterministically testable with the mock backend; the real\n * `bin` wires a server backend from environment variables.\n *\n * @module\n */\n\nimport type { AiBackend } from '@mindees/ai'\nimport { explainError, formatExplanation } from '@mindees/ai/devtools'\nimport type { CommandResult, Writer } from './types'\n\n/** What `runAiCommand` needs (injected for testability). */\nexport interface AiCommandContext {\n  write: Writer\n  /** The AI backend; absent when no `MINDEES_AI_*` env is configured. */\n  backend?: AiBackend\n}\n\nconst AI_HELP = `mindees ai — dev-time AI helpers\n\nUsage:\n  mindees ai explain <error message...>   Explain an error and suggest fixes\n\nConfigure a backend with environment variables:\n  MINDEES_AI_BASE_URL   e.g. https://api.openai.com/v1\n  MINDEES_AI_MODEL      e.g. gpt-4o-mini\n  MINDEES_AI_API_KEY    your key\n  MINDEES_AI_ADAPTER    openai (default) | anthropic`\n\nfunction out(write: Writer, text: string): void {\n  write({ stream: 'out', text })\n}\nfunction err(write: Writer, text: string): void {\n  write({ stream: 'err', text })\n}\n\n/** Run an `ai` subcommand. Async because it talks to a model. */\nexport async function runAiCommand(\n  args: readonly string[],\n  ctx: AiCommandContext,\n): Promise<CommandResult> {\n  const [sub, ...rest] = args\n\n  if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {\n    out(ctx.write, AI_HELP)\n    return { exitCode: 0 }\n  }\n  if (sub !== 'explain') {\n    err(ctx.write, `Unknown ai command \"${sub}\". Try \\`mindees ai explain <error>\\`.`)\n    return { exitCode: 1 }\n  }\n\n  const message = rest.join(' ').trim()\n  if (!message) {\n    err(ctx.write, 'ai explain: provide an error message. Usage: mindees ai explain <error>')\n    return { exitCode: 1 }\n  }\n  if (!ctx.backend) {\n    err(\n      ctx.write,\n      'No AI backend configured. Set MINDEES_AI_BASE_URL and MINDEES_AI_MODEL (and MINDEES_AI_API_KEY if your provider needs one).',\n    )\n    return { exitCode: 1 }\n  }\n\n  try {\n    const explanation = await explainError(ctx.backend, { message })\n    out(ctx.write, formatExplanation(explanation))\n    return { exitCode: 0 }\n  } catch (e) {\n    err(ctx.write, `ai explain failed: ${e instanceof Error ? e.message : String(e)}`)\n    return { exitCode: 1 }\n  }\n}\n"],"mappings":";;AAqBA,MAAM,UAAU;;;;;;;;;;AAWhB,SAAS,IAAI,OAAe,MAAoB;CAC9C,MAAM;EAAE,QAAQ;EAAO;CAAK,CAAC;AAC/B;AACA,SAAS,IAAI,OAAe,MAAoB;CAC9C,MAAM;EAAE,QAAQ;EAAO;CAAK,CAAC;AAC/B;;AAGA,eAAsB,aACpB,MACA,KACwB;CACxB,MAAM,CAAC,KAAK,GAAG,QAAQ;CAEvB,IAAI,CAAC,OAAO,QAAQ,UAAU,QAAQ,YAAY,QAAQ,MAAM;EAC9D,IAAI,IAAI,OAAO,OAAO;EACtB,OAAO,EAAE,UAAU,EAAE;CACvB;CACA,IAAI,QAAQ,WAAW;EACrB,IAAI,IAAI,OAAO,uBAAuB,IAAI,uCAAuC;EACjF,OAAO,EAAE,UAAU,EAAE;CACvB;CAEA,MAAM,UAAU,KAAK,KAAK,GAAG,EAAE,KAAK;CACpC,IAAI,CAAC,SAAS;EACZ,IAAI,IAAI,OAAO,yEAAyE;EACxF,OAAO,EAAE,UAAU,EAAE;CACvB;CACA,IAAI,CAAC,IAAI,SAAS;EAChB,IACE,IAAI,OACJ,6HACF;EACA,OAAO,EAAE,UAAU,EAAE;CACvB;CAEA,IAAI;EACF,MAAM,cAAc,MAAM,aAAa,IAAI,SAAS,EAAE,QAAQ,CAAC;EAC/D,IAAI,IAAI,OAAO,kBAAkB,WAAW,CAAC;EAC7C,OAAO,EAAE,UAAU,EAAE;CACvB,SAAS,GAAG;EACV,IAAI,IAAI,OAAO,sBAAsB,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,GAAG;EACjF,OAAO,EAAE,UAAU,EAAE;CACvB;AACF"}

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { VERSION } from "./version.js";
+import { runCliAsync } from "./cli.js";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import process from "node:process";
+import { createServerBackend } from "@mindees/ai/server";
+//#region src/bin.ts
+/**
+* The `mindees` executable — a thin adapter that wires real Node capabilities
+* (filesystem, environment probe, stdout/stderr, AI backend) into the tested
+* {@link runCliAsync} core. All logic lives in the core; this file only does I/O wiring.
+*
+* @module
+*/
+/** A `node:fs`-backed {@link FileSystem}. */
+function nodeFileSystem() {
+	return {
+		exists: (path) => existsSync(path),
+		readFile: (path) => readFileSync(path, "utf8"),
+		writeFile: (path, contents) => {
+			mkdirSync(dirname(path), { recursive: true });
+			writeFileSync(path, contents, "utf8");
+		},
+		mkdir: (path) => {
+			mkdirSync(path, { recursive: true });
+		},
+		readDir: (dir) => {
+			const walk = (current, acc) => {
+				if (!existsSync(current)) return acc;
+				for (const entry of readdirSync(current)) {
+					const full = join(current, entry);
+					if (statSync(full).isDirectory()) walk(full, acc);
+					else acc.push(relative(dir, full).split(sep).join("/"));
+				}
+				return acc;
+			};
+			return walk(dir, []).sort();
+		}
+	};
+}
+/** Probe the real environment for `doctor`/`info`. */
+function probeEnv(cwd) {
+	const pmMatch = (process.env.npm_config_user_agent ?? "").match(/^(\w+)\/(\S+)/);
+	return {
+		nodeVersion: process.version,
+		packageManager: pmMatch?.[1] && pmMatch[2] ? {
+			name: pmMatch[1],
+			version: pmMatch[2]
+		} : null,
+		hasPackageJson: existsSync(join(cwd, "package.json")),
+		hasNodeModules: existsSync(join(cwd, "node_modules"))
+	};
+}
+/** Build a server AI backend from `MINDEES_AI_*` env, or `undefined` if not configured. */
+function aiBackendFromEnv() {
+	const baseUrl = process.env.MINDEES_AI_BASE_URL;
+	const model = process.env.MINDEES_AI_MODEL;
+	if (!baseUrl || !model) return void 0;
+	const adapterEnv = process.env.MINDEES_AI_ADAPTER;
+	if (adapterEnv && adapterEnv !== "openai" && adapterEnv !== "anthropic") {
+		process.stderr.write(`mindees: unknown MINDEES_AI_ADAPTER "${adapterEnv}" (expected "openai" or "anthropic"); AI backend not configured.\n`);
+		return;
+	}
+	const adapter = adapterEnv === "anthropic" ? "anthropic" : "openai";
+	return createServerBackend({
+		fetch: globalThis.fetch,
+		baseUrl,
+		model,
+		adapter,
+		...process.env.MINDEES_AI_API_KEY ? { apiKey: process.env.MINDEES_AI_API_KEY } : {}
+	});
+}
+async function main() {
+	const cwd = process.cwd();
+	const write = (line) => {
+		(line.stream === "err" ? process.stderr : process.stdout).write(`${line.text}\n`);
+	};
+	const backend = aiBackendFromEnv();
+	const ctx = {
+		fs: nodeFileSystem(),
+		env: probeEnv(cwd),
+		cwd,
+		version: VERSION,
+		write,
+		...backend ? { aiBackend: backend } : {}
+	};
+	const { exitCode } = await runCliAsync(process.argv.slice(2), ctx);
+	process.exitCode = exitCode;
+}
+main();
+//#endregion
+
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * The `mindees` executable — a thin adapter that wires real Node capabilities\n * (filesystem, environment probe, stdout/stderr, AI backend) into the tested\n * {@link runCliAsync} core. All logic lives in the core; this file only does I/O wiring.\n *\n * @module\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'\nimport { dirname, join, relative, sep } from 'node:path'\nimport process from 'node:process'\nimport type { AiBackend } from '@mindees/ai'\nimport { type AdapterName, createServerBackend, type FetchLike } from '@mindees/ai/server'\nimport { type CliContext, runCliAsync } from './cli'\nimport type { FileSystem } from './fs'\nimport { VERSION } from './index'\nimport type { EnvProbe, OutputLine } from './types'\n\n/** A `node:fs`-backed {@link FileSystem}. */\nfunction nodeFileSystem(): FileSystem {\n  return {\n    exists: (path) => existsSync(path),\n    readFile: (path) => readFileSync(path, 'utf8'),\n    writeFile: (path, contents) => {\n      mkdirSync(dirname(path), { recursive: true })\n      writeFileSync(path, contents, 'utf8')\n    },\n    mkdir: (path) => {\n      mkdirSync(path, { recursive: true })\n    },\n    readDir: (dir) => {\n      const walk = (current: string, acc: string[]): string[] => {\n        if (!existsSync(current)) return acc\n        for (const entry of readdirSync(current)) {\n          const full = join(current, entry)\n          if (statSync(full).isDirectory()) walk(full, acc)\n          else acc.push(relative(dir, full).split(sep).join('/'))\n        }\n        return acc\n      }\n      return walk(dir, []).sort()\n    },\n  }\n}\n\n/** Probe the real environment for `doctor`/`info`. */\nfunction probeEnv(cwd: string): EnvProbe {\n  const pmSpec = process.env.npm_config_user_agent ?? ''\n  // user agent looks like \"pnpm/11.5.0 npm/? node/v24 ...\".\n  const pmMatch = pmSpec.match(/^(\\w+)\\/(\\S+)/)\n  return {\n    nodeVersion: process.version,\n    packageManager: pmMatch?.[1] && pmMatch[2] ? { name: pmMatch[1], version: pmMatch[2] } : null,\n    hasPackageJson: existsSync(join(cwd, 'package.json')),\n    hasNodeModules: existsSync(join(cwd, 'node_modules')),\n  }\n}\n\n/** Build a server AI backend from `MINDEES_AI_*` env, or `undefined` if not configured. */\nfunction aiBackendFromEnv(): AiBackend | undefined {\n  const baseUrl = process.env.MINDEES_AI_BASE_URL\n  const model = process.env.MINDEES_AI_MODEL\n  if (!baseUrl || !model) return undefined\n  // Fail loud on a mistyped adapter rather than silently defaulting to openai (which would\n  // build the wrong auth headers and yield confusing HTTP errors). Empty/unset → openai.\n  const adapterEnv = process.env.MINDEES_AI_ADAPTER\n  if (adapterEnv && adapterEnv !== 'openai' && adapterEnv !== 'anthropic') {\n    process.stderr.write(\n      `mindees: unknown MINDEES_AI_ADAPTER \"${adapterEnv}\" (expected \"openai\" or \"anthropic\"); AI backend not configured.\\n`,\n    )\n    return undefined\n  }\n  const adapter: AdapterName = adapterEnv === 'anthropic' ? 'anthropic' : 'openai'\n  return createServerBackend({\n    // The global `fetch` is structurally compatible at runtime; the minimal FetchLike\n    // intentionally avoids the DOM lib, so cast rather than pull in those types.\n    fetch: globalThis.fetch as unknown as FetchLike,\n    baseUrl,\n    model,\n    adapter,\n    ...(process.env.MINDEES_AI_API_KEY ? { apiKey: process.env.MINDEES_AI_API_KEY } : {}),\n  })\n}\n\nasync function main(): Promise<void> {\n  const cwd = process.cwd()\n  const write = (line: OutputLine): void => {\n    const stream = line.stream === 'err' ? process.stderr : process.stdout\n    stream.write(`${line.text}\\n`)\n  }\n  const backend = aiBackendFromEnv()\n  const ctx: CliContext = {\n    fs: nodeFileSystem(),\n    env: probeEnv(cwd),\n    cwd,\n    version: VERSION,\n    write,\n    ...(backend ? { aiBackend: backend } : {}),\n  }\n  const { exitCode } = await runCliAsync(process.argv.slice(2), ctx)\n  process.exitCode = exitCode\n}\n\nmain()\n"],"mappings":";;;;;;;;;;;;;;;;AAqBA,SAAS,iBAA6B;CACpC,OAAO;EACL,SAAS,SAAS,WAAW,IAAI;EACjC,WAAW,SAAS,aAAa,MAAM,MAAM;EAC7C,YAAY,MAAM,aAAa;GAC7B,UAAU,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;GAC5C,cAAc,MAAM,UAAU,MAAM;EACtC;EACA,QAAQ,SAAS;GACf,UAAU,MAAM,EAAE,WAAW,KAAK,CAAC;EACrC;EACA,UAAU,QAAQ;GAChB,MAAM,QAAQ,SAAiB,QAA4B;IACzD,IAAI,CAAC,WAAW,OAAO,GAAG,OAAO;IACjC,KAAK,MAAM,SAAS,YAAY,OAAO,GAAG;KACxC,MAAM,OAAO,KAAK,SAAS,KAAK;KAChC,IAAI,SAAS,IAAI,EAAE,YAAY,GAAG,KAAK,MAAM,GAAG;UAC3C,IAAI,KAAK,SAAS,KAAK,IAAI,EAAE,MAAM,GAAG,EAAE,KAAK,GAAG,CAAC;IACxD;IACA,OAAO;GACT;GACA,OAAO,KAAK,KAAK,CAAC,CAAC,EAAE,KAAK;EAC5B;CACF;AACF;;AAGA,SAAS,SAAS,KAAuB;CAGvC,MAAM,WAFS,QAAQ,IAAI,yBAAyB,IAE7B,MAAM,eAAe;CAC5C,OAAO;EACL,aAAa,QAAQ;EACrB,gBAAgB,UAAU,MAAM,QAAQ,KAAK;GAAE,MAAM,QAAQ;GAAI,SAAS,QAAQ;EAAG,IAAI;EACzF,gBAAgB,WAAW,KAAK,KAAK,cAAc,CAAC;EACpD,gBAAgB,WAAW,KAAK,KAAK,cAAc,CAAC;CACtD;AACF;;AAGA,SAAS,mBAA0C;CACjD,MAAM,UAAU,QAAQ,IAAI;CAC5B,MAAM,QAAQ,QAAQ,IAAI;CAC1B,IAAI,CAAC,WAAW,CAAC,OAAO,OAAO,KAAA;CAG/B,MAAM,aAAa,QAAQ,IAAI;CAC/B,IAAI,cAAc,eAAe,YAAY,eAAe,aAAa;EACvE,QAAQ,OAAO,MACb,wCAAwC,WAAW,mEACrD;EACA;CACF;CACA,MAAM,UAAuB,eAAe,cAAc,cAAc;CACxE,OAAO,oBAAoB;EAGzB,OAAO,WAAW;EAClB;EACA;EACA;EACA,GAAI,QAAQ,IAAI,qBAAqB,EAAE,QAAQ,QAAQ,IAAI,mBAAmB,IAAI,CAAC;CACrF,CAAC;AACH;AAEA,eAAe,OAAsB;CACnC,MAAM,MAAM,QAAQ,IAAI;CACxB,MAAM,SAAS,SAA2B;EAExC,CADe,KAAK,WAAW,QAAQ,QAAQ,SAAS,QAAQ,QACzD,MAAM,GAAG,KAAK,KAAK,GAAG;CAC/B;CACA,MAAM,UAAU,iBAAiB;CACjC,MAAM,MAAkB;EACtB,IAAI,eAAe;EACnB,KAAK,SAAS,GAAG;EACjB;EACA,SAAS;EACT;EACA,GAAI,UAAU,EAAE,WAAW,QAAQ,IAAI,CAAC;CAC1C;CACA,MAAM,EAAE,aAAa,MAAM,YAAY,QAAQ,KAAK,MAAM,CAAC,GAAG,GAAG;CACjE,QAAQ,WAAW;AACrB;AAEA,KAAK"}

package/dist/build.d.ts

@@ -0,0 +1,37 @@
+import { FileSystem } from "./fs.js";
+import { Diagnostic, buildRouteManifest } from "@mindees/compiler";
+
+//#region src/build.d.ts
+/** Options for {@link buildProject}. */
+interface BuildOptions {
+  /** Project root (contains `src/`). Default `"."`. */
+  root?: string;
+  /** Output directory. Default `"dist"`. */
+  outDir?: string;
+  /** Emit source maps. Default `true`. */
+  sourceMap?: boolean;
+}
+/** Result of a project build. */
+interface BuildResult {
+  ok: boolean;
+  /** Source files compiled (relative paths), sorted. */
+  compiled: string[];
+  /** All diagnostics across modules (errors fail the build). */
+  diagnostics: Diagnostic[];
+  /** Route manifest, if `src/routes/` existed. */
+  routes?: ReturnType<typeof buildRouteManifest>;
+  /** Optimizer totals across all modules. */
+  stats: {
+    flattenedNodes: number;
+    totalElements: number;
+  };
+}
+/**
+ * Build the project at `root`. Compiles every `src/**\/*.{ts,tsx}` (except
+ * `.d.ts`) and writes outputs to `outDir`. Stops emitting a module on type
+ * errors but collects diagnostics from all modules so the report is complete.
+ */
+declare function buildProject(fs: FileSystem, options?: BuildOptions): BuildResult;
+//#endregion
+export { BuildOptions, BuildResult, buildProject };
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","names":[],"sources":["../src/build.ts"],"mappings":";;;;AA6CA;AAAA,UAViB,YAAA;;EAEf,IAAA;EAe2B;EAb3B,MAAA;EAamB;EAXnB,SAAA;AAAA;;UAIe,WAAA;EACf,EAAA;EAMA;EAJA,QAAA;EAI2B;EAF3B,WAAA,EAAa,UAAA;EAIJ;EAFT,MAAA,GAAS,UAAA,QAAkB,kBAAA;EAEmB;EAA9C,KAAA;IAAS,cAAA;IAAwB,aAAA;EAAA;AAAA;;;;;;iBAWnB,YAAA,CAAa,EAAA,EAAI,UAAA,EAAY,OAAA,GAAS,YAAA,GAAoB,WAAA"}

package/dist/build.js

@@ -0,0 +1,97 @@
+import { buildRouteManifest, compile, typecheck } from "@mindees/compiler";
+//#region src/build.ts
+/**
+* `buildProject` — compile a project's sources with the Mindees Compiler.
+*
+* Walks `src/**` via an injected {@link FileSystem}, runs each TS/TSX module
+* through `@mindees/compiler`'s `typecheck` gate and then `compile` (emit),
+* writes the JS (and source map) to `dist/`, and — if a `src/routes/` dir
+* exists — emits a per-route manifest. Returns structured results so the CLI can
+* report diagnostics and fail the build on type errors.
+*
+* @module
+*/
+/**
+* Diagnostic codes that are artifacts of type-checking a module **in isolation**
+* (without the project's dependency graph or ambient JSX types), not real app
+* errors. If any ever reaches the build it is **downgraded to a warning** rather
+* than failing the build:
+*
+* - `TS2307` — "Cannot find module '…'": imports aren't resolved in single-module mode.
+* - `TS7026` — "no interface 'JSX.IntrinsicElements'": the framework's JSX env
+*   types aren't loaded in isolation.
+*
+* In practice the compiler's single-module gate already **filters** these upstream
+* (it drops unresolved-import codes and injects ambient JSX types), so they
+* normally don't appear here at all — this set is a defensive backstop in case a
+* future gate surfaces them. Genuine type errors (e.g. `TS2322` not-assignable)
+* are untouched and still fail the build. A full project-graph type-check is
+* future work (see ROADMAP).
+*/
+const ISOLATION_NOISE = new Set(["TS2307", "TS7026"]);
+const COMPILABLE = /\.(tsx|ts)$/;
+const DECLARATION = /\.d\.ts$/;
+/**
+* Build the project at `root`. Compiles every `src/**\/*.{ts,tsx}` (except
+* `.d.ts`) and writes outputs to `outDir`. Stops emitting a module on type
+* errors but collects diagnostics from all modules so the report is complete.
+*/
+function buildProject(fs, options = {}) {
+	const { root = ".", outDir = "dist", sourceMap = true } = options;
+	const srcDir = root === "." ? "src" : `${root}/src`;
+	const diagnostics = [];
+	const compiled = [];
+	const stats = {
+		flattenedNodes: 0,
+		totalElements: 0
+	};
+	const entries = fs.exists(srcDir) ? fs.readDir(srcDir) : [];
+	for (const rel of entries) {
+		if (!COMPILABLE.test(rel) || DECLARATION.test(rel)) continue;
+		const srcPath = `${srcDir}/${rel}`;
+		const source = fs.readFile(srcPath);
+		const moduleDiags = typecheck(source, rel).map((d) => d.severity === "error" && ISOLATION_NOISE.has(d.code) ? {
+			...d,
+			severity: "warning"
+		} : d);
+		diagnostics.push(...moduleDiags);
+		if (!moduleDiags.some((d) => d.severity === "error")) {
+			const emitted = compile(source, {
+				fileName: rel,
+				sourceMap
+			});
+			stats.flattenedNodes += emitted.stats.flattenedNodes;
+			stats.totalElements += emitted.stats.totalElements;
+			const outPath = `${outDir}/${rel.replace(COMPILABLE, ".js")}`;
+			fs.writeFile(outPath, emitted.code);
+			if (emitted.map) fs.writeFile(`${outPath}.map`, emitted.map);
+			compiled.push(rel);
+		}
+	}
+	let routes;
+	const routesDir = `${srcDir}/routes`;
+	if (fs.exists(routesDir)) try {
+		routes = buildRouteManifest(fs.readDir(routesDir));
+		fs.writeFile(`${outDir}/routes.manifest.json`, `${JSON.stringify(routes, null, 2)}\n`);
+	} catch (e) {
+		diagnostics.push({
+			severity: "error",
+			code: "MDC_ROUTES",
+			message: e instanceof Error ? e.message : String(e),
+			file: routesDir
+		});
+	}
+	compiled.sort();
+	const result = {
+		ok: !diagnostics.some((d) => d.severity === "error"),
+		compiled,
+		diagnostics,
+		stats
+	};
+	if (routes) result.routes = routes;
+	return result;
+}
+//#endregion
+export { buildProject };
+
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","names":[],"sources":["../src/build.ts"],"sourcesContent":["/**\n * `buildProject` — compile a project's sources with the Mindees Compiler.\n *\n * Walks `src/**` via an injected {@link FileSystem}, runs each TS/TSX module\n * through `@mindees/compiler`'s `typecheck` gate and then `compile` (emit),\n * writes the JS (and source map) to `dist/`, and — if a `src/routes/` dir\n * exists — emits a per-route manifest. Returns structured results so the CLI can\n * report diagnostics and fail the build on type errors.\n *\n * @module\n */\n\nimport { buildRouteManifest, compile, type Diagnostic, typecheck } from '@mindees/compiler'\nimport type { FileSystem } from './fs'\n\n/**\n * Diagnostic codes that are artifacts of type-checking a module **in isolation**\n * (without the project's dependency graph or ambient JSX types), not real app\n * errors. If any ever reaches the build it is **downgraded to a warning** rather\n * than failing the build:\n *\n * - `TS2307` — \"Cannot find module '…'\": imports aren't resolved in single-module mode.\n * - `TS7026` — \"no interface 'JSX.IntrinsicElements'\": the framework's JSX env\n *   types aren't loaded in isolation.\n *\n * In practice the compiler's single-module gate already **filters** these upstream\n * (it drops unresolved-import codes and injects ambient JSX types), so they\n * normally don't appear here at all — this set is a defensive backstop in case a\n * future gate surfaces them. Genuine type errors (e.g. `TS2322` not-assignable)\n * are untouched and still fail the build. A full project-graph type-check is\n * future work (see ROADMAP).\n */\nconst ISOLATION_NOISE = new Set(['TS2307', 'TS7026'])\n\n/** Options for {@link buildProject}. */\nexport interface BuildOptions {\n  /** Project root (contains `src/`). Default `\".\"`. */\n  root?: string\n  /** Output directory. Default `\"dist\"`. */\n  outDir?: string\n  /** Emit source maps. Default `true`. */\n  sourceMap?: boolean\n}\n\n/** Result of a project build. */\nexport interface BuildResult {\n  ok: boolean\n  /** Source files compiled (relative paths), sorted. */\n  compiled: string[]\n  /** All diagnostics across modules (errors fail the build). */\n  diagnostics: Diagnostic[]\n  /** Route manifest, if `src/routes/` existed. */\n  routes?: ReturnType<typeof buildRouteManifest>\n  /** Optimizer totals across all modules. */\n  stats: { flattenedNodes: number; totalElements: number }\n}\n\nconst COMPILABLE = /\\.(tsx|ts)$/\nconst DECLARATION = /\\.d\\.ts$/\n\n/**\n * Build the project at `root`. Compiles every `src/**\\/*.{ts,tsx}` (except\n * `.d.ts`) and writes outputs to `outDir`. Stops emitting a module on type\n * errors but collects diagnostics from all modules so the report is complete.\n */\nexport function buildProject(fs: FileSystem, options: BuildOptions = {}): BuildResult {\n  const { root = '.', outDir = 'dist', sourceMap = true } = options\n  const srcDir = root === '.' ? 'src' : `${root}/src`\n\n  const diagnostics: Diagnostic[] = []\n  const compiled: string[] = []\n  const stats = { flattenedNodes: 0, totalElements: 0 }\n\n  const entries = fs.exists(srcDir) ? fs.readDir(srcDir) : []\n  for (const rel of entries) {\n    if (!COMPILABLE.test(rel) || DECLARATION.test(rel)) continue\n    const srcPath = `${srcDir}/${rel}`\n    const source = fs.readFile(srcPath)\n\n    // Type-check for diagnostics, but downgrade isolation-only noise to warnings\n    // so a normal app (with cross-module imports + JSX) still builds. Genuine\n    // type errors remain errors and fail the build below.\n    const moduleDiags = typecheck(source, rel).map((d) =>\n      d.severity === 'error' && ISOLATION_NOISE.has(d.code)\n        ? { ...d, severity: 'warning' as const }\n        : d,\n    )\n    diagnostics.push(...moduleDiags)\n\n    // Emit only if this module has no real (post-downgrade) error.\n    const moduleHasError = moduleDiags.some((d) => d.severity === 'error')\n    if (!moduleHasError) {\n      const emitted = compile(source, { fileName: rel, sourceMap })\n      stats.flattenedNodes += emitted.stats.flattenedNodes\n      stats.totalElements += emitted.stats.totalElements\n      const outPath = `${outDir}/${rel.replace(COMPILABLE, '.js')}`\n      fs.writeFile(outPath, emitted.code)\n      if (emitted.map) fs.writeFile(`${outPath}.map`, emitted.map)\n      compiled.push(rel)\n    }\n  }\n\n  // Per-route manifest, if a routes dir is present. buildRouteManifest THROWS on\n  // a malformed routes dir (duplicate route path, or a non-terminal catch-all) —\n  // ordinary user misconfigurations that `mindees build` exists to report. Turn\n  // them into a build diagnostic + failing result so the CLI prints a clean error\n  // and exits non-zero, honoring runCli's \"never throws for expected failures\"\n  // contract instead of crashing with a raw stack trace.\n  let routes: BuildResult['routes']\n  const routesDir = `${srcDir}/routes`\n  if (fs.exists(routesDir)) {\n    try {\n      routes = buildRouteManifest(fs.readDir(routesDir))\n      fs.writeFile(`${outDir}/routes.manifest.json`, `${JSON.stringify(routes, null, 2)}\\n`)\n    } catch (e) {\n      diagnostics.push({\n        severity: 'error',\n        code: 'MDC_ROUTES',\n        message: e instanceof Error ? e.message : String(e),\n        file: routesDir,\n      })\n    }\n  }\n\n  compiled.sort()\n  const ok = !diagnostics.some((d) => d.severity === 'error')\n  const result: BuildResult = { ok, compiled, diagnostics, stats }\n  if (routes) result.routes = routes\n  return result\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAM,kBAAkB,IAAI,IAAI,CAAC,UAAU,QAAQ,CAAC;AAyBpD,MAAM,aAAa;AACnB,MAAM,cAAc;;;;;;AAOpB,SAAgB,aAAa,IAAgB,UAAwB,CAAC,GAAgB;CACpF,MAAM,EAAE,OAAO,KAAK,SAAS,QAAQ,YAAY,SAAS;CAC1D,MAAM,SAAS,SAAS,MAAM,QAAQ,GAAG,KAAK;CAE9C,MAAM,cAA4B,CAAC;CACnC,MAAM,WAAqB,CAAC;CAC5B,MAAM,QAAQ;EAAE,gBAAgB;EAAG,eAAe;CAAE;CAEpD,MAAM,UAAU,GAAG,OAAO,MAAM,IAAI,GAAG,QAAQ,MAAM,IAAI,CAAC;CAC1D,KAAK,MAAM,OAAO,SAAS;EACzB,IAAI,CAAC,WAAW,KAAK,GAAG,KAAK,YAAY,KAAK,GAAG,GAAG;EACpD,MAAM,UAAU,GAAG,OAAO,GAAG;EAC7B,MAAM,SAAS,GAAG,SAAS,OAAO;EAKlC,MAAM,cAAc,UAAU,QAAQ,GAAG,EAAE,KAAK,MAC9C,EAAE,aAAa,WAAW,gBAAgB,IAAI,EAAE,IAAI,IAChD;GAAE,GAAG;GAAG,UAAU;EAAmB,IACrC,CACN;EACA,YAAY,KAAK,GAAG,WAAW;EAI/B,IAAI,CADmB,YAAY,MAAM,MAAM,EAAE,aAAa,OAC5C,GAAG;GACnB,MAAM,UAAU,QAAQ,QAAQ;IAAE,UAAU;IAAK;GAAU,CAAC;GAC5D,MAAM,kBAAkB,QAAQ,MAAM;GACtC,MAAM,iBAAiB,QAAQ,MAAM;GACrC,MAAM,UAAU,GAAG,OAAO,GAAG,IAAI,QAAQ,YAAY,KAAK;GAC1D,GAAG,UAAU,SAAS,QAAQ,IAAI;GAClC,IAAI,QAAQ,KAAK,GAAG,UAAU,GAAG,QAAQ,OAAO,QAAQ,GAAG;GAC3D,SAAS,KAAK,GAAG;EACnB;CACF;CAQA,IAAI;CACJ,MAAM,YAAY,GAAG,OAAO;CAC5B,IAAI,GAAG,OAAO,SAAS,GACrB,IAAI;EACF,SAAS,mBAAmB,GAAG,QAAQ,SAAS,CAAC;EACjD,GAAG,UAAU,GAAG,OAAO,wBAAwB,GAAG,KAAK,UAAU,QAAQ,MAAM,CAAC,EAAE,GAAG;CACvF,SAAS,GAAG;EACV,YAAY,KAAK;GACf,UAAU;GACV,MAAM;GACN,SAAS,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC;GAClD,MAAM;EACR,CAAC;CACH;CAGF,SAAS,KAAK;CAEd,MAAM,SAAsB;EAAE,IAAA,CADlB,YAAY,MAAM,MAAM,EAAE,aAAa,OAAO;EACxB;EAAU;EAAa;CAAM;CAC/D,IAAI,QAAQ,OAAO,SAAS;CAC5B,OAAO;AACT"}

package/dist/cli.d.ts

@@ -0,0 +1,32 @@
+import { CommandResult, EnvProbe, Writer } from "./types.js";
+import { FileSystem } from "./fs.js";
+import { AiBackend } from "@mindees/ai";
+
+//#region src/cli.d.ts
+/** Everything the CLI needs from the outside world (injected for testability). */
+interface CliContext {
+  fs: FileSystem;
+  env: EnvProbe;
+  /** Working directory (where `create` writes, what `build` reads). */
+  cwd: string;
+  /** CLI version string (from package metadata). */
+  version: string;
+  /** Output sink. */
+  write: Writer;
+  /** AI backend for `ai` commands (wired from `MINDEES_AI_*` env in `bin`). */
+  aiBackend?: AiBackend;
+}
+/**
+ * Run the CLI. Returns a {@link CommandResult} with the process exit code.
+ * Never throws for expected failures — it reports them and returns non-zero.
+ */
+declare function runCli(argv: readonly string[], ctx: CliContext): CommandResult;
+/**
+ * The async CLI entry. Handles the model-calling `ai` command (which is asynchronous) and
+ * delegates every synchronous command to {@link runCli}. The `bin` calls this; tests can call
+ * either (sync commands stay testable through `runCli`).
+ */
+declare function runCliAsync(argv: readonly string[], ctx: CliContext): Promise<CommandResult>;
+//#endregion
+export { CliContext, runCli, runCliAsync };
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","names":[],"sources":["../src/cli.ts"],"mappings":";;;;;;UAwBiB,UAAA;EACf,EAAA,EAAI,UAAA;EACJ,GAAA,EAAK,QAAA;EAAA;EAEL,GAAA;EAEA;EAAA,OAAA;EAEO;EAAP,KAAA,EAAO,MAAA;EAEK;EAAZ,SAAA,GAAY,SAAA;AAAA;AAqCd;;;;AAAA,iBAAgB,MAAA,CAAO,IAAA,qBAAyB,GAAA,EAAK,UAAA,GAAa,aAAa;;;;;AAAA;iBAmC/D,WAAA,CAAY,IAAA,qBAAyB,GAAA,EAAK,UAAA,GAAa,OAAA,CAAQ,aAAA"}