amare/.github/skills/impeccable/scripts/live/roots.mjs

/**
 * Live root resolution: the single place that decides which directories a live
 * session operates on. Every live entry script resolves this once at startup
 * (see enterLiveRoot) instead of trusting its ambient cwd, which is how a
 * `cd` used to silently fork the whole system into a second, empty project.
 *
 * Four distinct roots travel together as one manifest:
 *
 *   appRoot     what the dev server serves; where live session state,
 *               injected adapters, and preview modules live.
 *   repoRoot    the git boundary (falls back to appRoot outside git).
 *   contextRoot the nearest directory from appRoot up to repoRoot carrying
 *               PRODUCT.md / DESIGN.md (canonical spot or a fallback dir).
 *   sessionRoot <appRoot>/.impeccable/live — durable live state.
 *
 * appRoot detection keys on dev-server config presence (vite/svelte/next/
 * astro/nuxt/... config files), not on monorepo brand markers. A nested
 * website/ with vite.config.js wins over a repo root that merely has a
 * package.json. Workspace declarations are one input, not the gatekeeper.
 *
 * The resolved manifest is persisted at <appRoot>/.impeccable/live/roots.json
 * plus a pointer at <repoRoot>/.impeccable/live/app-root.json when the two
 * differ, so a helper invoked from anywhere inside the repo finds the same
 * roots the boot decided on. When several apps in one repo run live, the
 * pointer follows the most recent boot; per-app roots.json files stay put.
 */
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { execFileSync } from 'node:child_process';
import { resolveProjectRoot } from '../context.mjs';

const ROOTS_MANIFEST_VERSION = 1;
const ROOTS_FILE = 'roots.json';
const POINTER_FILE = 'app-root.json';

const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
const CONTEXT_FALLBACK_DIRS = ['.agents/context', 'docs'];

// Presence of any of these marks a directory as a dev-served app root.
const DEV_CONFIG_MARKERS = [
  'vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.mts', 'vite.config.cjs',
  'svelte.config.js', 'svelte.config.mjs', 'svelte.config.ts',
  'next.config.js', 'next.config.mjs', 'next.config.ts',
  'astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.cjs',
  'nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs',
  'remix.config.js', 'react-router.config.ts',
  'angular.json',
  'webpack.config.js', 'webpack.config.ts',
];

const CANDIDATE_SCAN_IGNORED = new Set([
  'node_modules', '.git', 'dist', 'build', 'coverage', 'vendor', 'vendors',
  '.next', '.nuxt', '.svelte-kit', '.astro', '.turbo', '.cache', '.vercel',
]);
const CANDIDATE_SCAN_DEPTH = 2;

function exists(p) {
  try { fs.statSync(p); return true; } catch { return false; }
}

function isDir(p) {
  try { return fs.statSync(p).isDirectory(); } catch { return false; }
}

function firstExisting(dir, names) {
  for (const name of names) {
    const abs = path.join(dir, name);
    if (exists(abs)) return abs;
  }
  return null;
}

function hasDevConfig(dir) {
  if (DEV_CONFIG_MARKERS.some((name) => exists(path.join(dir, name)))) return true;
  // A plain Vite app can run with zero config: index.html + package.json.
  return exists(path.join(dir, 'index.html')) && exists(path.join(dir, 'package.json'));
}

function isAppRoot(dir) {
  // A directory already configured for live IS an app root, dev config or not
  // (plain static multi-page projects have no bundler config).
  return hasDevConfig(dir) || exists(path.join(dir, '.impeccable', 'live', 'config.json'));
}

function findContextFile(dir, names) {
  const direct = firstExisting(dir, names);
  if (direct) return direct;
  for (const rel of CONTEXT_FALLBACK_DIRS) {
    const nested = firstExisting(path.join(dir, rel), names);
    if (nested) return nested;
  }
  return null;
}

export function findGitRoot(startDir) {
  let dir = path.resolve(startDir);
  const home = path.resolve(os.homedir());
  while (true) {
    if (dir === home) return null;
    if (exists(path.join(dir, '.git'))) return dir;
    const parent = path.dirname(dir);
    if (parent === dir) return null;
    dir = parent;
  }
}

