@macroscope/cli 0.0.0

package/dist/cli.js

@@ -0,0 +1,1473 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/core/handler.ts
+function isHandler(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  if (typeof v.kind !== "string" || v.kind.length === 0) return false;
+  for (const method of ["render", "test", "build", "scaffold", "describe"]) {
+    if (v[method] !== void 0 && typeof v[method] !== "function") return false;
+  }
+  if (v.views !== void 0) {
+    if (typeof v.views !== "object" || v.views === null) return false;
+    for (const [, spec] of Object.entries(v.views)) {
+      if (!isViewSpec(spec)) return false;
+    }
+  }
+  return true;
+}
+function isViewSpec(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  switch (v.type) {
+    case "iframe":
+      if (typeof v.url !== "string" && typeof v.url !== "function") return false;
+      if (v.service !== void 0 && !isServiceSpec(v.service)) return false;
+      return true;
+    case "terminal":
+      return typeof v.command === "function" || Array.isArray(v.command) && v.command.every((c) => typeof c === "string");
+    case "hybrid": {
+      const urlOk = typeof v.url === "string" || typeof v.url === "function";
+      const commandOk = typeof v.command === "function" || Array.isArray(v.command) && v.command.every((c) => typeof c === "string");
+      if (!urlOk || !commandOk) return false;
+      for (const key of ["runLabel", "codeLabel", "terminalLabel"]) {
+        if (v[key] !== void 0 && typeof v[key] !== "string") return false;
+      }
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+function isServiceSpec(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  const commandOk = typeof v.command === "function" || Array.isArray(v.command) && v.command.every((c) => typeof c === "string");
+  if (!commandOk) return false;
+  if (typeof v.readyWhen !== "object" || v.readyWhen === null) return false;
+  const ready = v.readyWhen;
+  if (typeof ready.url !== "string") return false;
+  if (v.name !== void 0 && typeof v.name !== "string") return false;
+  if (v.cwd !== void 0 && typeof v.cwd !== "string" && typeof v.cwd !== "function") {
+    return false;
+  }
+  if (v.startupTimeoutMs !== void 0 && typeof v.startupTimeoutMs !== "number") return false;
+  return true;
+}
+var init_handler = __esm({
+  "src/core/handler.ts"() {
+    "use strict";
+  }
+});
+
+// src/core/blueprints.ts
+import { existsSync } from "fs";
+import { readdir } from "fs/promises";
+import { join } from "path";
+import { createJiti } from "jiti";
+async function loadBlueprints(project) {
+  const blueprintsDir = join(project.root, ".macroscope", "blueprints");
+  if (!existsSync(blueprintsDir)) {
+    return { blueprints: [], errors: [] };
+  }
+  let entries;
+  try {
+    entries = await readdir(blueprintsDir, { withFileTypes: true, encoding: "utf8" });
+  } catch {
+    return { blueprints: [], errors: [] };
+  }
+  const blueprints = [];
+  const errors = [];
+  const jiti = createJiti(import.meta.url);
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const folder = join(blueprintsDir, entry.name);
+    const kind = entry.name.normalize("NFC");
+    const result = await loadOne(folder, kind, jiti);
+    if (result.ok) {
+      blueprints.push(result.blueprint);
+    } else {
+      errors.push(result.error);
+    }
+  }
+  blueprints.sort((a, b) => a.kind < b.kind ? -1 : 1);
+  errors.sort((a, b) => a.kind < b.kind ? -1 : 1);
+  return { blueprints, errors };
+}
+async function loadOne(folder, kind, jiti) {
+  let file = null;
+  for (const filename of HANDLER_FILENAMES) {
+    const candidate = join(folder, filename);
+    if (existsSync(candidate)) {
+      file = candidate;
+      break;
+    }
+  }
+  if (!file) {
+    return {
+      ok: false,
+      error: {
+        folder,
+        kind,
+        cause: "no-handler-file",
+        message: `Blueprint folder ${folder} has no handler file. Expected one of: ${HANDLER_FILENAMES.join(", ")}.`
+      }
+    };
+  }
+  let mod;
+  try {
+    mod = await jiti.import(file);
+  } catch (err) {
+    return {
+      ok: false,
+      error: {
+        folder,
+        kind,
+        cause: "import-failed",
+        message: `Failed to import ${file}: ${err.message}`
+      }
+    };
+  }
+  const def = extractDefault(mod);
+  if (def === void 0) {
+    return {
+      ok: false,
+      error: {
+        folder,
+        kind,
+        cause: "no-default-export",
+        message: `Blueprint at ${file} has no default export. Use \`export default { kind: '${kind}', ... } satisfies Handler\`.`
+      }
+    };
+  }
+  if (!isHandler(def)) {
+    return {
+      ok: false,
+      error: {
+        folder,
+        kind,
+        cause: "invalid-handler-shape",
+        message: `Default export of ${file} is not a valid Handler. It must be an object with a non-empty string \`kind\` field and optional async methods (render, test, build, scaffold, describe).`
+      }
+    };
+  }
+  if (def.kind !== kind) {
+    return {
+      ok: false,
+      error: {
+        folder,
+        kind,
+        cause: "kind-mismatch",
+        message: `Blueprint at ${file} declares \`kind: '${def.kind}'\` but lives in folder \`${kind}/\`. The kind field must match the folder name.`
+      }
+    };
+  }
+  const handlerRecord = def;
+  const capabilities = OPERATION_NAMES.filter((op) => typeof handlerRecord[op] === "function");
+  return {
+    ok: true,
+    blueprint: { kind: def.kind, folder, file, handler: def, capabilities }
+  };
+}
+function extractDefault(mod) {
+  if (mod === null || mod === void 0) return void 0;
+  if (typeof mod !== "object") return mod;
+  if (!Object.prototype.hasOwnProperty.call(mod, "default")) return void 0;
+  return mod.default;
+}
+var HANDLER_FILENAMES, OPERATION_NAMES;
+var init_blueprints = __esm({
+  "src/core/blueprints.ts"() {
+    "use strict";
+    init_handler();
+    HANDLER_FILENAMES = ["handler.ts", "handler.mjs", "handler.js"];
+    OPERATION_NAMES = ["render", "test", "build", "scaffold", "describe"];
+  }
+});
+
+// src/core/project.ts
+import { existsSync as existsSync2 } from "fs";
+import { readFile } from "fs/promises";
+import { dirname, join as join2, resolve } from "path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+async function findProject(cwd = process.cwd()) {
+  const startedFrom = resolve(cwd);
+  let current = startedFrom;
+  while (true) {
+    if (existsSync2(join2(current, ".macroscope"))) {
+      return { root: current, config: await loadConfig(current) };
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      throw new ProjectNotFoundError(startedFrom);
+    }
+    current = parent;
+  }
+}
+async function loadConfig(root) {
+  const configPath = join2(root, ".macroscope", "config.yaml");
+  if (!existsSync2(configPath)) {
+    return projectConfigSchema.parse({});
+  }
+  const raw = await readFile(configPath, "utf8");
+  let parsed;
+  try {
+    parsed = parseYaml(raw) ?? {};
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to parse ${configPath}: ${msg}`);
+  }
+  const result = projectConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new Error(`Invalid project config at ${configPath}:
+${issues}`);
+  }
+  return result.data;
+}
+var projectConfigSchema, ProjectNotFoundError;
+var init_project = __esm({
+  "src/core/project.ts"() {
+    "use strict";
+    projectConfigSchema = z.object({
+      scanRoots: z.array(z.string()).default(["."]),
+      ignore: z.array(z.string()).default(["node_modules", ".git", "dist", ".macroscope"])
+    });
+    ProjectNotFoundError = class extends Error {
+      constructor(startedFrom) {
+        super(
+          `No macroscope project found. Walked up from ${startedFrom} looking for a .macroscope/ directory but reached the filesystem root. Run \`npm create macroscope\` to scaffold one, or cd into an existing project.`
+        );
+        this.name = "ProjectNotFoundError";
+      }
+    };
+  }
+});
+
+// ../contracts/dist/index.js
+import { z as z2 } from "zod";
+import { z as z22 } from "zod";
+import { z as z3 } from "zod";
+import { z as z4 } from "zod";
+import { z as z5 } from "zod";
+var BlockManifestSchema, SymbolSignatureSchema, UploadPayloadSchema, MeilisearchDocSchema, BlockHitSchema, CodeMatchSchema, IndexBatchRequestSchema, IndexBatchResponseSchema, SearchRequestSchema, SearchResponseSchema, DeleteIndexResponseSchema, ScopeTouchRequestSchema, ScopeTouchResponseSchema, HealthResponseSchema, ErrorEnvelopeSchema;
+var init_dist = __esm({
+  "../contracts/dist/index.js"() {
+    "use strict";
+    BlockManifestSchema = z2.object({
+      /** Must reference a registered blueprint's `kind`. */
+      kind: z2.string().min(1),
+      /** Optional override for the auto-derived block id (POSIX relative path). */
+      id: z2.string().optional(),
+      name: z2.string().optional(),
+      description: z2.string().optional(),
+      tags: z2.array(z2.string()).optional(),
+      source: z2.string().optional(),
+      preview: z2.string().optional(),
+      docs: z2.string().optional(),
+      tests: z2.union([z2.string(), z2.array(z2.string())]).optional()
+    }).passthrough();
+    SymbolSignatureSchema = z22.object({
+      name: z22.string().min(1),
+      kind: z22.string().min(1),
+      signature: z22.string()
+    });
+    UploadPayloadSchema = z22.object({
+      /** Stable block id (POSIX relative path or manifest `id` override). */
+      blockId: z22.string().min(1),
+      kind: z22.string().min(1),
+      name: z22.string().optional(),
+      description: z22.string().optional(),
+      tags: z22.array(z22.string()).optional(),
+      /** Exported symbols extracted from the block's source files. */
+      symbols: z22.array(SymbolSignatureSchema),
+      /** First ~500 chars of the README, if any. */
+      readmeExcerpt: z22.string().optional()
+    });
+    MeilisearchDocSchema = UploadPayloadSchema.extend({
+      /** SHA-256 over the canonical JSON of the UploadPayload (see T6). */
+      contentHash: z22.string().min(1),
+      /** Git remote URL (normalised) or local repo name when no remote exists. */
+      repo: z22.string().min(1),
+      /** hash(machineUuid + absolutePath) — see ARCHITECTURE.md. */
+      worktreeId: z22.string().min(1),
+      /** POSIX path from the worktree root to the block folder. */
+      path: z22.string().min(1),
+      /** Unix epoch milliseconds. Refreshed on every push and by `/scope/touch`. */
+      lastActiveAt: z22.number().int().nonnegative()
+    });
+    BlockHitSchema = z3.object({
+      blockId: z3.string().min(1),
+      kind: z3.string().min(1),
+      name: z3.string().optional(),
+      description: z3.string().optional(),
+      repo: z3.string().min(1),
+      worktreeId: z3.string().min(1),
+      path: z3.string().min(1),
+      /** Relevance score from Meilisearch hybrid ranking. Larger = more relevant. */
+      score: z3.number()
+    });
+    CodeMatchSchema = z3.object({
+      /** POSIX path from the worktree root. */
+      file: z3.string().min(1),
+      /** 1-based line number. */
+      line: z3.number().int().positive(),
+      /** 1-based column number, when available. */
+      column: z3.number().int().positive().optional(),
+      /** A single line of source text containing the match. */
+      preview: z3.string()
+    });
+    IndexBatchRequestSchema = z4.object({
+      /** Per-block docs to upsert. The cloud routes these to the user's Meilisearch index. */
+      upserts: z4.array(MeilisearchDocSchema),
+      /** Block ids to delete. Empty array is valid (upsert-only batch). */
+      deletes: z4.array(z4.string().min(1))
+    });
+    IndexBatchResponseSchema = z4.object({
+      /** Unix epoch ms of server-side acknowledgement. */
+      acceptedAt: z4.number().int().nonnegative(),
+      /** Number of upserts accepted (deletes excluded). */
+      accepted: z4.number().int().nonnegative()
+    });
+    SearchRequestSchema = z4.object({
+      q: z4.string().min(1),
+      /** Restrict to one worktree. Omit to search across all of the user's worktrees. */
+      worktreeId: z4.string().optional(),
+      /** Restrict to one repo. */
+      repo: z4.string().optional(),
+      /** Restrict to one block kind. */
+      kind: z4.string().optional(),
+      /** Cap on returned hits. Server enforces an upper bound. */
+      limit: z4.number().int().positive().optional()
+    });
+    SearchResponseSchema = z4.object({
+      hits: z4.array(BlockHitSchema),
+      /** Approximate total match count from Meilisearch (estimated, not exact). */
+      totalEstimated: z4.number().int().nonnegative()
+    });
+    DeleteIndexResponseSchema = z4.object({
+      deletedAt: z4.number().int().nonnegative()
+    });
+    ScopeTouchRequestSchema = z4.object({
+      worktreeId: z4.string().min(1),
+      repo: z4.string().min(1)
+    });
+    ScopeTouchResponseSchema = z4.object({
+      touchedAt: z4.number().int().nonnegative()
+    });
+    HealthResponseSchema = z4.object({
+      status: z4.literal("ok"),
+      schemaVersion: z4.number().int().positive()
+    });
+    ErrorEnvelopeSchema = z5.object({
+      error: z5.object({
+        /** Stable machine-readable code (e.g. `unauthorized`, `validation_failed`). */
+        code: z5.string().min(1),
+        /** Human-readable message. */
+        message: z5.string().min(1),
+        /** Source file path when the error originates from parsing a manifest or other on-disk artifact. Set by the CLI side (see `ScanError`) and by the cloud when validating uploaded manifests. */
+        file: z5.string().optional(),
+        /** Path of the offending field when the error is validation-related. */
+        field: z5.string().optional(),
+        /** Server-assigned request id for log correlation. */
+        requestId: z5.string().optional()
+      })
+    });
+  }
+});
+
+// src/core/manifest.ts
+var manifestSchema;
+var init_manifest = __esm({
+  "src/core/manifest.ts"() {
+    "use strict";
+    init_dist();
+    manifestSchema = BlockManifestSchema;
+  }
+});
+
+// src/core/scanner.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync3 } from "fs";
+import { readFile as readFile2, readdir as readdir2 } from "fs/promises";
+import { dirname as dirname2, join as join3, relative, sep } from "path";
+import { parse as parseYaml2 } from "yaml";
+async function scan(project) {
+  const blocks = [];
+  const errors = [];
+  const ignore = new Set(project.config.ignore);
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const root of project.config.scanRoots) {
+    const start = join3(project.root, root);
+    if (!existsSync3(start)) continue;
+    for await (const manifestPath of findManifests(start, ignore)) {
+      const result = await parseBlock(manifestPath, project.root);
+      if (result.kind === "ok") {
+        if (seenIds.has(result.block.id)) {
+          errors.push({
+            file: manifestPath,
+            kind: "validation",
+            message: `Duplicate block id "${result.block.id}" at ${manifestPath}. Set an explicit \`id:\` field to disambiguate.`,
+            field: "id"
+          });
+        } else {
+          seenIds.add(result.block.id);
+          blocks.push(result.block);
+        }
+      } else {
+        errors.push(result.error);
+      }
+    }
+  }
+  blocks.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  return { blocks, errors };
+}
+async function* findManifests(dir, ignore) {
+  let entries;
+  try {
+    entries = await readdir2(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name === "macroscope.yaml") {
+      yield join3(dir, entry.name);
+    }
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (ignore.has(entry.name)) continue;
+    yield* findManifests(join3(dir, entry.name), ignore);
+  }
+}
+async function parseBlock(manifestPath, projectRoot) {
+  let raw;
+  try {
+    raw = await readFile2(manifestPath, "utf8");
+  } catch (err) {
+    return {
+      kind: "err",
+      error: {
+        file: manifestPath,
+        kind: "io",
+        message: `Failed to read manifest at ${manifestPath}: ${err.message}`
+      }
+    };
+  }
+  let yamlValue;
+  try {
+    yamlValue = parseYaml2(raw);
+  } catch (err) {
+    return {
+      kind: "err",
+      error: {
+        file: manifestPath,
+        kind: "parse",
+        message: `Invalid YAML in ${manifestPath}: ${err.message}`
+      }
+    };
+  }
+  const parsed = manifestSchema.safeParse(yamlValue);
+  if (!parsed.success) {
+    const first = firstZodIssue(parsed.error);
+    return {
+      kind: "err",
+      error: {
+        file: manifestPath,
+        kind: "validation",
+        message: `Manifest at ${manifestPath} is invalid: field \`${first.fieldPath}\` ${first.message}.`,
+        field: first.fieldPath
+      }
+    };
+  }
+  const manifest = parsed.data;
+  const blockDir = dirname2(manifestPath);
+  const defaultId = toPosix(relative(projectRoot, blockDir));
+  const id = manifest.id ?? defaultId;
+  const contentHash = createHash("sha256").update(raw).digest("hex");
+  return {
+    kind: "ok",
+    block: { id, path: blockDir, manifest, contentHash }
+  };
+}
+function firstZodIssue(err) {
+  const issue = err.issues[0];
+  if (!issue) return { fieldPath: "(root)", message: "unknown validation error" };
+  const fieldPath = issue.path.length ? issue.path.join(".") : "(root)";
+  return { fieldPath, message: issue.message.toLowerCase() };
+}
+function toPosix(p) {
+  return p.split(sep).join("/");
+}
+var init_scanner = __esm({
+  "src/core/scanner.ts"() {
+    "use strict";
+    init_manifest();
+  }
+});
+
+// src/ui/api/terminal-resolver.ts
+async function resolveTerminalCommand(cwd, blockId, viewKey) {
+  let project;
+  try {
+    project = await findProject(cwd);
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) {
+      return { ok: false, error: err.message };
+    }
+    return { ok: false, error: err.message };
+  }
+  const [scanResult, blueprintResult] = await Promise.all([scan(project), loadBlueprints(project)]);
+  const block = scanResult.blocks.find((b) => b.id === blockId);
+  if (!block) {
+    return { ok: false, error: `No block found with id "${blockId}".` };
+  }
+  const blueprint = blueprintResult.blueprints.find((bp) => bp.kind === block.manifest.kind);
+  if (!blueprint) {
+    return { ok: false, error: `No blueprint registered for kind "${block.manifest.kind}".` };
+  }
+  const spec = blueprint.handler.views?.[viewKey];
+  if (!spec) {
+    return { ok: false, error: `Blueprint "${blueprint.kind}" has no view named "${viewKey}".` };
+  }
+  if (spec.type !== "terminal" && spec.type !== "hybrid") {
+    return {
+      ok: false,
+      error: `View "${viewKey}" on "${blueprint.kind}" has no terminal command.`
+    };
+  }
+  const blockInput = { id: block.id, path: block.path, manifest: block.manifest };
+  let command;
+  if (Array.isArray(spec.command)) {
+    command = spec.command;
+  } else {
+    try {
+      command = await withTimeout2(spec.command(blockInput), COMMAND_RESOLVE_TIMEOUT_MS);
+    } catch (err) {
+      return { ok: false, error: `Command resolver failed: ${err.message}` };
+    }
+    if (!Array.isArray(command) || !command.every((c) => typeof c === "string")) {
+      return { ok: false, error: "Command resolver did not return a string[]." };
+    }
+  }
+  return { ok: true, command, cwd: project.root };
+}
+function withTimeout2(p, ms) {
+  return Promise.race([
+    p,
+    new Promise(
+      (_, reject) => setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms)
+    )
+  ]);
+}
+var COMMAND_RESOLVE_TIMEOUT_MS;
+var init_terminal_resolver = __esm({
+  "src/ui/api/terminal-resolver.ts"() {
+    "use strict";
+    init_blueprints();
+    init_project();
+    init_scanner();
+    COMMAND_RESOLVE_TIMEOUT_MS = 5e3;
+  }
+});
+
+// src/ui/api/terminal-ws.ts
+var terminal_ws_exports = {};
+__export(terminal_ws_exports, {
+  attachTerminalWs: () => attachTerminalWs,
+  setSpawnOverride: () => setSpawnOverride
+});
+import { spawn } from "child_process";
+import { WebSocketServer } from "ws";
+function setSpawnOverride(override) {
+  spawnOverride = override;
+}
+function attachTerminalWs(httpServer, defaultCwd) {
+  const wss = new WebSocketServer({ noServer: true });
+  httpServer.on("upgrade", (req, socket, head) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (url.pathname !== "/api/terminal") {
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      handleConnection(ws, req, defaultCwd);
+    });
+  });
+}
+async function handleConnection(ws, req, defaultCwd) {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const blockId = url.searchParams.get("blockId") ?? "";
+  const viewKey = url.searchParams.get("viewKey") ?? "";
+  let command;
+  let cwd;
+  if (spawnOverride) {
+    command = spawnOverride.command;
+    cwd = spawnOverride.cwd ?? defaultCwd;
+  } else {
+    const resolved = await resolveTerminalCommand(defaultCwd, blockId, viewKey);
+    if (!resolved.ok) {
+      send(ws, { type: "error", message: resolved.error });
+      ws.close();
+      return;
+    }
+    command = resolved.command;
+    cwd = resolved.cwd;
+  }
+  if (command.length === 0) {
+    send(ws, { type: "error", message: "empty command" });
+    ws.close();
+    return;
+  }
+  send(ws, { type: "open", command });
+  const [bin, ...args] = command;
+  let child;
+  try {
+    child = spawn(bin, args, { cwd, stdio: ["pipe", "pipe", "pipe"] });
+  } catch (err) {
+    send(ws, { type: "error", message: `failed to spawn: ${err.message}` });
+    ws.close();
+    return;
+  }
+  child.stdout?.on("data", (chunk) => send(ws, { type: "out", data: chunk.toString() }));
+  child.stderr?.on("data", (chunk) => send(ws, { type: "err", data: chunk.toString() }));
+  child.on("exit", (code, signal) => {
+    send(ws, { type: "close", code, signal });
+    ws.close();
+  });
+  child.on("error", (err) => {
+    send(ws, { type: "error", message: err.message });
+    ws.close();
+  });
+  ws.on("message", (raw) => {
+    let frame;
+    try {
+      frame = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+    if (frame.type === "in" && typeof frame.data === "string") {
+      child.stdin?.write(frame.data);
+    } else if (frame.type === "eof") {
+      child.stdin?.end();
+    }
+  });
+  ws.on("close", () => {
+    if (!child.killed) child.kill();
+  });
+}
+function send(ws, frame) {
+  try {
+    ws.send(JSON.stringify(frame));
+  } catch {
+  }
+}
+var spawnOverride;
+var init_terminal_ws = __esm({
+  "src/ui/api/terminal-ws.ts"() {
+    "use strict";
+    init_terminal_resolver();
+    spawnOverride = null;
+  }
+});
+
+// src/cli.ts
+init_blueprints();
+init_project();
+import { dirname as dirname3, resolve as resolve3 } from "path";
+import { fileURLToPath } from "url";
+import { Command } from "commander";
+import importLocal from "import-local";
+
+// src/core/version.ts
+var VERSION = "0.0.0";
+
+// src/ui/ui-server.ts
+import { existsSync as existsSync4 } from "fs";
+import { readFile as readFile5 } from "fs/promises";
+import { createServer } from "http";
+import { extname as extname2, join as join4, normalize, resolve as resolve2 } from "path";
+
+// src/ui/api/blocks-handler.ts
+init_blueprints();
+init_project();
+init_scanner();
+var URL_RESOLVE_TIMEOUT_MS = 5e3;
+async function handleBlocksRequest(cwd) {
+  try {
+    const project = await findProject(cwd);
+    const [scanResult, blueprintResult] = await Promise.all([
+      scan(project),
+      loadBlueprints(project)
+    ]);
+    const byKind = /* @__PURE__ */ new Map();
+    for (const bp of blueprintResult.blueprints) byKind.set(bp.kind, bp);
+    const blocks = await Promise.all(
+      scanResult.blocks.map(async (block) => ({
+        id: block.id,
+        path: block.path,
+        manifest: block.manifest,
+        contentHash: block.contentHash,
+        views: await resolveViewsWithTimeout(
+          block,
+          byKind.get(block.manifest.kind)?.handler,
+          URL_RESOLVE_TIMEOUT_MS
+        )
+      }))
+    );
+    return {
+      status: 200,
+      body: {
+        blocks,
+        errors: scanResult.errors,
+        blueprintErrors: blueprintResult.errors
+      }
+    };
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) {
+      return { status: 404, body: { error: err.message } };
+    }
+    return { status: 500, body: { error: err.message } };
+  }
+}
+async function resolveViewsWithTimeout(block, handler, timeoutMs = URL_RESOLVE_TIMEOUT_MS) {
+  if (!handler?.views) return [];
+  const blockInput = { id: block.id, path: block.path, manifest: block.manifest };
+  const resolved = [];
+  for (const [key, spec] of Object.entries(handler.views)) {
+    if (spec.type === "iframe") {
+      const service = spec.service ? { name: spec.service.name ?? firstArg(spec.service.command) } : null;
+      if (typeof spec.url === "string") {
+        resolved.push({ type: "iframe", key, label: titleize(key), url: spec.url, service });
+        continue;
+      }
+      try {
+        const url = await withTimeout(spec.url(blockInput), timeoutMs);
+        if (typeof url !== "string") continue;
+        resolved.push({ type: "iframe", key, label: titleize(key), url, service });
+      } catch {
+      }
+    } else if (spec.type === "terminal") {
+      resolved.push({ type: "terminal", key, label: titleize(key) });
+    } else if (spec.type === "hybrid") {
+      const runLabel = spec.runLabel ?? "Run";
+      const codeLabel = spec.codeLabel ?? "Code";
+      const terminalLabel = spec.terminalLabel ?? "Terminal";
+      if (typeof spec.url === "string") {
+        resolved.push({
+          type: "hybrid",
+          key,
+          label: titleize(key),
+          url: spec.url,
+          runLabel,
+          codeLabel,
+          terminalLabel
+        });
+        continue;
+      }
+      try {
+        const url = await withTimeout(spec.url(blockInput), timeoutMs);
+        if (typeof url !== "string") continue;
+        resolved.push({
+          type: "hybrid",
+          key,
+          label: titleize(key),
+          url,
+          runLabel,
+          codeLabel,
+          terminalLabel
+        });
+      } catch {
+      }
+    }
+  }
+  return resolved;
+}
+function withTimeout(promise, ms) {
+  return Promise.race([
+    promise,
+    new Promise(
+      (_, reject) => setTimeout(() => reject(new Error(`url resolver timed out after ${ms}ms`)), ms)
+    )
+  ]);
+}
+function titleize(key) {
+  return key.charAt(0).toUpperCase() + key.slice(1).replace(/-/g, " ");
+}
+function firstArg(command) {
+  if (Array.isArray(command)) return command[0] ?? "service";
+  return "service";
+}
+
+// src/ui/api/blueprints-handler.ts
+init_blueprints();
+init_project();
+async function handleBlueprintsRequest(cwd) {
+  try {
+    const project = await findProject(cwd);
+    const result = await loadBlueprints(project);
+    return {
+      status: 200,
+      body: {
+        blueprints: result.blueprints.map((b) => ({
+          kind: b.kind,
+          folder: b.folder,
+          file: b.file,
+          capabilities: b.capabilities
+        })),
+        errors: result.errors
+      }
+    };
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) {
+      return { status: 404, body: { error: err.message } };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { status: 500, body: { error: message } };
+  }
+}
+
+// src/ui/api/code-handler.ts
+import { readFile as readFile3 } from "fs/promises";
+import { extname } from "path";
+import { codeToHtml } from "shiki";
+var EXT_TO_LANG = {
+  ".ts": "typescript",
+  ".tsx": "tsx",
+  ".js": "javascript",
+  ".jsx": "jsx",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".json": "json",
+  ".css": "css",
+  ".html": "html",
+  ".md": "markdown",
+  ".yaml": "yaml",
+  ".yml": "yaml",
+  ".sh": "shell",
+  ".py": "python",
+  ".rs": "rust",
+  ".go": "go"
+};
+async function handleCodeRequest(absolutePath, language) {
+  let raw;
+  try {
+    raw = await readFile3(absolutePath, "utf8");
+  } catch {
+    return errorResponse(404, `File not found: ${absolutePath}`);
+  }
+  const lang = language ?? EXT_TO_LANG[extname(absolutePath).toLowerCase()] ?? "text";
+  try {
+    const inner = await codeToHtml(raw, { lang, theme: "github-dark" });
+    return {
+      status: 200,
+      contentType: "text/html; charset=utf-8",
+      body: wrap(inner)
+    };
+  } catch {
+    const fallback = `<pre>${escapeHtml(raw)}</pre>`;
+    return {
+      status: 200,
+      contentType: "text/html; charset=utf-8",
+      body: wrap(fallback)
+    };
+  }
+}
+function wrap(inner) {
+  return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>macroscope \xB7 code</title>
+  <style>
+    body { margin: 0; padding: 0; font-family: ui-monospace, SFMono-Regular, monospace; }
+    pre { margin: 0; padding: 1rem; overflow-x: auto; line-height: 1.5; font-size: 13px; }
+  </style>
+</head>
+<body>${inner}</body>
+</html>`;
+}
+function errorResponse(status, message) {
+  return {
+    status,
+    contentType: "text/html; charset=utf-8",
+    body: `<!doctype html><body><pre>${escapeHtml(message)}</pre></body>`
+  };
+}
+function escapeHtml(s) {
+  return s.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c] ?? c);
+}
+
+// src/ui/api/markdown-handler.ts
+import { readFile as readFile4 } from "fs/promises";
+import { marked } from "marked";
+async function handleMarkdownRequest(absolutePath) {
+  let raw;
+  try {
+    raw = await readFile4(absolutePath, "utf8");
+  } catch {
+    return errorResponse2(404, `File not found: ${absolutePath}`);
+  }
+  try {
+    const inner = await marked.parse(raw);
+    return {
+      status: 200,
+      contentType: "text/html; charset=utf-8",
+      body: wrap2(inner)
+    };
+  } catch (err) {
+    return errorResponse2(500, `Failed to render markdown: ${err.message}`);
+  }
+}
+function wrap2(inner) {
+  return `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>macroscope \xB7 markdown</title>
+  <style>
+    body { font-family: ui-sans-serif, system-ui, sans-serif; max-width: 760px; margin: 2rem auto; padding: 0 1rem; line-height: 1.6; color: #18181b; }
+    h1, h2, h3 { margin-top: 1.6em; }
+    code { background: #f4f4f5; padding: 0.1em 0.3em; border-radius: 3px; font-size: 0.9em; }
+    pre { background: #18181b; color: #fafafa; padding: 1em; border-radius: 6px; overflow-x: auto; }
+    pre code { background: transparent; padding: 0; color: inherit; }
+    a { color: #2563eb; }
+  </style>
+</head>
+<body>${inner}</body>
+</html>`;
+}
+function errorResponse2(status, message) {
+  return {
+    status,
+    contentType: "text/html; charset=utf-8",
+    body: `<!doctype html><body><pre>${escapeHtml2(message)}</pre></body>`
+  };
+}
+function escapeHtml2(s) {
+  return s.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c] ?? c);
+}
+
+// src/ui/api/service-manager.ts
+import { spawn as nodeSpawn } from "child_process";
+
+// src/ui/api/service-readiness.ts
+async function pollReadiness(url, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const intervalMs = opts.intervalMs ?? 250;
+  const fetchImpl = opts.fetch ?? fetch;
+  const deadline = Date.now() + timeoutMs;
+  let lastError = "";
+  while (Date.now() < deadline) {
+    if (opts.signal?.aborted) return { ready: false, aborted: true };
+    try {
+      const fetchPromise = fetchImpl(url, { signal: opts.signal });
+      let onAbort = null;
+      const signal = opts.signal;
+      const abortPromise = signal ? new Promise((_, reject) => {
+        onAbort = () => {
+          reject(new AbortError());
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+      }) : new Promise(() => {
+      });
+      try {
+        const res = await Promise.race([fetchPromise, abortPromise]);
+        if (res.status < 500) return { ready: true };
+        lastError = `status ${res.status}`;
+      } finally {
+        if (onAbort && opts.signal) opts.signal.removeEventListener("abort", onAbort);
+      }
+    } catch (err) {
+      if (opts.signal?.aborted || err instanceof AbortError) return { ready: false, aborted: true };
+      lastError = err instanceof Error ? err.message : String(err);
+    }
+    const result = await sleep(intervalMs, opts.signal);
+    if (result.aborted) return { ready: false, aborted: true };
+  }
+  return { ready: false, lastError };
+}
+var AbortError = class extends Error {
+  constructor() {
+    super("aborted");
+  }
+};
+function sleep(ms, signal) {
+  return new Promise((resolve4) => {
+    let onAbort = null;
+    const t = setTimeout(() => {
+      if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+      resolve4({ aborted: false });
+    }, ms);
+    if (signal?.aborted) {
+      clearTimeout(t);
+      resolve4({ aborted: true });
+      return;
+    }
+    onAbort = () => {
+      clearTimeout(t);
+      if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+      resolve4({ aborted: true });
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/ui/api/service-manager.ts
+var LOG_BUFFER_BYTES = 4096;
+var ServiceManager = class {
+  spawn;
+  poll;
+  services = /* @__PURE__ */ new Map();
+  constructor(deps = {}) {
+    this.spawn = deps.spawn ?? nodeSpawn;
+    this.poll = deps.pollReadiness ?? pollReadiness;
+  }
+  keyFor(input) {
+    return JSON.stringify({ command: input.command, cwd: input.cwd });
+  }
+  get(key) {
+    return this.services.get(key)?.state;
+  }
+  async ensure(input) {
+    const key = this.keyFor(input);
+    const existing = this.services.get(key);
+    if (existing) return existing.state;
+    if (input.probeFirst) {
+      const probe = await this.poll(input.readyUrl, { timeoutMs: 500, intervalMs: 100 });
+      if (probe.ready) {
+        const state2 = { status: "ready", logs: "", adopted: true };
+        this.services.set(key, { state: state2, abort: new AbortController() });
+        return state2;
+      }
+    }
+    const [bin, ...args] = input.command;
+    if (!bin) return { status: "failed", logs: "", message: "empty command" };
+    const abort = new AbortController();
+    const state = { status: "starting", logs: "" };
+    let child;
+    try {
+      child = this.spawn(bin, args, { cwd: input.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (err) {
+      return { status: "failed", logs: "", message: `spawn failed: ${err.message}` };
+    }
+    this.services.set(key, { state, child, abort });
+    const appendLog = (chunk) => {
+      state.logs = (state.logs + chunk.toString()).slice(-LOG_BUFFER_BYTES);
+    };
+    child.stdout?.on("data", appendLog);
+    child.stderr?.on("data", appendLog);
+    child.on("exit", (code) => {
+      if (state.status === "starting" || state.status === "ready") {
+        state.status = "failed";
+        state.message = `process exited with code ${code}`;
+        abort.abort();
+      }
+    });
+    child.on("error", (err) => {
+      if (state.status === "starting") {
+        state.status = "failed";
+        state.message = err.message;
+        abort.abort();
+      }
+    });
+    void this.poll(input.readyUrl, {
+      timeoutMs: input.startupTimeoutMs ?? 3e4,
+      signal: abort.signal
+    }).then((result) => {
+      if (state.status !== "starting") return;
+      if (result.ready) {
+        state.status = "ready";
+      } else if (!result.aborted) {
+        state.status = "failed";
+        state.message = `readiness check failed: ${result.lastError ?? "timeout"}`;
+        if (!child.killed) child.kill();
+      }
+    });
+    return state;
+  }
+  shutdown() {
+    for (const entry of this.services.values()) {
+      entry.abort.abort();
+      if (entry.child && !entry.child.killed) entry.child.kill();
+    }
+    this.services.clear();
+  }
+};
+
+// src/ui/api/services-handler.ts
+init_blueprints();
+init_project();
+init_scanner();
+async function handleServiceEnsureRequest(cwd, manager, input) {
+  if (!input.blockId || !input.viewKey) {
+    return { status: 400, body: { error: "blockId and viewKey are required" } };
+  }
+  try {
+    const project = await findProject(cwd);
+    const [scanResult, blueprintResult] = await Promise.all([
+      scan(project),
+      loadBlueprints(project)
+    ]);
+    const block = scanResult.blocks.find((b) => b.id === input.blockId);
+    if (!block) return { status: 404, body: { error: `unknown block: ${input.blockId}` } };
+    const bp = blueprintResult.blueprints.find((b) => b.kind === block.manifest.kind);
+    const viewSpec = bp?.handler.views?.[input.viewKey];
+    if (!viewSpec || viewSpec.type !== "iframe" || !viewSpec.service) {
+      return { status: 404, body: { error: `view ${input.viewKey} has no service` } };
+    }
+    const svc = viewSpec.service;
+    const blockInput = { id: block.id, path: block.path, manifest: block.manifest };
+    const command = typeof svc.command === "function" ? await svc.command(blockInput) : svc.command;
+    const cwdResolved = typeof svc.cwd === "function" ? await svc.cwd(blockInput) : svc.cwd ?? project.root;
+    const state = await manager.ensure({
+      command,
+      cwd: cwdResolved,
+      readyUrl: svc.readyWhen.url,
+      probeFirst: true,
+      startupTimeoutMs: svc.startupTimeoutMs
+    });
+    return {
+      status: 200,
+      body: {
+        status: state.status,
+        message: state.message,
+        logs: state.status === "failed" ? state.logs : void 0
+      }
+    };
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) return { status: 404, body: { error: err.message } };
+    return { status: 500, body: { error: err.message } };
+  }
+}
+
+// src/ui/ui-server.ts
+var MIME_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".htm": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".map": "application/json; charset=utf-8"
+};
+async function startUiServer(opts) {
+  const staticDir = resolve2(opts.staticDir);
+  if (!existsSync4(staticDir)) {
+    throw new Error(
+      `Macroscope UI build is missing. Expected files at ${staticDir}. Run \`pnpm build\` first.`
+    );
+  }
+  const indexFile = join4(staticDir, "index.html");
+  if (!existsSync4(indexFile)) {
+    throw new Error(`Macroscope UI build is incomplete: ${indexFile} not found.`);
+  }
+  const serviceManager = new ServiceManager();
+  const server = createServer((req, res) => {
+    void handleRequest(req, res, staticDir, opts.cwd, serviceManager).catch((err) => {
+      respondError(res, 500, err instanceof Error ? err.message : String(err));
+    });
+  });
+  const port = await new Promise((resolveListen, reject) => {
+    server.once("error", reject);
+    server.listen(opts.port ?? 0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        reject(new Error("Server did not start with an address"));
+        return;
+      }
+      resolveListen(addr.port);
+    });
+  });
+  const { attachTerminalWs: attachTerminalWs2 } = await Promise.resolve().then(() => (init_terminal_ws(), terminal_ws_exports));
+  attachTerminalWs2(server, opts.cwd);
+  const url = `http://localhost:${port}`;
+  if (opts.open !== false) {
+    try {
+      const openModule = await import("open");
+      const openFn = openModule.default ?? openModule;
+      await openFn(url);
+    } catch {
+    }
+  }
+  const onSignal = () => serviceManager.shutdown();
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+  return {
+    url,
+    port,
+    close: () => new Promise((resolveClose, reject) => {
+      serviceManager.shutdown();
+      process.off("SIGINT", onSignal);
+      process.off("SIGTERM", onSignal);
+      server.close((err) => err ? reject(err) : resolveClose());
+    })
+  };
+}
+async function handleRequest(req, res, staticDir, cwd, serviceManager) {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  if (url.pathname === "/api/blueprints") {
+    const result = await handleBlueprintsRequest(cwd);
+    res.statusCode = result.status;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(result.body));
+    return;
+  }
+  if (url.pathname === "/api/blocks") {
+    const result = await handleBlocksRequest(cwd);
+    res.statusCode = result.status;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(result.body));
+    return;
+  }
+  if (url.pathname === "/api/markdown") {
+    const requestedPath = url.searchParams.get("path");
+    if (!requestedPath) {
+      res.statusCode = 400;
+      res.setHeader("content-type", "text/plain");
+      res.end("Missing ?path");
+      return;
+    }
+    const absolute = resolve2(cwd, requestedPath);
+    if (!absolute.startsWith(resolve2(cwd))) {
+      res.statusCode = 403;
+      res.setHeader("content-type", "text/plain");
+      res.end("Forbidden");
+      return;
+    }
+    const result = await handleMarkdownRequest(absolute);
+    res.statusCode = result.status;
+    res.setHeader("content-type", result.contentType);
+    res.end(result.body);
+    return;
+  }
+  if (url.pathname === "/api/code") {
+    const requestedPath = url.searchParams.get("path");
+    const lang = url.searchParams.get("lang") ?? void 0;
+    if (!requestedPath) {
+      res.statusCode = 400;
+      res.setHeader("content-type", "text/plain");
+      res.end("Missing ?path");
+      return;
+    }
+    const absolute = resolve2(cwd, requestedPath);
+    if (!absolute.startsWith(resolve2(cwd))) {
+      res.statusCode = 403;
+      res.setHeader("content-type", "text/plain");
+      res.end("Forbidden");
+      return;
+    }
+    const result = await handleCodeRequest(absolute, lang);
+    res.statusCode = result.status;
+    res.setHeader("content-type", result.contentType);
+    res.end(result.body);
+    return;
+  }
+  if (url.pathname === "/api/services/ensure" && req.method === "POST") {
+    const raw = await readBody(req);
+    let parsed;
+    try {
+      parsed = JSON.parse(raw || "{}");
+    } catch {
+      res.statusCode = 400;
+      res.setHeader("content-type", "application/json; charset=utf-8");
+      res.end(JSON.stringify({ error: "invalid json" }));
+      return;
+    }
+    const result = await handleServiceEnsureRequest(cwd, serviceManager, {
+      blockId: parsed.blockId ?? "",
+      viewKey: parsed.viewKey ?? ""
+    });
+    res.statusCode = result.status;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(result.body));
+    return;
+  }
+  const requested = url.pathname === "/" ? "/index.html" : url.pathname;
+  const absolutePath = normalize(join4(staticDir, requested));
+  if (!absolutePath.startsWith(staticDir)) {
+    respondError(res, 403, "Forbidden");
+    return;
+  }
+  try {
+    const content = await readFile5(absolutePath);
+    res.setHeader("content-type", MIME_TYPES[extname2(absolutePath)] ?? "application/octet-stream");
+    res.end(content);
+    return;
+  } catch {
+    try {
+      const indexContent = await readFile5(join4(staticDir, "index.html"));
+      res.setHeader("content-type", "text/html; charset=utf-8");
+      res.end(indexContent);
+    } catch {
+      respondError(res, 404, "Not found");
+    }
+  }
+}
+function respondError(res, status, message) {
+  res.statusCode = status;
+  res.setHeader("content-type", "text/plain; charset=utf-8");
+  res.end(message);
+}
+function readBody(req) {
+  return new Promise((resolveBody, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolveBody(Buffer.concat(chunks).toString()));
+    req.on("error", reject);
+  });
+}
+
+// src/cli.ts
+if (importLocal(import.meta.url)) {
+} else {
+  main();
+}
+function main() {
+  const program = new Command();
+  program.name("macroscope").description("Catalogue tooling for AI-collaborative software development").version(VERSION, "-v, --version").option("--json", "output machine-readable JSON");
+  program.command("hello").description("Placeholder \u2014 proves the CLI wiring works").action((_opts, cmd) => {
+    const globalOpts = cmd.parent?.opts() ?? {};
+    if (globalOpts.json) {
+      process.stdout.write(`${JSON.stringify({ ok: true, message: "hello from macroscope" })}
+`);
+    } else {
+      process.stdout.write("hello from macroscope\n");
+    }
+  });
+  program.command("blueprints").description("List the unit blueprints defined in this project (.macroscope/blueprints/)").option("--cwd <path>", "project search starts here (defaults to current dir)").action(async (cmdOpts, cmd) => {
+    const globalOpts = cmd.parent?.opts() ?? {};
+    await runBlueprints({ cwd: cmdOpts.cwd, json: !!globalOpts.json });
+  });
+  program.command("ui").description("Open the macroscope web UI in your browser").option("--cwd <path>", "project search starts here (defaults to current dir)").option(
+    "--port <n>",
+    "port to listen on (default: auto-pick a free port)",
+    (v) => Number.parseInt(v, 10)
+  ).option("--no-open", "don't automatically open a browser").action(async (cmdOpts) => {
+    await runUi({
+      cwd: cmdOpts.cwd,
+      port: cmdOpts.port,
+      open: cmdOpts.open !== false
+    });
+  });
+  program.parse(process.argv);
+}
+async function runBlueprints(opts) {
+  let project;
+  try {
+    project = await findProject(opts.cwd ?? process.cwd());
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) {
+      writeError(err.message, opts.json);
+      process.exit(1);
+    }
+    writeError(`${err.message}`, opts.json);
+    process.exit(1);
+  }
+  const result = await loadBlueprints(project);
+  if (opts.json) {
+    writeJson(result);
+  } else {
+    writeHuman(result);
+  }
+  if (result.errors.length > 0) {
+    process.exitCode = 1;
+  }
+}
+function writeHuman(result) {
+  if (result.blueprints.length === 0 && result.errors.length === 0) {
+    process.stdout.write(
+      "No blueprints found. Create one at .macroscope/blueprints/<kind>/handler.ts.\n"
+    );
+    return;
+  }
+  if (result.blueprints.length > 0) {
+    for (const bp of result.blueprints) {
+      const caps = bp.capabilities.length > 0 ? bp.capabilities.join(", ") : "(no operations)";
+      process.stdout.write(`${bp.kind.padEnd(24)} ${caps}
+`);
+    }
+  }
+  if (result.errors.length > 0) {
+    process.stderr.write(`
+${result.errors.length} blueprint error(s):
+`);
+    for (const e of result.errors) {
+      process.stderr.write(`  [${e.kind}] ${e.message}
+`);
+    }
+  }
+}
+function writeJson(result) {
+  const out = {
+    blueprints: result.blueprints.map((b) => ({
+      kind: b.kind,
+      folder: b.folder,
+      file: b.file,
+      capabilities: b.capabilities
+    })),
+    errors: result.errors
+  };
+  process.stdout.write(`${JSON.stringify(out, null, 2)}
+`);
+}
+async function runUi(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  try {
+    await findProject(cwd);
+  } catch (err) {
+    if (err instanceof ProjectNotFoundError) {
+      process.stderr.write(`${err.message}
+`);
+      process.exit(1);
+    }
+    throw err;
+  }
+  const here = dirname3(fileURLToPath(import.meta.url));
+  const staticDir = resolve3(here, "ui");
+  let server;
+  try {
+    server = await startUiServer({ cwd, staticDir, port: opts.port, open: opts.open });
+  } catch (err) {
+    process.stderr.write(`macroscope ui: ${err.message}
+`);
+    process.exit(1);
+  }
+  process.stdout.write(`macroscope ui running at ${server.url}
+`);
+  process.stdout.write("Press Ctrl+C to stop.\n");
+  const shutdown = async () => {
+    await server.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown());
+  process.on("SIGTERM", () => void shutdown());
+}
+function writeError(message, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ ok: false, error: message })}
+`);
+  } else {
+    process.stderr.write(`${message}
+`);
+  }
+}
+//# sourceMappingURL=cli.js.map