@sightmap/sightmap 0.3.1 → 0.5.0

package/dist/cli/index.js

@@ -1497,6 +1497,1190 @@ async function processFile(absPath, relPath, opts, fileResults, diagnostics) {
   }
 }
 
+// src/cli/init/index.ts
+import { resolve as resolve22 } from "path";
+import { mkdir as mkdir4, readFile as readFile13, rm, writeFile as writeFile7 } from "fs/promises";
+import { tmpdir } from "os";
+import * as clack2 from "@clack/prompts";
+
+// src/cli/init/detect/framework.ts
+import { readFile as readFile4, access } from "fs/promises";
+import { resolve as resolve11 } from "path";
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function detectFramework(cwd) {
+  const pkgPath = resolve11(cwd, "package.json");
+  if (!await exists(pkgPath)) return "unknown";
+  const pkg = JSON.parse(await readFile4(pkgPath, "utf8"));
+  const deps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+  if (deps.next) {
+    if (await exists(resolve11(cwd, "app"))) return "next-app";
+    if (await exists(resolve11(cwd, "pages"))) return "next-pages";
+    return "next-app";
+  }
+  const rrVersion = deps["react-router"];
+  const rr7 = rrVersion ? /^[\^~>=<]*7\./.test(rrVersion) : false;
+  if (rr7 || await exists(resolve11(cwd, "react-router.config.ts"))) {
+    return "react-router-7";
+  }
+  if (deps.react) {
+    if (deps.vite || await exists(resolve11(cwd, "vite.config.ts")) || await exists(resolve11(cwd, "vite.config.js"))) {
+      return "react-vite";
+    }
+    if (deps["react-scripts"]) return "react-cra";
+  }
+  return "unknown";
+}
+
+// src/cli/init/detect/harness.ts
+import { access as access2 } from "fs/promises";
+import { resolve as resolve12 } from "path";
+async function exists2(path) {
+  try {
+    await access2(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var HARNESS_ORDER = ["claude-code", "codex", "cursor", "opencode"];
+async function detectHarnesses(cwd) {
+  const out = [];
+  for (const h of HARNESS_ORDER) {
+    let found = false;
+    if (h === "claude-code") found = await exists2(resolve12(cwd, ".claude"));
+    else if (h === "cursor") found = await exists2(resolve12(cwd, ".cursor"));
+    else if (h === "codex") found = await exists2(resolve12(cwd, ".codex"));
+    else if (h === "opencode") found = await exists2(resolve12(cwd, "opencode.json"));
+    if (found) out.push(h);
+  }
+  return out;
+}
+
+// src/cli/init/detect/vendor.ts
+import { readFile as readFile5, access as access3 } from "fs/promises";
+import { resolve as resolve13 } from "path";
+
+// src/cli/init/vendor-allowlist.ts
+var KNOWN_SIGHTMAP_VENDORS = ["subtext"];
+function isKnownVendor(entry) {
+  const haystacks = [entry.name, entry.command, ...entry.args];
+  return KNOWN_SIGHTMAP_VENDORS.some(
+    (vendor) => haystacks.some((h) => h.toLowerCase().includes(vendor.toLowerCase()))
+  );
+}
+
+// src/cli/init/detect/vendor.ts
+async function readJsonIfExists(path) {
+  try {
+    await access3(path);
+    return JSON.parse(await readFile5(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function extractServers(parsed) {
+  if (!parsed || typeof parsed !== "object") return [];
+  const root = parsed;
+  const servers = root.mcpServers ?? {};
+  return Object.entries(servers).map(([name, def]) => ({
+    name,
+    command: def.command ?? "",
+    args: def.args ?? []
+  }));
+}
+async function detectSightmapAwareVendor(cwd, hosts) {
+  const candidates = [];
+  if (hosts.includes("claude-code")) candidates.push(resolve13(cwd, ".mcp.json"));
+  if (hosts.includes("cursor")) candidates.push(resolve13(cwd, ".cursor/mcp.json"));
+  if (hosts.includes("opencode")) candidates.push(resolve13(cwd, "opencode.json"));
+  for (const path of candidates) {
+    const parsed = await readJsonIfExists(path);
+    if (!parsed) continue;
+    for (const entry of extractServers(parsed)) {
+      if (isKnownVendor(entry)) return true;
+    }
+  }
+  return false;
+}
+
+// src/cli/init/detect/sightmap-dir.ts
+import { access as access4, readdir as readdir4 } from "fs/promises";
+import { resolve as resolve14 } from "path";
+async function detectSightmapDir(cwd) {
+  const dir = resolve14(cwd, ".sightmap");
+  try {
+    await access4(dir);
+  } catch {
+    return { present: false };
+  }
+  const entries = await readdir4(dir);
+  const yamls = entries.filter((e) => e.endsWith(".yaml") || e.endsWith(".yml"));
+  return { present: true, viewCount: yamls.length };
+}
+
+// src/cli/init/detect/workspaces.ts
+import { readFile as readFile6, readdir as readdir5, stat as stat3 } from "fs/promises";
+import { resolve as resolve15, relative as relative6 } from "path";
+import { parse as parseYaml } from "yaml";
+async function exists3(p) {
+  try {
+    await stat3(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readWorkspacePatterns(root) {
+  const patterns = [];
+  const pnpmWs = resolve15(root, "pnpm-workspace.yaml");
+  if (await exists3(pnpmWs)) {
+    try {
+      const parsed = parseYaml(await readFile6(pnpmWs, "utf8"));
+      const list = parsed && Array.isArray(parsed.packages) ? parsed.packages : [];
+      for (const p of list) {
+        if (typeof p === "string") patterns.push(p);
+      }
+    } catch {
+    }
+  }
+  const pkgJson = resolve15(root, "package.json");
+  if (await exists3(pkgJson)) {
+    try {
+      const pkg = JSON.parse(await readFile6(pkgJson, "utf8"));
+      const ws = pkg.workspaces;
+      if (Array.isArray(ws)) patterns.push(...ws);
+      else if (ws && Array.isArray(ws.packages)) patterns.push(...ws.packages);
+    } catch {
+    }
+  }
+  return patterns;
+}
+async function expandPattern(root, pattern) {
+  const trimmed = pattern.replace(/^\.\//, "").replace(/\/$/, "");
+  if (trimmed.startsWith("!")) return [];
+  if (trimmed.includes("**")) return expandDoubleStar(root, trimmed);
+  const segments = trimmed.split("/");
+  return expandSegments(root, segments, 0, root);
+}
+async function expandSegments(root, segs, idx, current) {
+  if (idx >= segs.length) {
+    if (await isPackageDir(current)) return [current];
+    return [];
+  }
+  const seg = segs[idx];
+  if (seg === void 0) return [];
+  if (seg === "*") {
+    let entries = [];
+    try {
+      entries = await readdir5(current);
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const name of entries) {
+      if (name.startsWith(".")) continue;
+      const child = resolve15(current, name);
+      let s;
+      try {
+        s = await stat3(child);
+      } catch {
+        continue;
+      }
+      if (!s.isDirectory()) continue;
+      out.push(...await expandSegments(root, segs, idx + 1, child));
+    }
+    return out;
+  }
+  return expandSegments(root, segs, idx + 1, resolve15(current, seg));
+}
+async function expandDoubleStar(root, pattern) {
+  const prefix = (pattern.split("**")[0] ?? "").replace(/\/$/, "");
+  const base = prefix ? resolve15(root, prefix) : root;
+  const out = [];
+  await walk2(base, 0, 5, out);
+  return out;
+}
+async function walk2(dir, depth, maxDepth, out) {
+  if (depth > maxDepth) return;
+  if (await isPackageDir(dir)) out.push(dir);
+  let entries = [];
+  try {
+    entries = await readdir5(dir);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (name.startsWith(".") || name === "node_modules") continue;
+    const child = resolve15(dir, name);
+    let s;
+    try {
+      s = await stat3(child);
+    } catch {
+      continue;
+    }
+    if (s.isDirectory()) await walk2(child, depth + 1, maxDepth, out);
+  }
+}
+async function isPackageDir(dir) {
+  return exists3(resolve15(dir, "package.json"));
+}
+async function enumerateWorkspaces(opts) {
+  const { root } = opts;
+  const patterns = await readWorkspacePatterns(root);
+  if (patterns.length === 0) return [];
+  const dirs = /* @__PURE__ */ new Set();
+  for (const pat of patterns) {
+    for (const d of await expandPattern(root, pat)) dirs.add(d);
+  }
+  const result = [];
+  for (const dir of dirs) {
+    if (dir === root) continue;
+    const framework = await detectFramework(dir);
+    result.push({ dir, relPath: relative6(root, dir) || ".", framework });
+  }
+  result.sort((a, b) => {
+    const ak = a.framework === "unknown" ? 1 : 0;
+    const bk = b.framework === "unknown" ? 1 : 0;
+    if (ak !== bk) return ak - bk;
+    return a.relPath.localeCompare(b.relPath);
+  });
+  return result;
+}
+
+// src/cli/init/tui.ts
+import * as clack from "@clack/prompts";
+import pc from "picocolors";
+
+// src/cli/init/framework-setup/provider-snippet.ts
+import { relative as relative7 } from "path";
+var IMPORT_LINE = `import { SightmapProvider } from '@sightmap/react';`;
+function renderProviderSnippet(opts) {
+  const relPath = relative7(opts.cwd, opts.entryAbsPath) || opts.entryAbsPath;
+  switch (opts.framework) {
+    case "react-vite":
+    case "react-cra":
+      return {
+        relPath,
+        importLine: IMPORT_LINE,
+        instruction: "Wrap your render root with <SightmapProvider>:",
+        example: `ReactDOM.createRoot(document.getElementById('root')!).render(
+  <SightmapProvider>
+    <App />
+  </SightmapProvider>,
+);`
+      };
+    case "next-app":
+      return {
+        relPath,
+        importLine: IMPORT_LINE,
+        instruction: "Wrap the layout's {children} with <SightmapProvider>:",
+        example: `export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <SightmapProvider>{children}</SightmapProvider>
+      </body>
+    </html>
+  );
+}`
+      };
+    case "next-pages":
+      return {
+        relPath,
+        importLine: IMPORT_LINE,
+        instruction: "Wrap <Component {...pageProps} /> with <SightmapProvider>:",
+        example: `export default function App({ Component, pageProps }) {
+  return (
+    <SightmapProvider>
+      <Component {...pageProps} />
+    </SightmapProvider>
+  );
+}`
+      };
+    case "react-router-7":
+      return {
+        relPath,
+        importLine: IMPORT_LINE,
+        instruction: "Wrap the default export's returned JSX with <SightmapProvider>:",
+        example: `export default function Root() {
+  return (
+    <SightmapProvider>
+      <Outlet />
+    </SightmapProvider>
+  );
+}`
+      };
+    case "unknown":
+      return {
+        relPath,
+        importLine: IMPORT_LINE,
+        instruction: "Wrap your application's root component with <SightmapProvider>.",
+        example: `<SightmapProvider>{/* your app */}</SightmapProvider>`
+      };
+  }
+}
+function formatSnippet(snippet) {
+  return [
+    `In ${snippet.relPath}:`,
+    "",
+    `  ${snippet.importLine}`,
+    "",
+    snippet.instruction,
+    "",
+    ...snippet.example.split("\n").map((l) => `  ${l}`)
+  ].join("\n");
+}
+
+// src/cli/init/tui.ts
+var FRAMEWORK_LABELS = {
+  "react-vite": "React (Vite)",
+  "react-cra": "React (CRA)",
+  "next-app": "Next.js (App Router)",
+  "next-pages": "Next.js (Pages Router)",
+  "react-router-7": "React Router 7",
+  unknown: "unknown"
+};
+var HOST_LABELS = {
+  "claude-code": "Claude Code",
+  codex: "Codex",
+  cursor: "Cursor",
+  opencode: "OpenCode"
+};
+function row(label, value) {
+  return `${pc.cyan(label)} ${pc.white(value)}`;
+}
+function formatDetectionSummary(d) {
+  const fw = row("Framework:", FRAMEWORK_LABELS[d.framework]);
+  const hosts = row(
+    "Coding agents:",
+    d.hosts.length > 0 ? d.hosts.map((h) => HOST_LABELS[h]).join(", ") : "none detected"
+  );
+  const vendor = row(
+    "Browser MCP:",
+    d.sightmapAwareVendor ? "Sightmap-aware vendor detected" : "none detected"
+  );
+  const dir = row(
+    ".sightmap/:",
+    d.sightmapDir.present ? `present (${d.sightmapDir.viewCount ?? 0} views)` : "not present"
+  );
+  return [fw, hosts, vendor, dir];
+}
+function intro2() {
+  clack.intro(pc.cyan("\u25C6 Sightmap") + "  curate your view inventory");
+}
+function outro2(message) {
+  clack.outro(pc.green(message));
+}
+function showDetection(d) {
+  clack.log.message(
+    [pc.bold("Detected"), "", ...formatDetectionSummary(d)].join("\n"),
+    { symbol: pc.cyan("\u25C7") }
+  );
+}
+function showPluginInstructions(hosts) {
+  const lines = [pc.bold("Next: run these to finish setup"), ""];
+  for (let i = 0; i < hosts.length; i++) {
+    const h = hosts[i];
+    lines.push(...pluginSection(h));
+    if (i < hosts.length - 1) lines.push("");
+  }
+  lines.push("", pc.dim("Then restart your agent."));
+  clack.log.message(lines.join("\n"), { symbol: pc.cyan("\u25C7") });
+}
+function pluginSection(host) {
+  switch (host) {
+    case "claude-code":
+      return [
+        pc.cyan("Claude Code"),
+        pc.white("  /plugin marketplace add sightmap/plugin"),
+        pc.white("  /plugin install sightmap@sightmap-marketplace")
+      ];
+    case "codex":
+      return [
+        pc.cyan("Codex"),
+        pc.white("  codex plugin marketplace add sightmap/plugin"),
+        pc.white("  codex plugin install sightmap@sightmap-marketplace")
+      ];
+    case "cursor":
+      return [
+        pc.cyan("Cursor"),
+        pc.white("  /plugin add sightmap/plugin"),
+        pc.dim("  (in the Cursor command palette)")
+      ];
+    case "opencode":
+      return [
+        pc.cyan("OpenCode"),
+        pc.white("  Add to opencode.json plugin array:"),
+        pc.white('    "plugin": ["sightmap@git+https://github.com/sightmap/plugin"]'),
+        pc.dim("  Then restart OpenCode.")
+      ];
+  }
+}
+async function selectInstallPath(suggestion = "plugin") {
+  return clack.select({
+    message: "How would you like to install Sightmap?",
+    initialValue: suggestion,
+    options: [
+      {
+        value: "plugin",
+        label: "Plugin (recommended)",
+        hint: "Two copy-paste commands per host. Skills, hooks, MCP \u2014 all together."
+      },
+      {
+        value: "manual",
+        label: "Manual",
+        hint: "Write MCP config + copy skills/hooks into this repo."
+      }
+    ]
+  });
+}
+async function selectWorkspace(workspaces) {
+  const options = workspaces.map((w) => ({
+    value: w,
+    label: w.relPath,
+    hint: w.framework === "unknown" ? pc.dim("no framework") : FRAMEWORK_LABELS[w.framework]
+  }));
+  return clack.select({
+    message: "Multiple workspaces found. Which one should we set up?",
+    options,
+    initialValue: workspaces[0]
+  });
+}
+async function selectProviderAction(entryRelPath) {
+  const options = [
+    { value: "auto", label: "Wrap automatically", hint: "Edit the file in place via codemod." },
+    { value: "snippet", label: "Show me the snippet to paste", hint: "Print the exact lines; I'll add them myself." },
+    { value: "skip", label: "Skip", hint: "Already done, or I'll handle it later." }
+  ];
+  return clack.select({
+    message: `Add <SightmapProvider> to ${entryRelPath}?`,
+    initialValue: "auto",
+    options
+  });
+}
+function showProviderSnippet(snippet, note) {
+  const header = pc.bold("Add <SightmapProvider> manually");
+  const body = formatSnippet(snippet);
+  const trailer = note ? `
+
+${pc.dim(note)}` : "";
+  clack.log.message(`${header}
+
+${body}${trailer}`, { symbol: pc.cyan("\u25C7") });
+}
+async function selectHosts(detected, defaults) {
+  const options = ["claude-code", "codex", "cursor", "opencode"].map((h) => ({
+    value: h,
+    label: HOST_LABELS[h] + (detected.includes(h) ? pc.dim(" (detected)") : "")
+  }));
+  return clack.multiselect({
+    message: "Which hosts?",
+    options,
+    initialValues: defaults,
+    required: true
+  });
+}
+
+// src/cli/init/mcp-config/claude-code.ts
+import { readFile as readFile7, writeFile as writeFile2, access as access5 } from "fs/promises";
+import { resolve as resolve16 } from "path";
+async function readJsonIfExists2(path) {
+  try {
+    await access5(path);
+    return JSON.parse(await readFile7(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function writeClaudeCodeMcp(opts) {
+  const path = resolve16(opts.cwd, ".mcp.json");
+  const existing = await readJsonIfExists2(path) ?? {};
+  const servers = existing.mcpServers ?? {};
+  const next = {
+    ...existing,
+    mcpServers: {
+      ...servers,
+      [opts.serverName]: opts.serverDef
+    }
+  };
+  await writeFile2(path, JSON.stringify(next, null, 2) + "\n", "utf8");
+}
+
+// src/cli/init/mcp-config/cursor.ts
+import { readFile as readFile8, writeFile as writeFile3, access as access6, mkdir } from "fs/promises";
+import { resolve as resolve17, dirname as dirname2 } from "path";
+async function writeCursorMcp(opts) {
+  const path = resolve17(opts.cwd, ".cursor/mcp.json");
+  let existing = {};
+  try {
+    await access6(path);
+    existing = JSON.parse(await readFile8(path, "utf8"));
+  } catch {
+    await mkdir(dirname2(path), { recursive: true });
+  }
+  const servers = existing.mcpServers ?? {};
+  const next = {
+    ...existing,
+    mcpServers: { ...servers, [opts.serverName]: opts.serverDef }
+  };
+  await writeFile3(path, JSON.stringify(next, null, 2) + "\n", "utf8");
+}
+
+// src/cli/init/mcp-config/opencode.ts
+import { readFile as readFile9, writeFile as writeFile4, access as access7 } from "fs/promises";
+import { resolve as resolve18 } from "path";
+async function writeOpenCodeMcp(opts) {
+  const path = resolve18(opts.cwd, "opencode.json");
+  let existing = {};
+  try {
+    await access7(path);
+    existing = JSON.parse(await readFile9(path, "utf8"));
+  } catch {
+  }
+  const mcp = existing.mcp ?? {};
+  const next = {
+    ...existing,
+    mcp: { ...mcp, [opts.serverName]: opts.serverDef }
+  };
+  await writeFile4(path, JSON.stringify(next, null, 2) + "\n", "utf8");
+}
+
+// src/cli/init/mcp-config/codex.ts
+import { readFile as readFile10, writeFile as writeFile5, access as access8, mkdir as mkdir2 } from "fs/promises";
+import { dirname as dirname3 } from "path";
+import { parse as parse2, stringify } from "smol-toml";
+async function writeCodexMcp(opts) {
+  let existing = {};
+  try {
+    await access8(opts.configPath);
+    existing = parse2(await readFile10(opts.configPath, "utf8"));
+  } catch {
+    await mkdir2(dirname3(opts.configPath), { recursive: true });
+  }
+  const servers = existing.mcp_servers ?? {};
+  const next = {
+    ...existing,
+    mcp_servers: {
+      ...servers,
+      [opts.serverName]: opts.serverDef
+    }
+  };
+  await writeFile5(opts.configPath, stringify(next), "utf8");
+}
+
+// src/cli/init/tarball.ts
+import pacote from "pacote";
+import { readFile as readFile11 } from "fs/promises";
+import { resolve as resolve19 } from "path";
+async function fetchPluginTarball(opts) {
+  const spec = `@sightmap/plugin@${opts.version}`;
+  await pacote.extract(spec, opts.destDir);
+  const manifestPath = resolve19(opts.destDir, ".claude-plugin/plugin.json");
+  const manifest = JSON.parse(await readFile11(manifestPath, "utf8"));
+  if (!manifest.compatibleMcpVersion) {
+    throw new Error("Plugin tarball missing 'compatibleMcpVersion' in plugin.json");
+  }
+  return {
+    destDir: opts.destDir,
+    compatibleMcpVersion: manifest.compatibleMcpVersion,
+    pluginVersion: manifest.version ?? "0.0.0"
+  };
+}
+
+// src/cli/init/skills-copy.ts
+import { chmod, cp, mkdir as mkdir3, readFile as readFile12, readdir as readdir6, stat as stat4, writeFile as writeFile6, access as access9 } from "fs/promises";
+import { resolve as resolve20 } from "path";
+
+// src/cli/init/settings-merge.ts
+var PLUGIN_ROOT_TOKEN = /\$\{CLAUDE_PLUGIN_ROOT\}/g;
+function rewriteHookCommands(hooks, replacement) {
+  const out = {};
+  for (const [event, groups] of Object.entries(hooks)) {
+    out[event] = groups.map((g) => ({
+      ...g.matcher !== void 0 ? { matcher: g.matcher } : {},
+      hooks: g.hooks.map((h) => ({
+        ...h,
+        command: h.command.replace(PLUGIN_ROOT_TOKEN, replacement)
+      }))
+    }));
+  }
+  return out;
+}
+function mergeHooksIntoSettings(existing, incoming) {
+  const merged = { ...existing };
+  const mergedHooks = { ...existing.hooks ?? {} };
+  for (const [event, incomingGroups] of Object.entries(incoming)) {
+    const existingGroups = mergedHooks[event] ?? [];
+    const combined = [...existingGroups];
+    for (const g of incomingGroups) {
+      if (!hasGroup(combined, g)) combined.push(g);
+    }
+    mergedHooks[event] = combined;
+  }
+  merged.hooks = mergedHooks;
+  return merged;
+}
+function hasGroup(groups, candidate) {
+  return groups.some(
+    (g) => (g.matcher ?? "") === (candidate.matcher ?? "") && g.hooks.length === candidate.hooks.length && g.hooks.every((h, i) => h.command === candidate.hooks[i]?.command)
+  );
+}
+
+// src/cli/init/skills-copy.ts
+async function copyPluginAssets(opts) {
+  const targets = resolveTargets(opts.host, opts.projectDir);
+  await mkdir3(targets.skills, { recursive: true });
+  await cp(resolve20(opts.tarballDir, "skills"), targets.skills, { recursive: true });
+  if (targets.agents) {
+    await mkdir3(targets.agents, { recursive: true });
+    await cp(resolve20(opts.tarballDir, "agents"), targets.agents, { recursive: true });
+  }
+  if (targets.bin) {
+    await mkdir3(targets.bin, { recursive: true });
+    await cp(resolve20(opts.tarballDir, "bin"), targets.bin, { recursive: true });
+    await chmodShellScripts(targets.bin);
+  }
+  if (targets.settingsJson && targets.bin && targets.binEnvPath) {
+    await installHooksIntoSettings({
+      tarballDir: opts.tarballDir,
+      settingsPath: targets.settingsJson,
+      binEnvPath: targets.binEnvPath
+    });
+  } else if (targets.hooksJson) {
+    await installLegacyHooksJson({
+      tarballDir: opts.tarballDir,
+      dstPath: targets.hooksJson,
+      binEnvPath: targets.binEnvPath ?? `\${CLAUDE_PROJECT_DIR}/.claude/sightmap`
+    });
+  }
+}
+async function installHooksIntoSettings(opts) {
+  const incomingRaw = JSON.parse(
+    await readFile12(resolve20(opts.tarballDir, "hooks/hooks.json"), "utf8")
+  );
+  const incoming = incomingRaw.hooks ?? {};
+  const rewritten = rewriteHookCommands(incoming, opts.binEnvPath);
+  let existing = {};
+  try {
+    await access9(opts.settingsPath);
+    existing = JSON.parse(await readFile12(opts.settingsPath, "utf8"));
+  } catch {
+  }
+  const merged = mergeHooksIntoSettings(existing, rewritten);
+  await mkdir3(resolve20(opts.settingsPath, ".."), { recursive: true });
+  await writeFile6(opts.settingsPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+}
+async function installLegacyHooksJson(opts) {
+  const srcRaw = JSON.parse(
+    await readFile12(resolve20(opts.tarballDir, "hooks/hooks.json"), "utf8")
+  );
+  const rewritten = rewriteHookCommands(srcRaw.hooks ?? {}, opts.binEnvPath);
+  let merged = { hooks: rewritten };
+  try {
+    await access9(opts.dstPath);
+    const existing = JSON.parse(await readFile12(opts.dstPath, "utf8"));
+    merged = { hooks: { ...existing.hooks ?? {}, ...rewritten } };
+  } catch {
+  }
+  await mkdir3(resolve20(opts.dstPath, ".."), { recursive: true });
+  await writeFile6(opts.dstPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+}
+async function chmodShellScripts(dir) {
+  const entries = await readdir6(dir);
+  for (const name of entries) {
+    const p = resolve20(dir, name);
+    const s = await stat4(p);
+    if (s.isDirectory()) {
+      await chmodShellScripts(p);
+    } else if (name.endsWith(".sh")) {
+      await chmod(p, 493);
+    }
+  }
+}
+function resolveTargets(host, projectDir) {
+  switch (host) {
+    case "claude-code":
+      return {
+        skills: resolve20(projectDir, ".claude/skills/sightmap"),
+        agents: resolve20(projectDir, ".claude/agents"),
+        bin: resolve20(projectDir, ".claude/sightmap/bin"),
+        // Stand-in for CLAUDE_PLUGIN_ROOT — tarball commands are written as
+        // ${CLAUDE_PLUGIN_ROOT}/bin/X.sh, so we replace the plugin root, not the bin dir.
+        binEnvPath: "${CLAUDE_PROJECT_DIR}/.claude/sightmap",
+        settingsJson: resolve20(projectDir, ".claude/settings.json")
+      };
+    case "codex":
+      return {
+        skills: resolve20(projectDir, ".codex/skills/sightmap"),
+        agents: resolve20(projectDir, ".codex/agents"),
+        bin: resolve20(projectDir, ".codex/sightmap/bin"),
+        binEnvPath: "${CLAUDE_PROJECT_DIR}/.codex/sightmap",
+        hooksJson: resolve20(projectDir, ".codex/hooks.json")
+      };
+    case "cursor":
+      return { skills: resolve20(projectDir, ".cursor/rules/sightmap") };
+    case "opencode":
+      return { skills: resolve20(projectDir, ".opencode/plugins/sightmap") };
+  }
+}
+
+// src/cli/init/version-pin.ts
+function buildSightmapMcpServerDef(opts) {
+  const args = [
+    "-y",
+    `@sightmap/mcp@${opts.compatibleMcpVersion}`,
+    "--sightmap-dir",
+    opts.sightmapDir,
+    "--curate-root",
+    opts.curateRoot
+  ];
+  if (opts.withBrowser) {
+    args.push("--", "npx", "-y", "@playwright/mcp@latest");
+  } else {
+    args.push("--curate-only");
+  }
+  return {
+    command: "npx",
+    args,
+    env: { SIGHTMAP_PLUGIN_VERSION: opts.pluginVersion }
+  };
+}
+
+// src/cli/init/framework-setup/package-manager.ts
+import { access as access10 } from "fs/promises";
+import { dirname as dirname4, resolve as resolve21 } from "path";
+async function exists4(p) {
+  try {
+    await access10(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var SIGNALS = [
+  { file: "pnpm-lock.yaml", pm: "pnpm" },
+  { file: "pnpm-workspace.yaml", pm: "pnpm" },
+  { file: "yarn.lock", pm: "yarn" }
+];
+async function detectPackageManager(cwd) {
+  let dir = resolve21(cwd);
+  while (true) {
+    for (const { file, pm } of SIGNALS) {
+      if (await exists4(resolve21(dir, file))) return pm;
+    }
+    const parent = dirname4(dir);
+    if (parent === dir) return "npm";
+    dir = parent;
+  }
+}
+
+// src/cli/init/framework-setup/install-adapter.ts
+import { spawn } from "child_process";
+var ADD_VERB = {
+  pnpm: "add",
+  yarn: "add",
+  npm: "install"
+};
+async function installAdapter(opts) {
+  await new Promise((resolveP, reject) => {
+    const child = spawn(opts.packageManager, [ADD_VERB[opts.packageManager], opts.packageName], {
+      cwd: opts.cwd,
+      stdio: "inherit"
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => code === 0 ? resolveP() : reject(new Error(`${opts.packageManager} exited with code ${code}`)));
+  });
+}
+
+// src/cli/init/framework-setup/codegen.ts
+import { spawn as spawn2 } from "child_process";
+var REACT_FRAMEWORKS = ["react-vite", "react-cra", "next-app", "next-pages", "react-router-7"];
+var EXEC_VERB = {
+  pnpm: ["exec"],
+  yarn: ["exec"],
+  npm: ["exec", "--"]
+};
+function buildCodegenCommand(opts) {
+  if (!REACT_FRAMEWORKS.includes(opts.framework)) return null;
+  return {
+    command: opts.packageManager,
+    args: [...EXEC_VERB[opts.packageManager], "sightmap-react", "gen", "--router=auto"]
+  };
+}
+async function runCodegen(cwd, cmd) {
+  await new Promise((resolveP, reject) => {
+    const child = spawn2(cmd.command, cmd.args, { cwd, stdio: "inherit" });
+    child.on("error", reject);
+    child.on("exit", (code) => code === 0 ? resolveP() : reject(new Error(`codegen exited ${code}`)));
+  });
+}
+
+// src/cli/init/framework-setup/provider-codemod.ts
+import * as recast from "recast";
+import * as parser from "@babel/parser";
+var babelParser = {
+  parse(source) {
+    return parser.parse(source, {
+      sourceType: "module",
+      tokens: true,
+      plugins: ["jsx", "typescript"]
+    });
+  }
+};
+function wrapWithSightmapProvider(source, opts = {}) {
+  if (source.includes("SightmapProvider")) {
+    return { code: source, changed: false, reason: "SightmapProvider already present" };
+  }
+  const ast = recast.parse(source, { parser: babelParser });
+  const b = recast.types.builders;
+  const wrap = (inner) => b.jsxElement(
+    b.jsxOpeningElement(b.jsxIdentifier("SightmapProvider"), [], false),
+    b.jsxClosingElement(b.jsxIdentifier("SightmapProvider")),
+    [stripPrintMetadata(inner)]
+  );
+  let wrapped = false;
+  let reason;
+  recast.types.visit(ast, {
+    visitCallExpression(path) {
+      if (wrapped) return false;
+      const callee = path.node.callee;
+      if (callee.type === "MemberExpression" && callee.property.type === "Identifier" && callee.property.name === "render") {
+        const arg = path.node.arguments[0];
+        if (!arg) {
+          reason = "render() called with no args";
+          return false;
+        }
+        path.node.arguments[0] = wrap(arg);
+        wrapped = true;
+        return false;
+      }
+      this.traverse(path);
+    }
+  });
+  if (!wrapped && opts.framework === "react-router-7") {
+    wrapped = tryWrapDefaultExport(ast, wrap);
+    if (!wrapped) reason = "no default export returning JSX found in app/root.tsx";
+  }
+  if (!wrapped) {
+    return { code: source, changed: false, reason: reason ?? "no .render() call found" };
+  }
+  const importDecl = b.importDeclaration(
+    [b.importSpecifier(b.identifier("SightmapProvider"), b.identifier("SightmapProvider"))],
+    b.stringLiteral("@sightmap/react")
+  );
+  insertImportAfterHeaderComments(ast, importDecl);
+  return { code: recast.print(ast, { quote: "single" }).code, changed: true };
+}
+function insertImportAfterHeaderComments(ast, importDecl) {
+  const body = ast.program.body;
+  const firstStmt = body[0];
+  if (firstStmt) {
+    const newImp = importDecl;
+    if (Array.isArray(firstStmt.leadingComments) && firstStmt.leadingComments.length > 0) {
+      newImp.leadingComments = firstStmt.leadingComments;
+      firstStmt.leadingComments = [];
+    }
+    if (Array.isArray(firstStmt.comments) && firstStmt.comments.length > 0) {
+      newImp.comments = firstStmt.comments;
+      firstStmt.comments = [];
+    }
+  }
+  body.unshift(importDecl);
+}
+function stripPrintMetadata(node) {
+  const n = node;
+  if (n && typeof n === "object") {
+    try {
+      n.original = void 0;
+    } catch {
+    }
+    try {
+      n.loc = void 0;
+    } catch {
+    }
+    if (n.extra) n.extra.parenthesized = false;
+  }
+  return node;
+}
+function tryWrapDefaultExport(ast, wrap) {
+  let done = false;
+  recast.types.visit(ast, {
+    visitExportDefaultDeclaration(path) {
+      if (done) return false;
+      const decl = path.node.declaration;
+      const body = decl.body;
+      if ((decl.type === "FunctionDeclaration" || decl.type === "ArrowFunctionExpression" || decl.type === "FunctionExpression") && body && body.type === "BlockStatement" && Array.isArray(body.body)) {
+        for (const stmt of body.body) {
+          if (stmt.type === "ReturnStatement" && stmt.argument) {
+            const arg = stmt.argument;
+            if (arg.type === "JSXElement" || arg.type === "JSXFragment") {
+              stmt.argument = wrap(stmt.argument);
+              done = true;
+              return false;
+            }
+          }
+        }
+      }
+      if (decl.type === "ArrowFunctionExpression" && body && (body.type === "JSXElement" || body.type === "JSXFragment")) {
+        decl.body = wrap(body);
+        done = true;
+        return false;
+      }
+      return false;
+    }
+  });
+  return done;
+}
+
+// src/cli/init/existing-corpus.ts
+function formatExistingCorpusReport(input) {
+  const errors = input.diagnostics.filter((d) => d.severity === "error");
+  const warnings = input.diagnostics.filter((d) => d.severity === "warning");
+  const lines = [];
+  lines.push(`sightmap check passed (${input.viewCount} views, ${errors.length} schema errors)`);
+  if (warnings.length > 0) {
+    const byCode = /* @__PURE__ */ new Map();
+    for (const w of warnings) byCode.set(w.code, (byCode.get(w.code) ?? 0) + 1);
+    const emptyMemory = byCode.get("EMPTY_MEMORY") ?? 0;
+    if (emptyMemory > 0) {
+      lines.push(`${emptyMemory} views have empty memory blocks \u2014 run /sightmap audit for details`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/cli/init/index.ts
+var REACT_FRAMEWORKS2 = ["react-vite", "react-cra", "next-app", "next-pages", "react-router-7"];
+async function runInit(opts) {
+  intro2();
+  let detect = {
+    framework: await detectFramework(opts.cwd),
+    hosts: await detectHarnesses(opts.cwd),
+    sightmapAwareVendor: false,
+    sightmapDir: await detectSightmapDir(opts.cwd)
+  };
+  detect.sightmapAwareVendor = await detectSightmapAwareVendor(opts.cwd, detect.hosts);
+  showDetection(detect);
+  if (detect.framework === "unknown" && !detect.sightmapDir.present) {
+    const chosen = await maybePickWorkspace(opts);
+    if (typeof chosen === "symbol") return 1;
+    if (chosen) {
+      opts = { ...opts, cwd: chosen.dir };
+      clack2.log.info(`Targeting workspace: ${chosen.relPath}`);
+      detect = {
+        framework: await detectFramework(opts.cwd),
+        hosts: detect.hosts,
+        sightmapAwareVendor: detect.sightmapAwareVendor,
+        sightmapDir: await detectSightmapDir(opts.cwd)
+      };
+    }
+  }
+  if (detect.sightmapDir.present) {
+    await runExistingCorpusFlow(opts.cwd, detect.sightmapDir.viewCount ?? 0);
+  } else {
+    await runFreshFrameworkSetup(opts, detect);
+  }
+  let installPath = opts.installPath;
+  if (!installPath) {
+    if (opts.yes) installPath = "plugin";
+    else {
+      const choice = await selectInstallPath("plugin");
+      if (typeof choice === "symbol") return 1;
+      installPath = choice;
+    }
+  }
+  const hosts = await resolveHosts(opts, detect);
+  if (hosts.length === 0) {
+    outro2("No hosts selected \u2014 nothing to do.");
+    return 0;
+  }
+  const withBrowser = resolveBrowserBundle(opts, detect);
+  if (installPath === "plugin") {
+    showPluginInstructions(hosts);
+    outro2("Run those, then restart your agent.");
+    return 0;
+  }
+  const tarballDir = resolve22(tmpdir(), `sightmap-plugin-${Date.now()}`);
+  await mkdir4(tarballDir, { recursive: true });
+  try {
+    const tar = await fetchPluginTarball({ destDir: tarballDir, version: "latest" });
+    const serverDef = buildSightmapMcpServerDef({
+      compatibleMcpVersion: tar.compatibleMcpVersion,
+      pluginVersion: tar.pluginVersion,
+      withBrowser,
+      sightmapDir: ".sightmap",
+      curateRoot: ".sightmap"
+    });
+    for (const h of hosts) {
+      await writeMcpForHost(h, opts.cwd, serverDef);
+      await copyPluginAssets({ tarballDir, projectDir: opts.cwd, host: h });
+    }
+  } finally {
+    await rm(tarballDir, { recursive: true, force: true });
+  }
+  outro2("Done. Restart your agent to pick up the new MCP.");
+  return 0;
+}
+async function runFreshFrameworkSetup(opts, detect) {
+  if (!REACT_FRAMEWORKS2.includes(detect.framework)) {
+    await mkdir4(resolve22(opts.cwd, ".sightmap"), { recursive: true });
+    await writeFile7(
+      resolve22(opts.cwd, ".sightmap/app.yaml"),
+      `version: 1
+views: []
+`,
+      "utf8"
+    );
+    return;
+  }
+  const pm = await detectPackageManager(opts.cwd);
+  const spinner2 = clack2.spinner();
+  spinner2.start(`Installing @sightmap/react via ${pm}`);
+  await installAdapter({ cwd: opts.cwd, packageManager: pm, packageName: "@sightmap/react" });
+  spinner2.stop("Installed @sightmap/react");
+  if (!opts.noProvider) {
+    await runProviderStep(opts, detect);
+  }
+  if (!opts.noCodegen) {
+    const cmd = buildCodegenCommand({ framework: detect.framework, packageManager: pm });
+    if (cmd) {
+      spinner2.start("Running sightmap-react gen");
+      await runCodegen(opts.cwd, cmd);
+      spinner2.stop("Scaffolded .sightmap/");
+    }
+  }
+}
+async function runProviderStep(opts, detect) {
+  const entry = await findAppEntry(opts.cwd, detect.framework);
+  if (!entry) {
+    const snippet = renderProviderSnippet({
+      framework: detect.framework,
+      cwd: opts.cwd,
+      entryAbsPath: "your app's root component file"
+    });
+    showProviderSnippet(snippet, "We couldn't locate the entry file \u2014 drop these lines into your app's root.");
+    return;
+  }
+  const source = await readFile13(entry, "utf8");
+  const result = wrapWithSightmapProvider(source, { framework: detect.framework });
+  if (!result.changed) {
+    const snippet = renderProviderSnippet({
+      framework: detect.framework,
+      cwd: opts.cwd,
+      entryAbsPath: entry
+    });
+    const note = result.reason ? `Codemod skipped: ${result.reason}.` : void 0;
+    showProviderSnippet(snippet, note);
+    return;
+  }
+  if (opts.yes) {
+    await writeFile7(entry, result.code, "utf8");
+    return;
+  }
+  const entryRel = relativePath(opts.cwd, entry);
+  const choice = await selectProviderAction(entryRel);
+  if (choice === "auto") {
+    await writeFile7(entry, result.code, "utf8");
+  } else if (choice === "snippet") {
+    const snippet = renderProviderSnippet({
+      framework: detect.framework,
+      cwd: opts.cwd,
+      entryAbsPath: entry
+    });
+    showProviderSnippet(snippet);
+  }
+}
+function relativePath(cwd, abs) {
+  if (abs.startsWith(cwd + "/")) return abs.slice(cwd.length + 1);
+  return abs;
+}
+async function findAppEntry(cwd, framework) {
+  const candidates = {
+    "react-vite": ["src/main.tsx", "src/main.jsx", "src/index.tsx", "src/index.jsx"],
+    "react-cra": ["src/index.tsx", "src/index.jsx"],
+    "next-app": ["app/layout.tsx", "app/layout.jsx"],
+    "next-pages": ["pages/_app.tsx", "pages/_app.jsx"],
+    "react-router-7": ["app/root.tsx", "app/root.jsx", "src/root.tsx"],
+    unknown: []
+  };
+  for (const rel of candidates[framework]) {
+    const abs = resolve22(cwd, rel);
+    try {
+      await readFile13(abs, "utf8");
+      return abs;
+    } catch {
+    }
+  }
+  return null;
+}
+async function runExistingCorpusFlow(cwd, viewCount) {
+  const spinner2 = clack2.spinner();
+  spinner2.start("Auditing existing corpus...");
+  await runLint({ path: ".sightmap", cwd, json: false, strict: false });
+  spinner2.stop("Audit complete");
+  const header = `${viewCount} view${viewCount === 1 ? "" : "s"}`;
+  const body = formatExistingCorpusReport({ viewCount, diagnostics: [] });
+  clack2.log.message(`${header}
+
+${body}`);
+}
+async function resolveHosts(opts, detect) {
+  if (opts.hosts) {
+    const valid = /* @__PURE__ */ new Set(["claude-code", "codex", "cursor", "opencode"]);
+    const invalid = opts.hosts.filter((h) => !valid.has(h));
+    if (invalid.length > 0) {
+      throw new Error(
+        `Unknown host(s): ${invalid.join(", ")}. Valid: claude-code, codex, cursor, opencode`
+      );
+    }
+    return opts.hosts;
+  }
+  if (opts.yes) return detect.hosts.length > 0 ? detect.hosts : ["claude-code"];
+  const defaults = detect.hosts.length > 0 ? detect.hosts : ["claude-code"];
+  const choice = await selectHosts(detect.hosts, defaults);
+  if (typeof choice === "symbol") return [];
+  return choice;
+}
+function resolveBrowserBundle(opts, detect) {
+  if (opts.withBrowser) return true;
+  if (opts.curateOnly) return false;
+  return !detect.sightmapAwareVendor;
+}
+async function maybePickWorkspace(opts) {
+  const all = await enumerateWorkspaces({ root: opts.cwd });
+  if (all.length === 0) return null;
+  const withFramework = all.filter((w) => w.framework !== "unknown");
+  if (withFramework.length === 0) return null;
+  if (opts.yes) {
+    if (withFramework.length === 1) return withFramework[0];
+    clack2.log.warn(
+      `Found ${withFramework.length} workspaces with a framework. Re-run from one of them, or without -y to pick interactively.`
+    );
+    return null;
+  }
+  return selectWorkspace(withFramework);
+}
+async function writeMcpForHost(host, cwd, serverDef) {
+  const common = { cwd, serverName: "sightmap", serverDef };
+  if (host === "claude-code") return writeClaudeCodeMcp(common);
+  if (host === "cursor") return writeCursorMcp(common);
+  if (host === "opencode") return writeOpenCodeMcp(common);
+  if (host === "codex") {
+    return writeCodexMcp({
+      configPath: resolve22(process.env.HOME ?? cwd, ".codex/config.toml"),
+      serverName: "sightmap",
+      serverDef
+    });
+  }
+}
+
 // src/cli/index.ts
 var program = new Command();
 program.name("sightmap").description("CLI for the Sightmap spec \u2014 validate, lint, match, explain.").version("0.1.0");
@@ -1590,6 +2774,20 @@ program.command("fmt [path]").description("Canonicalize .sightmap/*.yaml files (
     process.exit(code);
   }
 );
+program.command("init").description("Initialize Sightmap in this project (detects framework + coding agent, writes config).").option("--yes", "accept all defaults (non-interactive)").option("--plugin", "force plugin install path").option("--manual", "force manual install path").option("--host <names>", "comma-separated hosts: claude-code,codex,cursor,opencode").option("--with-browser", "force bundled Playwright + browser tools").option("--curate-only", "force curation-only (skip browser tools)").option("--no-codegen", "skip sightmap-react gen").option("--no-provider", "skip <SightmapProvider> codemod").action(async (opts) => {
+  const code = await runInit({
+    cwd: program.opts().cwd,
+    yes: opts.yes === true,
+    ...opts.plugin ? { installPath: "plugin" } : {},
+    ...opts.manual ? { installPath: "manual" } : {},
+    ...opts.host !== void 0 ? { hosts: opts.host.split(",").map((s) => s.trim()) } : {},
+    ...opts.withBrowser ? { withBrowser: true } : {},
+    ...opts.curateOnly ? { curateOnly: true } : {},
+    ...opts.codegen === false ? { noCodegen: true } : {},
+    ...opts.provider === false ? { noProvider: true } : {}
+  });
+  process.exit(code);
+});
 program.parseAsync(process.argv).catch((err) => {
   process.stderr.write(`fatal: ${err instanceof Error ? err.message : String(err)}
 `);