function walkUp(startDir, upperBound, visit) {
  let dir = path.resolve(startDir);
  const stop = path.resolve(upperBound);
  const home = path.resolve(os.homedir());
  while (true) {
    if (dir === home) return null;
    const hit = visit(dir);
    if (hit) return hit;
    if (dir === stop) return null;
    const parent = path.dirname(dir);
    if (parent === dir) return null;
    dir = parent;
  }
}

function insideOrEqual(candidate, root) {
  const rel = path.relative(path.resolve(root), path.resolve(candidate));
  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
}

/**
 * Scan downward (bounded depth) for directories carrying a dev-server config.
 * Used when live boots from a directory that is not itself an app root and no
 * --target narrows the choice: one candidate is auto-picked, several become a
 * selection prompt.
 */
export function discoverAppCandidates(rootDir, depth = CANDIDATE_SCAN_DEPTH) {
  const found = [];
  const scan = (dir, remaining) => {
    let entries;
    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
    for (const entry of entries) {
      if (!entry.isDirectory()) continue;
      if (entry.name.startsWith('.') || CANDIDATE_SCAN_IGNORED.has(entry.name)) continue;
      const abs = path.join(dir, entry.name);
      // Same criterion as the upward walk (isAppRoot): a live-configured
      // plain-static site with no bundler markers is still an app, and
      // missing it here would silently fall back to the wrong root.
      if (isAppRoot(abs)) {
        found.push(abs);
        continue; // nested apps below an app root are that app's business
      }
      if (remaining > 1) scan(abs, remaining - 1);
    }
  };
  scan(path.resolve(rootDir), depth);
  return found.sort();
}

/**
 * Fresh root resolution. Never reads a persisted manifest.
 *
 * Returns { manifest } on success or { selection } when several candidate
 * apps exist and nothing disambiguates.
 */
export function resolveRoots({ cwd = process.cwd(), targetPath = null } = {}) {
  const absCwd = path.resolve(cwd);
  const absTarget = targetPath
    ? (path.isAbsolute(targetPath) ? targetPath : path.resolve(absCwd, targetPath))
    : null;
  const targetDir = absTarget
    ? (isDir(absTarget) ? absTarget : path.dirname(absTarget))
    : absCwd;

  // The walk bound must be an ancestor of the target: a git root found from
  // the CWD is only usable when the target actually lives inside it,
  // otherwise the walk would climb out of both trees.
  const targetGitRoot = findGitRoot(targetDir);
  const cwdGitRoot = targetGitRoot ? null : findGitRoot(absCwd);
  const repoRoot = targetGitRoot
    || (cwdGitRoot && insideOrEqual(targetDir, cwdGitRoot) ? cwdGitRoot : null);
  // Without a git boundary, never ascend above the starting directory: the
  // filesystem above an unversioned project is not ours to interpret.
  const upperBound = repoRoot || targetDir;

  // The workspace-aware legacy resolution (context.mjs) still decides two
  // things: the fallback when no app marker exists, and how far the marker
  // walk may ascend when an explicit target selected a workspace child. A
  // root-level live config must never shadow a child the target picked.
  const legacyRoot = resolveProjectRoot(absCwd, absTarget ? { targetPath: absTarget } : {});
  const markerBound = absTarget && insideOrEqual(targetDir, legacyRoot) && insideOrEqual(legacyRoot, upperBound)
    ? legacyRoot
    : upperBound;

  let appRoot = walkUp(targetDir, markerBound, (dir) => (isAppRoot(dir) ? dir : null));
  let resolvedFrom = appRoot
    ? (absTarget ? `target:${path.relative(absCwd, absTarget) || '.'}` : 'cwd')
    : null;

  if (!appRoot && !absTarget) {
    const candidates = discoverAppCandidates(absCwd);
    if (candidates.length === 1) {
      appRoot = candidates[0];
      resolvedFrom = `candidate:${path.relative(absCwd, appRoot)}`;
    } else if (candidates.length > 1) {
      return {
        selection: {
          candidates: candidates.map((abs) => ({
            name: path.basename(abs),
            path: path.relative(absCwd, abs).split(path.sep).join('/'),
          })),
        },
      };
    }
  }

  if (!appRoot) {
    // No app marker anywhere: defer to the workspace-aware legacy resolution
    // (workspace child for a targeted monorepo path, cwd otherwise). Never
    // adopt an arbitrary ancestor just because it has a package.json, and
    // never adopt a root that does not even contain the target.
    appRoot = insideOrEqual(targetDir, legacyRoot) ? legacyRoot : targetDir;
    resolvedFrom = 'fallback';
  }

  const effectiveRepoRoot = repoRoot && insideOrEqual(appRoot, repoRoot) ? repoRoot : appRoot;

  // Each context file resolves independently: a child app may carry its own
  // PRODUCT.md while inheriting DESIGN.md from the repo root (or vice versa).
  const productPath = walkUp(appRoot, effectiveRepoRoot, (dir) => findContextFile(dir, PRODUCT_NAMES));
  const designPath = walkUp(appRoot, effectiveRepoRoot, (dir) => findContextFile(dir, DESIGN_NAMES));
  const contextRoot = productPath
    ? path.dirname(productPath)
    : designPath
      ? path.dirname(designPath)
      : null;

  return {
    manifest: {
      version: ROOTS_MANIFEST_VERSION,
      appRoot,
      repoRoot: effectiveRepoRoot,
      contextRoot,
      sessionRoot: path.join(appRoot, '.impeccable', 'live'),
      productPath,
      designPath,
      resolvedFrom,
    },
  };
}

