@famonfa/mono 0.0.0-stage → 0.3.0

package/src/launcher.mjs

@@ -0,0 +1,276 @@
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { PKG_DIR, REPO_ROOT, writeConfig } from "./paths.mjs";
+import { STATUS_FILE, readRemote, writeRemote } from "./remote.mjs";
+
+const HOME = os.homedir();
+export const PORT = Number(process.env.PORT ?? 4600);
+export const APP_URL = `http://localhost:${PORT}`;
+/** The shared relay everyone signs in to; override with MONO_RELAY or `mono connect <url>`. */
+export const DEFAULT_RELAY = process.env.MONO_RELAY ?? "https://mono.155-181-39-178.sslip.io";
+const SERVER_MAIN = path.join(PKG_DIR, "src", "main.mjs");
+const CLI = path.join(PKG_DIR, "bin", "mono.mjs");
+/** `npx` runs from a cache folder that can disappear, so nothing long-lived should point at it. */
+const EPHEMERAL = PKG_DIR.includes(`${path.sep}_npx${path.sep}`);
+const BUNDLED_SKILL = path.join(PKG_DIR, "skills", "workspace");
+const SKILL_DIR = path.join(HOME, ".claude", "skills", "workspace");
+const LOG = path.join(HOME, "Library", "Logs", "mono.log");
+const SERVICE = "com.famonfa.mono";
+const PLIST = path.join(HOME, "Library", "LaunchAgents", `${SERVICE}.plist`);
+const PATH = [path.join(HOME, ".local/bin"), path.join(HOME, ".npm-global/bin"), "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"].join(":");
+
+export async function isUp() {
+  try {
+    const res = await fetch(`${APP_URL}/api/health`, { signal: AbortSignal.timeout(800) });
+    return res.ok && (await res.json()).app === "mono";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Lets the desktop app find the server without hardcoding a path, and gives Claude Code the
+ * `/workspace` skill that "Actualizar con IA" relies on (never overwriting one you already have).
+ */
+function setup() {
+  if (!EPHEMERAL) writeConfig({ server: SERVER_MAIN, node: process.execPath });
+  if (fs.existsSync(BUNDLED_SKILL) && !fs.existsSync(SKILL_DIR)) fs.cpSync(BUNDLED_SKILL, SKILL_DIR, { recursive: true });
+}
+
+/** Starts the server in the background unless it (or the launchd service) is already up. */
+export async function ensureServer() {
+  setup();
+  if (await isUp()) return;
+  fs.mkdirSync(path.dirname(LOG), { recursive: true });
+  const out = fs.openSync(LOG, "a");
+  spawn(process.execPath, [SERVER_MAIN], { cwd: HOME, detached: true, stdio: ["ignore", out, out], env: { ...process.env, PATH: `${PATH}:${process.env.PATH}` } }).unref();
+  for (let i = 0; i < 40; i++) {
+    await new Promise((r) => setTimeout(r, 250));
+    if (await isUp()) return;
+  }
+  throw new Error(`El server no arrancó; mirá ${LOG}`);
+}
+
+const USER_APP = path.join(HOME, "Applications", "Mono.app");
+
+function appVersion(app) {
+  try {
+    return execFileSync("plutil", ["-extract", "CFBundleShortVersionString", "raw", "-o", "-", path.join(app, "Contents", "Info.plist")], { encoding: "utf8" }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Installs (or updates) the desktop app into ~/Applications. Downloaded here rather than in a
+ * browser, the app carries no quarantine flag, so macOS opens it without the "unverified" warning.
+ */
+async function installDesktop() {
+  const wanted = JSON.parse(fs.readFileSync(path.join(PKG_DIR, "package.json"), "utf8")).version;
+  const existing = ["/Applications/Mono.app", USER_APP].find((p) => fs.existsSync(p));
+  if (existing && appVersion(existing) === wanted) return existing;
+
+  const url = `${DEFAULT_RELAY}/_mono/download/Mono-${process.arch === "arm64" ? "arm64" : "x64"}.zip`;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`no pude bajar la app (${res.status})`);
+  const total = Number(res.headers.get("content-length")) || 0;
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "mono-app-"));
+  const zip = path.join(work, "Mono.zip");
+  const out = fs.createWriteStream(zip);
+  let done = 0;
+  for await (const chunk of res.body) {
+    out.write(chunk);
+    done += chunk.length;
+    if (total && process.stdout.isTTY) process.stdout.write(`\r${existing ? "Actualizando" : "Bajando"} la app de Mono… ${Math.round((done / total) * 100)}%`);
+  }
+  await new Promise((resolve) => out.end(resolve));
+  if (process.stdout.isTTY) process.stdout.write("\n");
+  execFileSync("ditto", ["-x", "-k", zip, work]);
+
+  fs.mkdirSync(path.dirname(USER_APP), { recursive: true });
+  if (existing) {
+    // macOS only lets Finder remove installed apps; the shell gets a half-deleted bundle.
+    try {
+      execFileSync("osascript", ["-e", `tell application "Finder" to delete (POSIX file "${existing}" as alias)`], { stdio: "ignore" });
+    } catch {
+      throw new Error(`no pude reemplazar ${existing}: tiralo a la papelera y volvé a correr el comando`);
+    }
+  }
+  fs.renameSync(path.join(work, "Mono.app"), USER_APP);
+  fs.rmSync(work, { recursive: true, force: true });
+  return USER_APP;
+}
+
+/**
+ * Opens Mono in its desktop app, installing it on first run. `--web` (or a failed download) falls
+ * back to the browser; a monorepo checkout uses its dev Electron shell.
+ */
+export async function openApp({ hash = "", web = false } = {}) {
+  const electron = REPO_ROOT && path.join(REPO_ROOT, "node_modules", ".bin", "electron");
+  if (!web && electron && fs.existsSync(electron)) {
+    // Terminals inside Electron-based apps export ELECTRON_RUN_AS_NODE, which would start Electron as plain Node.
+    const { ELECTRON_RUN_AS_NODE, ...env } = process.env;
+    spawn(electron, [path.join(REPO_ROOT, "apps", "desktop")], { detached: true, stdio: "ignore", env: { ...env, MONO_HASH: hash } }).unref();
+    return "desktop";
+  }
+  if (!web && process.platform === "darwin") {
+    try {
+      const app = await installDesktop();
+      // `open` forwards the caller's environment; from a terminal inside an Electron-based app that
+      // includes ELECTRON_RUN_AS_NODE, which would make Mono start as plain Node and quit.
+      const { ELECTRON_RUN_AS_NODE, ...env } = process.env;
+      execFileSync("open", ["-a", app], { env });
+      return "desktop";
+    } catch (error) {
+      console.log(`No pude abrir la app de escritorio (${error.message}); la abro en el navegador.`);
+    }
+  }
+  execFileSync("open", [`${APP_URL}/${hash}`]);
+  return "browser";
+}
+
+export async function launch({ hash, web } = {}) {
+  await ensureServer();
+  const where = await openApp({ hash, web });
+  console.log(where === "desktop" ? "🐒 Mono abierto" : `🐒 Mono en ${APP_URL}`);
+}
+
+/**
+ * `npx @famonfa/mono` runs from npm's cache, which can be wiped, while the server has to outlive it
+ * (launchd, remote access). So npx only bootstraps: it installs the same version into ~/.mono/runtime
+ * once and hands every command to that copy.
+ */
+export function runFromRuntime() {
+  if (!EPHEMERAL || process.env.MONO_NO_BOOTSTRAP) return;
+  const pkg = JSON.parse(fs.readFileSync(path.join(PKG_DIR, "package.json"), "utf8"));
+  const runtime = path.join(HOME, ".mono", "runtime");
+  const installed = path.join(runtime, "node_modules", ...pkg.name.split("/"));
+  let current = null;
+  try {
+    current = JSON.parse(fs.readFileSync(path.join(installed, "package.json"), "utf8")).version;
+  } catch {}
+  if (current !== pkg.version) {
+    console.log(current ? `Actualizando Mono ${current} → ${pkg.version}…` : `Instalando Mono ${pkg.version}…`);
+    fs.mkdirSync(runtime, { recursive: true });
+    if (!fs.existsSync(path.join(runtime, "package.json"))) fs.writeFileSync(path.join(runtime, "package.json"), '{ "private": true }\n');
+    execFileSync("npm", ["install", "--prefix", runtime, "--no-audit", "--no-fund", "--omit=dev", "--loglevel=error", process.env.MONO_RUNTIME_SPEC ?? `${pkg.name}@${pkg.version}`], { stdio: "inherit" });
+  }
+  const result = spawnSync(process.execPath, [path.join(installed, "bin", "mono.mjs"), ...process.argv.slice(2)], { stdio: "inherit", env: { ...process.env, MONO_NO_BOOTSTRAP: "1" } });
+  process.exit(result.status ?? 1);
+}
+
+
+/**
+ * Pairs this machine with a relay so the phone/web can reach it: the relay hands out a short code,
+ * you approve it signed in with Google, and the relay returns a host token saved in ~/.mono.
+ */
+export async function connect(relayArg, name = os.hostname().replace(/\.local$/, "")) {
+  const relay = new URL(relayArg ?? readRemote()?.relay ?? DEFAULT_RELAY).origin;
+  const post = async (route, body) => {
+    const res = await fetch(new URL(route, relay), { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error(json.error ?? `${res.status} ${res.statusText}`);
+    return json;
+  };
+  const { code, pollToken, url } = await post("/_mono/pair/start", { name });
+  console.log(`\nAbrí este link y entrá con Google para conectar "${name}":\n\n  ${url}\n\nCódigo: ${code}\n`);
+  try {
+    execFileSync("open", [url]);
+  } catch {}
+  const deadline = Date.now() + 10 * 60_000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 2000));
+    const result = await post("/_mono/pair/poll", { pollToken });
+    if (result.status === "approved") {
+      writeRemote({ relay, token: result.token, hostId: result.hostId, email: result.email, name });
+      // Remote access only helps if the server is still up after a reboot.
+      if (!fs.existsSync(PLIST) && !REPO_ROOT) installService();
+      await ensureServer();
+      console.log(`✓ ${name} conectado a ${relay} como ${result.email}. Abrí ${relay} desde el celular.`);
+      return;
+    }
+    if (result.status !== "pending") throw new Error("El código expiró o fue rechazado");
+  }
+  throw new Error("Se venció el tiempo para aprobar el código");
+}
+
+export function disconnect() {
+  writeRemote(null);
+  console.log("✓ Desconectado del relay");
+}
+
+/** How to spell commands back to the user: npx users don't have `mono` on their PATH. */
+const CMD = process.env.MONO_NO_BOOTSTRAP ? "npx @famonfa/mono" : "mono";
+
+export async function status() {
+  const remote = readRemote();
+  let live = null;
+  try {
+    live = JSON.parse(fs.readFileSync(STATUS_FILE, "utf8"));
+  } catch {}
+  console.log(`Server:  ${(await isUp()) ? `✓ ${APP_URL}` : `✗ apagado (corré \`${CMD}\`)`}`);
+  console.log(`Servicio: ${fs.existsSync(PLIST) ? "instalado (arranca solo al iniciar sesión)" : `no instalado (\`${CMD} service install\`)`}`);
+  if (!remote) return console.log(`Remoto:  sin conectar (\`${CMD} connect\`)`);
+  console.log(`Remoto:  ${remote.relay} · ${remote.email} · ${live?.state ?? "?"}${live?.reason ? ` (${live.reason})` : ""}`);
+}
+
+/** Runs the server at login via launchd and puts `mono`/`ws` on PATH. */
+export function installService({ ifMissing = false } = {}) {
+  // The desktop app asks with ifMissing so it never replaces a service someone set up from a checkout.
+  if (ifMissing && fs.existsSync(PLIST)) return console.log(`✓ Servicio ${SERVICE} ya instalado`);
+  if (EPHEMERAL) throw new Error("Corré `npx @famonfa/mono service install`");
+  setup();
+  // npm's global install already puts mono/ws on PATH; a checkout links them into ~/.local/bin.
+  if (REPO_ROOT) {
+    const bin = path.join(HOME, ".local", "bin");
+    fs.mkdirSync(bin, { recursive: true });
+    for (const name of ["mono", "ws"]) {
+      fs.rmSync(path.join(bin, name), { force: true });
+      fs.symlinkSync(CLI, path.join(bin, name));
+    }
+  }
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${SERVICE}</string>
+  <key>ProgramArguments</key>
+  <array><string>${process.execPath}</string><string>${SERVER_MAIN}</string></array>
+  <key>WorkingDirectory</key><string>${HOME}</string>
+  <key>EnvironmentVariables</key>
+  <dict><key>PATH</key><string>${PATH}</string>${process.versions.electron ? "<key>ELECTRON_RUN_AS_NODE</key><string>1</string>" : ""}</dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${LOG}</string>
+  <key>StandardErrorPath</key><string>${LOG}</string>
+</dict>
+</plist>
+`;
+  fs.mkdirSync(path.dirname(PLIST), { recursive: true });
+  fs.writeFileSync(PLIST, plist);
+  const domain = `gui/${process.getuid()}`;
+  try {
+    execFileSync("launchctl", ["bootout", `${domain}/${SERVICE}`], { stdio: "ignore" });
+  } catch {}
+  // bootout finishes asynchronously; bootstrap fails with EIO until the old job is gone.
+  for (let attempt = 0; ; attempt++) {
+    try {
+      execFileSync("launchctl", ["bootstrap", domain, PLIST], { stdio: "pipe" });
+      break;
+    } catch (error) {
+      if (attempt >= 10) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 300);
+    }
+  }
+  console.log(`✓ Servicio ${SERVICE} → ${SERVER_MAIN}`);
+}
+
+export function uninstallService() {
+  try {
+    execFileSync("launchctl", ["bootout", `gui/${process.getuid()}/${SERVICE}`], { stdio: "ignore" });
+  } catch {}
+  fs.rmSync(PLIST, { force: true });
+  console.log(`✓ Servicio ${SERVICE} desinstalado`);
+}

package/src/main.mjs

@@ -0,0 +1,42 @@
+import http from "node:http";
+import { createApi, serveStatic } from "./api.mjs";
+import { startRemote } from "./remote.mjs";
+import { WEB_DIST as DIST } from "./paths.mjs";
+
+const PORT = Number(process.env.PORT ?? 4600);
+const HOST = "127.0.0.1";
+
+const clients = new Set();
+const relay = startRemote({ port: PORT });
+
+function broadcast(event, data) {
+  const frame = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+  for (const res of clients) res.write(frame);
+  relay.forward(frame);
+}
+
+const api = createApi(broadcast);
+
+const server = http.createServer((req, res) => {
+  if (req.url === "/api/events") {
+    res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" });
+    res.write("retry: 2000\n\n");
+    clients.add(res);
+    const ping = setInterval(() => res.write(": ping\n\n"), 25_000);
+    req.on("close", () => {
+      clearInterval(ping);
+      clients.delete(res);
+    });
+    return;
+  }
+  api(req, res, () => {
+    const rel = decodeURIComponent(req.url.split("?")[0]).replace(/^\/+/, "");
+    if (rel && serveStatic(res, DIST, rel)) return;
+    if (!serveStatic(res, DIST, "index.html")) {
+      res.statusCode = 503;
+      res.end("Falta compilar la app: npm run build");
+    }
+  });
+});
+
+server.listen(PORT, HOST, () => console.log(`Mono en http://localhost:${PORT}`));

package/src/paths.mjs

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Where things live. Mono runs either from the monorepo checkout (`~/mono`, during development) or
+ * from the npm package (`npm i -g @famonfa/mono`); both resolve here so nothing else cares which.
+ */
+
+const HOME = os.homedir();
+export const PKG_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const repo = path.resolve(PKG_DIR, "../..");
+/** The monorepo root when running from a checkout, otherwise null. */
+export const REPO_ROOT = fs.existsSync(path.join(repo, "apps", "web", "package.json")) ? repo : null;
+
+export const CONFIG_DIR = path.join(HOME, ".mono");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+
+export function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(patch) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify({ ...readConfig(), ...patch }, null, 2));
+}
+
+/** The built UI: bundled into the package, or the web app's build output in a checkout. */
+export const WEB_DIST = [path.join(PKG_DIR, "web"), REPO_ROOT && path.join(REPO_ROOT, "apps", "web", "dist")].filter(Boolean).find((dir) => fs.existsSync(path.join(dir, "index.html"))) ?? path.join(PKG_DIR, "web");
+
+/** Tasks, boards and uploads. A checkout keeps its historical `data/` folder; installs use ~/.mono/data. */
+export const DATA_DIR =
+  process.env.MONO_DATA_DIR ?? readConfig().dataDir ?? (REPO_ROOT && fs.existsSync(path.join(REPO_ROOT, "data")) ? path.join(REPO_ROOT, "data") : path.join(CONFIG_DIR, "data"));
+
+/** Where chats start when no folder is picked (`defaultCwd` in ~/.mono/config.json; home otherwise). */
+export function defaultCwd() {
+  const dir = readConfig().defaultCwd;
+  return dir && fs.existsSync(dir) ? dir : HOME;
+}

package/src/projects.mjs

@@ -0,0 +1,199 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DATA_DIR } from "./store.mjs";
+
+const T3_DB = path.join(os.homedir(), ".t3", "userdata", "state.sqlite");
+const CLAUDE_CONFIG = path.join(os.homedir(), ".claude.json");
+const OVERRIDES_FILE = path.join(DATA_DIR, "projects.json");
+const CACHE_MS = 30_000;
+const FAVICONS = ["favicon.svg", "favicon.png", "favicon.ico", "public/favicon.svg", "public/favicon.png", "public/favicon.ico", "assets/favicon.svg", "assets/favicon.png", "app/favicon.ico", "static/favicon.ico"];
+const COLORS = ["#eb5757", "#f2994a", "#d9a23b", "#4cb782", "#26b5ce", "#5e6ad2", "#bb87fc", "#e15a97"];
+
+let cache = { at: 0, projects: [] };
+
+function realpath(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+function slug(text) {
+  return text
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function hashColor(text) {
+  let h = 0;
+  for (const ch of text) h = (h * 31 + ch.charCodeAt(0)) >>> 0;
+  return COLORS[h % COLORS.length];
+}
+
+export function readOverrides() {
+  try {
+    return JSON.parse(fs.readFileSync(OVERRIDES_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/** Projects T3 Code knows about (read-only), so both apps share the same list of directories. */
+function readT3Projects() {
+  if (!fs.existsSync(T3_DB)) return [];
+  try {
+    const out = execFileSync("sqlite3", ["-readonly", "-json", `file:${T3_DB}?mode=ro`, "select title, workspace_root as root from projection_projects where deleted_at is null order by created_at"], {
+      encoding: "utf8",
+      timeout: 5000,
+    });
+    return JSON.parse(out || "[]");
+  } catch {
+    return [];
+  }
+}
+
+/** Without T3 Code: the git repos Claude Code has been used in (keys of `projects` in ~/.claude.json). */
+function readClaudeProjects() {
+  try {
+    const dirs = Object.keys(JSON.parse(fs.readFileSync(CLAUDE_CONFIG, "utf8")).projects ?? {});
+    return dirs.filter((dir) => dir !== os.homedir() && fs.existsSync(path.join(dir, ".git"))).map((root) => ({ title: path.basename(root), root }));
+  } catch {
+    return [];
+  }
+}
+
+/** Every project T3 knows, including ones nested inside another (internal: folder pickers, launch roots). */
+export function allProjects({ fresh = false } = {}) {
+  if (!fresh && Date.now() - cache.at < CACHE_MS) return cache.projects;
+  const overrides = readOverrides();
+  const seen = new Set();
+  const projects = [];
+  const t3 = readT3Projects();
+  for (const { title, root } of [...(t3.length ? t3 : readClaudeProjects()), ...(overrides.extra ?? [])]) {
+    const real = realpath(root);
+    if (seen.has(real) || !fs.existsSync(real)) continue;
+    seen.add(real);
+    const custom = overrides[real] ?? {};
+    let id = slug(title) || slug(path.basename(real));
+    while (projects.some((p) => p.id === id)) id = `${id}-2`;
+    const favicon = FAVICONS.map((f) => path.join(real, f)).find((f) => fs.existsSync(f));
+    const name = custom.title ?? title;
+    projects.push({
+      id,
+      title: name,
+      root: real,
+      initials: (name[0] + name[name.length - 1]).toUpperCase(),
+      color: custom.color ?? hashColor(name),
+      favicon: custom.color ? undefined : favicon,
+    });
+  }
+  for (const project of projects) project.parentId = parentOf(project, projects)?.id ?? null;
+  cache = { at: Date.now(), projects };
+  return projects;
+}
+
+const HOME_DIR = realpath(os.homedir());
+const isInside = (dir, root) => dir === root || dir.startsWith(root + path.sep);
+
+/**
+ * The nearest project that contains this one (avocado contains instamenu, KDS…). The home folder is a
+ * catch-all project, so it never acts as a parent.
+ */
+function parentOf(project, projects) {
+  return projects
+    .filter((p) => p !== project && p.root !== HOME_DIR && isInside(project.root, p.root))
+    .sort((a, b) => b.root.length - a.root.length)[0];
+}
+
+/**
+ * Projects shown in the app: only outermost ones. A repo inside avocado (instamenu, KDS…) is a folder of
+ * avocado, not a project of its own — avocado is the single home for that family and holds the skills.
+ */
+export function listProjects(opts) {
+  return allProjects(opts).filter((p) => !p.parentId);
+}
+
+function topProjectId(id) {
+  const projects = allProjects();
+  let current = projects.find((p) => p.id === id);
+  while (current?.parentId) current = projects.find((p) => p.id === current.parentId);
+  return current?.id ?? null;
+}
+
+export function descendantIds(projectId) {
+  const projects = allProjects();
+  const ids = new Set([projectId]);
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const p of projects) if (p.parentId && ids.has(p.parentId) && !ids.has(p.id)) (ids.add(p.id), (grew = true));
+  }
+  return ids;
+}
+
+/**
+ * Where a session must start so it loads the shared skills and CLAUDE.md: the outermost project that
+ * contains the folder (avocado for anything under it). Claude Code doesn't load skills from parent folders.
+ */
+export function launchRootFor(dir) {
+  const real = realpath(dir);
+  const main = mainRepoRoot(real) ?? real;
+  const containing = allProjects().filter((p) => p.root !== HOME_DIR && (isInside(real, p.root) || isInside(main, p.root)));
+  return containing.sort((a, b) => a.root.length - b.root.length)[0]?.root ?? real;
+}
+
+export function saveOverride(projectId, patch) {
+  const project = listProjects().find((p) => p.id === projectId);
+  if (!project) throw new Error(`No existe el proyecto ${projectId}`);
+  const overrides = readOverrides();
+  overrides[project.root] = { ...overrides[project.root], ...patch };
+  fs.mkdirSync(path.dirname(OVERRIDES_FILE), { recursive: true });
+  fs.writeFileSync(OVERRIDES_FILE, JSON.stringify(overrides, null, 2));
+  return allProjects({ fresh: true }).find((p) => p.root === project.root);
+}
+
+const repoRootCache = new Map();
+
+/** For a path inside a git worktree, the main checkout it belongs to (so `.worktrees/X/KDS` counts as KDS). */
+function mainRepoRoot(dir) {
+  if (repoRootCache.has(dir)) return repoRootCache.get(dir);
+  let root = null;
+  try {
+    const common = execFileSync("git", ["-C", dir, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (common.endsWith(`${path.sep}.git`)) root = realpath(path.dirname(common));
+  } catch {}
+  repoRootCache.set(dir, root);
+  return root;
+}
+
+export function projectForPath(dir) {
+  if (!dir) return null;
+  const real = realpath(dir);
+  const candidates = [mainRepoRoot(real), real].filter(Boolean);
+  const projects = listProjects();
+  for (const candidate of candidates) {
+    const match = projects
+      .filter((p) => candidate === p.root || candidate.startsWith(p.root + path.sep))
+      .sort((a, b) => b.root.length - a.root.length)[0];
+    if (match) return match.id;
+  }
+  return null;
+}
+
+/** Explicit `projects` on the task win; otherwise repos are matched to projects by folder or title. Nested ones roll up to their outermost project. */
+export function projectsForTask(task) {
+  const projects = allProjects();
+  const explicit = Array.isArray(task.projects) && task.projects.length ? task.projects : null;
+  const ids = explicit ?? (task.repos ?? []).map((repo) => projects.find((p) => path.basename(p.root) === repo.name || p.title === repo.name)?.id);
+  return [...new Set(ids.map((id) => id && topProjectId(id)).filter(Boolean))];
+}
+
+export function projectIcon(projectId) {
+  return allProjects().find((p) => p.id === projectId)?.favicon ?? null;
+}