function rootsFilePath(appRoot) {
  return path.join(appRoot, '.impeccable', 'live', ROOTS_FILE);
}

function pointerFilePath(repoRoot) {
  return path.join(repoRoot, '.impeccable', 'live', POINTER_FILE);
}

export function writeRootsManifest(manifest) {
  const file = rootsFilePath(manifest.appRoot);
  fs.mkdirSync(path.dirname(file), { recursive: true });
  fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
  if (path.resolve(manifest.repoRoot) !== path.resolve(manifest.appRoot)) {
    const pointer = pointerFilePath(manifest.repoRoot);
    fs.mkdirSync(path.dirname(pointer), { recursive: true });
    // The pointer records EVERY app that has booted live in this repo, most
    // recent first. A single last-boot-wins value made a helper run from the
    // repo root silently target whichever app booted last, even while an
    // earlier app's session was the one still live.
    const entries = readPointerEntries(manifest.repoRoot)
      .filter((entry) => path.resolve(entry.appRoot) !== path.resolve(manifest.appRoot));
    entries.unshift({ appRoot: manifest.appRoot, bootedAt: new Date().toISOString() });
    fs.writeFileSync(pointer, JSON.stringify({ version: 2, appRoots: entries }));
  }
  return file;
}

function readPointerEntries(repoRoot) {
  try {
    const raw = JSON.parse(fs.readFileSync(pointerFilePath(repoRoot), 'utf-8'));
    if (Array.isArray(raw?.appRoots)) {
      return raw.appRoots.filter((entry) => entry && typeof entry.appRoot === 'string');
    }
    // v1 shape: a single { appRoot } value.
    if (raw && typeof raw.appRoot === 'string') return [{ appRoot: raw.appRoot }];
    return [];
  } catch {
    return [];
  }
}

/**
 * True when the app's live helper server is recorded and its pid is alive.
 * A liveness signal alone misclassifies a REUSED pid (helper died without
 * removing server.json, the OS handed the pid to something else), so the
 * process's command line must also look like a node process; that removes
 * reuse by arbitrary processes. A pid reused by another node process remains
 * a residual false positive, which the multi-app warning and --target
 * escape hatch cover.
 */
function hasLiveServer(appRoot) {
  let pid;
  let port;
  let token;
  try {
    const info = JSON.parse(fs.readFileSync(path.join(appRoot, '.impeccable', 'live', 'server.json'), 'utf-8'));
    if (!info || typeof info.pid !== 'number') return false;
    pid = info.pid;
    port = Number(info.port);
    token = typeof info.token === 'string' ? info.token : null;
    process.kill(pid, 0);
  } catch (err) {
    // EPERM: the process exists but is not signalable by this user.
    if (err?.code !== 'EPERM') return false;
  }
  // Liveness alone misclassifies a REUSED pid, and a bare TCP connect
  // misclassifies a coincidental listener on a reused port. The decisive
  // signal is IDENTITY: the helper answers its authenticated /status
  // endpoint with the token server.json records; nothing else on that port
  // can. The probe is a spawned node one-liner so it works identically on
  // every platform.
  if (Number.isInteger(port) && port > 0 && token) {
    try {
      execFileSync(process.execPath, ['-e', [
        "const req = require('node:http').get({ host: '127.0.0.1', port: Number(process.argv[1]), path: '/status?token=' + encodeURIComponent(process.argv[2]), timeout: 1200 }, (res) => { res.resume(); process.exit(res.statusCode === 200 ? 0 : 1); });",
        "req.on('timeout', () => { req.destroy(); process.exit(1); });",
        "req.on('error', () => process.exit(1));",
      ].join(''), String(port), token], { timeout: 4000, stdio: 'ignore' });
      return true;
    } catch {
      return false;
    }
  }
  // Every server.json this codebase has ever written records port + token
  // (see writeLiveServerInfo). A record without them is malformed or foreign
  // and cannot be authenticated, so it does not count as a live helper;
  // resolution falls to the durable-session tier, which is the correct
  // recovery path for a stopped or crashed helper anyway.
  return false;
}

const TERMINAL_SESSION_PHASES = new Set(['completed', 'discarded']);

/**
 * True when the app's durable session store holds a session that is not
 * terminal. With every helper server stopped, this is what distinguishes
 * "the app whose interrupted session the user is trying to recover" from an
 * app that merely booted more recently.
 */
function hasActiveDurableSession(appRoot) {
  const dir = path.join(appRoot, '.impeccable', 'live', 'sessions');
  let entries;
  try {
    entries = fs.readdirSync(dir);
  } catch {
    return false;
  }
  for (const name of entries) {
    if (!name.endsWith('.snapshot.json')) continue;
    try {
      const snapshot = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8'));
      if (snapshot?.phase && !TERMINAL_SESSION_PHASES.has(snapshot.phase)) return true;
    } catch { /* skip unreadable snapshots */ }
  }
  return false;
}

function readManifestAt(appRoot) {
  try {
    const raw = JSON.parse(fs.readFileSync(rootsFilePath(appRoot), 'utf-8'));
    if (!raw || typeof raw.appRoot !== 'string') return null;
    // A manifest is only trusted where it claims to live; anything else is a
    // copied or stale file.
    if (path.resolve(raw.appRoot) !== path.resolve(appRoot)) return null;
    return raw;
  } catch {
    return null;
  }
}

/**
 * Resolve the roots for the live session governing `cwd`, preferring a
 * persisted manifest (written by the boot) over fresh detection:
 *
 *   1. Walk up from cwd looking for .impeccable/live/roots.json.
 *   2. At the git root, follow .impeccable/live/app-root.json to the app.
 *   3. Fresh resolveRoots().
 *
 * Fresh results are NOT persisted here; only the boot (live.mjs / server
 * startup) writes manifests, so ad-hoc helper invocations cannot mint
 * conflicting truth.
 */
export function resolveLiveRoots(cwd = process.cwd(), { targetPath = null } = {}) {
  const absCwd = path.resolve(cwd);

  if (!targetPath) {
    const persisted = walkUp(absCwd, findGitRoot(absCwd) || absCwd, (dir) => readManifestAt(dir));
    if (persisted) return { manifest: persisted, source: 'persisted' };

    const gitRoot = findGitRoot(absCwd);
    if (gitRoot) {
      // Several apps in one repo may have booted live. Preference order:
      // a running helper server, then an app whose durable store still holds
      // a non-terminal session (the stopped session the user is recovering),
      // then the most recent boot. A stale pointer entry must never redirect
      // status/poll/accept onto the wrong app's session store.
      const candidates = readPointerEntries(gitRoot)
        .map((entry) => readManifestAt(entry.appRoot))
        .filter(Boolean);
      if (candidates.length > 0) {
        const liveApps = candidates.filter((manifest) => hasLiveServer(manifest.appRoot));
        const recoveringApps = liveApps.length > 0
          ? liveApps
          : candidates.filter((manifest) => hasActiveDurableSession(manifest.appRoot));
        const tier = recoveringApps.length > 0 ? recoveringApps : candidates;
        // Multiple apps qualifying at the same tier is inherent ambiguity:
        // intent is unknowable from the repo root. The choice stays
        // deterministic (most recent boot first), but it must be LOUD, not
        // silent, so the agent can re-anchor when it meant the other app.
        if (tier.length > 1) {
          const chosen = tier[0].appRoot;
          const others = tier.slice(1).map((manifest) => manifest.appRoot).join(', ');
          process.stderr.write(
            `[impeccable live] Multiple apps in this repo have live state; using ${chosen}. `
            + `Other candidate(s): ${others}. Run from the app directory (or pass --target) to address a specific app.\n`,
          );
        }
        return { manifest: tier[0], source: 'pointer' };
      }
    }
  }

  const fresh = resolveRoots({ cwd: absCwd, targetPath });
  if (fresh.selection) return { selection: fresh.selection, source: 'fresh' };
  return { manifest: fresh.manifest, source: 'fresh' };
}

/**
 * Consume a `--target <path>` / `--target=<path>` pair from an argv array,
 * returning the value and removing the tokens so downstream flag parsers
 * (which do not know the option) never see them.
 */
export function consumeTargetArg(argv = process.argv) {
  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
    if (arg === '--target') {
      const value = argv[i + 1];
      // A --target with no usable value must not degrade into implicit root
      // selection: these helpers mutate session state, and "the most recent
      // app" is exactly what the caller was trying NOT to get.
      if (typeof value !== 'string' || value === '' || value.startsWith('--')) {
        throw new Error('--target requires a path value (use --target <path> or --target=<path>)');
      }
      argv.splice(i, 2);
      return value;
    }
    if (typeof arg === 'string' && arg.startsWith('--target=')) {
      const value = arg.slice('--target='.length);
      if (value === '') {
        throw new Error('--target requires a path value (use --target <path> or --target=<path>)');
      }
      argv.splice(i, 1);
      return value;
    }
  }
  return null;
}

/**
 * Entry-point guard for live CLI scripts: resolve the governing roots and
 * make appRoot the process cwd so every downstream path derivation agrees
 * with the boot. An explicit `--target <path>` on the helper's command line
 * overrides pointer resolution, which is what disambiguates a repo with
 * several live apps (the multi-app warning names this escape hatch, so it
 * has to actually work on every helper). Returns the manifest. On selection
 * ambiguity it stays in the current directory (the boot flow handles
 * prompting); a malformed --target exits with an error instead of silently
 * falling back to implicit selection, which could mutate the wrong app.
 */
export function enterLiveRoot(cwd = process.cwd()) {
  let targetPath;
  try {
    targetPath = consumeTargetArg(process.argv);
  } catch (err) {
    console.error(`[impeccable live] ${err.message}`);
    process.exit(1);
  }
  const resolved = resolveLiveRoots(cwd, targetPath ? { targetPath } : {});
  if (!resolved.manifest) return null;
  const appRoot = resolved.manifest.appRoot;
  if (path.resolve(cwd) !== path.resolve(appRoot)) {
    // Failing to land on the resolved appRoot must be fatal: a helper that
    // silently keeps its ambient cwd derives server, session, and source
    // paths from a different project and mutates the wrong state. A manifest
    // pointing at a deleted directory is stale ambient truth, not a reason
    // to guess.
    if (!isDir(appRoot)) {
      console.error(`[impeccable live] resolved app root does not exist: ${appRoot} (stale roots manifest? re-run the live boot, or pass --target <path>)`);
      process.exit(1);
    }
    try {
      process.chdir(appRoot);
    } catch (err) {
      console.error(`[impeccable live] could not enter app root ${appRoot}: ${err.message}`);
      process.exit(1);
    }
  }
  return resolved.manifest;
}