1/**
2 * CLI entry point: prepare everything needed to enter the live variant poll loop.
3 *
4 * Does (all in one command):
5 *   1. Check .impeccable/live/config.json (returns config_missing if first-ever run)
6 *   2. Start the live server in the background (or reuse a running one)
7 *   3. Inject the browser script tag into the project's entry file
8 *   4. Read PRODUCT.md / DESIGN.md for project context
9 *   5. Print a single JSON blob with everything the agent needs
10 *
11 * After this, the agent's only remaining steps are:
12 *   - Open the project's live dev/preview URL in the browser (optional, if browser automation exists)—not `serverPort`; that port is the Impeccable helper for /live.js and /poll
13 *   - Enter the poll loop: `node live-poll.mjs`
14 *
15 * Usage:
16 *   node live.mjs                   # Prepare everything, print JSON, exit
17 *   node live.mjs --help
18 */
19 
20import { execSync } from 'node:child_process';
21import fs from 'node:fs';
22import path from 'node:path';
23import { fileURLToPath } from 'node:url';
24import { loadContext, resolveTargetSelection } from './context.mjs';
25import { resolveFiles } from './live-inject.mjs';
26import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
27import { resolveLiveTarget } from './live-target.mjs';
28 
29const __dirname = path.dirname(fileURLToPath(import.meta.url));
30 
31async function liveCli() {
32  const args = process.argv.slice(2);
33  const liveTarget = resolveLiveTarget(process.cwd(), args);
34 
35  if (args.includes('--help') || args.includes('-h')) {
36    console.log(`Usage: node live.mjs
37 
38Prepare everything for live variant mode in a single command:
39  - Checks .impeccable/live/config.json (required, created once per project)
40  - Starts (or reuses) the live server in the background
41  - Injects the browser script tag
42  - Reads PRODUCT.md / DESIGN.md for project context
43  - In monorepos, choose a child app first; --target <path> is the fallback/manual path
44 
45On success, prints a JSON blob with:
46  { ok, serverPort, serverToken, pageFiles, projectRoot, repoRoot, targetPath, productPath, designPath }
47 
48On target_selection_required, prints:
49  { ok: false, error: "target_selection_required", targetCandidates }
50 
51On config_missing, prints:
52  { ok: false, error: "config_missing", configPath, hint }
53 
54The agent should then:
55  1. If target_selection_required, ask which app to use and rerun from that child cwd
56  2. If config_missing, create the config and re-run this script
57  3. Optionally open the project's dev/preview URL in the browser (see reference/live.md—not serverPort)
58  4. Enter the poll loop: node live-poll.mjs`);
59    process.exit(0);
60  }
61 
62  const targetSelection = resolveTargetSelection(liveTarget.originalCwd, liveTarget.targetOptions);
63  if (targetSelection) {
64    console.log(JSON.stringify({
65      ok: false,
66      error: 'target_selection_required',
67      ...targetSelection,
68      hint: 'Ask the user which app Impeccable should use, then rerun live from that child app cwd. Use --target <path> only as a fallback or explicit path diagnostic.',
69    }, null, 2));
70    process.exit(0);
71  }
72 
73  const ctx = loadContext(liveTarget.originalCwd, liveTarget.targetOptions);
74  const activeCwd = ctx.projectRoot;
75  const outputTargetPath = liveTarget.targetPath || null;
76 
77  const missingContext = missingLiveContext(ctx);
78  if (missingContext.length > 0) {
79    console.log(JSON.stringify({
80      ok: false,
81      error: 'context_missing',
82      missing: missingContext,
83      nextCommand: missingContext.includes('PRODUCT.md') ? 'init' : 'document',
84      targetPath: outputTargetPath,
85      projectRoot: ctx.projectRoot,
86      repoRoot: ctx.repoRoot,
87      productPath: ctx.productPath,
88      designPath: ctx.designPath,
89    }, null, 2));
90    process.exit(0);
91  }
92 
93  // 1. Check config (fail fast if missing — no point starting anything else)
94  const checkOut = runScript('live-inject.mjs', ['--check'], { cwd: activeCwd });
95  const checkResult = safeParse(checkOut);
96  if (!checkResult || !checkResult.ok) {
97    console.log(JSON.stringify({
98      ...(checkResult || { ok: false, error: 'check_failed', raw: checkOut }),
99      targetPath: outputTargetPath,
100      projectRoot: ctx.projectRoot,
101      repoRoot: ctx.repoRoot,
102    }));
103    process.exit(0);
104  }
105 
106  // 2. Start server (or reuse existing)
107  const serverInfo = ensureServerRunning(activeCwd);
108  if (!serverInfo) {
109    console.log(JSON.stringify({ ok: false, error: 'server_start_failed' }));
110    process.exit(1);
111  }
112 
113  // 3. Inject the script tag at the current port
114  const injectOut = runScript('live-inject.mjs', ['--port', String(serverInfo.port)], { cwd: activeCwd });
115  const injectResult = safeParse(injectOut);
116  if (!injectResult || !injectResult.ok) {
117    console.log(JSON.stringify({
118      ok: false,
119      error: 'inject_failed',
120      detail: injectResult || injectOut,
121      serverPort: serverInfo.port,
122    }));
123    process.exit(1);
124  }
125 
126  // 4. Compute drift-heal: compare resolved inject targets against the
127  //    project's HTML files. Orphans are HTML files not covered by config.
128  //    Warning only — the agent decides whether to act.
129  const resolvedFiles = resolveFiles(activeCwd, checkResult.config);
130  const drift = scanForDrift(activeCwd, resolvedFiles, checkResult.config);
131 
132  // 5. Emit everything the agent needs
133  console.log(JSON.stringify({
134    ok: true,
135    serverPort: serverInfo.port,
136    serverToken: serverInfo.token,
137    pageFiles: resolvedFiles,
138    liveConfigPath: checkResult.path,
139    configDrift: drift,
140    targetPath: outputTargetPath,
141    projectRoot: ctx.projectRoot,
142    repoRoot: ctx.repoRoot,
143    hasProduct: ctx.hasProduct,
144    product: ctx.product,
145    productPath: ctx.productPath,
146    hasDesign: ctx.hasDesign,
147    design: ctx.design,
148    designPath: ctx.designPath,
149  }, null, 2));
150}
151 
152function missingLiveContext(ctx) {
153  const missing = [];
154  if (!ctx.hasProduct) missing.push('PRODUCT.md');
155  if (!ctx.hasDesign) missing.push('DESIGN.md');
156  return missing;
157}
158 
159/**
160 * Drift-heal scan. Walks the project for HTML files under common
161 * page-source directories (public/, src/, app/, pages/) and reports any
162 * that aren't covered by the resolved inject targets. This is purely
163 * advisory — the agent can ignore it, or suggest the user add the
164 * orphans to config.files.
165 *
166 * Skipped if config.files already contains at least one glob pattern
167 * covering everything in practice (signaled by the orphan count being 0).
168 */
169function scanForDrift(rootDir, resolvedFiles, config) {
170  const SCAN_ROOTS = ['public', 'src', 'app', 'pages'];
171  const IGNORE_DIRS = new Set([
172    'node_modules', '.git', '.next', '.nuxt', '.svelte-kit', '.astro',
173    '.turbo', '.vercel', '.cache', 'coverage', 'dist', 'build',
174  ]);
175 
176  const resolvedSet = new Set(resolvedFiles.map((f) => f.split(path.sep).join('/')));
177 
178  // Files matching the user's `exclude` globs are intentional omissions,
179  // not drift. Compile them to regexes so the orphan list stays signal.
180  const userExcludeRegexes = (Array.isArray(config.exclude) ? config.exclude : [])
181    .map((p) => globToRegex(p));
182  const isUserExcluded = (rel) => userExcludeRegexes.some((re) => re.test(rel));
183 
184  const orphans = [];
185 
186  const walk = (dir, relBase) => {
187    let entries;
188    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
189    catch { return; }
190    for (const e of entries) {
191      const rel = relBase ? `${relBase}/${e.name}` : e.name;
192      if (e.isDirectory()) {
193        if (IGNORE_DIRS.has(e.name) || e.name.startsWith('.')) continue;
194        walk(path.join(dir, e.name), rel);
195      } else if (e.isFile() && e.name.endsWith('.html')) {
196        if (resolvedSet.has(rel)) continue;
197        if (isUserExcluded(rel)) continue;
198        orphans.push(rel);
199      }
200    }
201  };
202 
203  for (const root of SCAN_ROOTS) {
204    const abs = path.join(rootDir, root);
205    if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
206      walk(abs, root);
207    }
208  }
209 
210  if (orphans.length === 0) return null;
211  const capped = orphans.slice(0, 20);
212  return {
213    orphans: capped,
214    orphanCount: orphans.length,
215    hint: `${orphans.length} HTML file(s) exist but aren't in config.files. Consider adding them, or use a glob pattern like "public/**/*.html".`,
216  };
217}
218 
219/**
220 * Same glob-to-regex mapping used by live-inject.mjs. Kept inline here
221 * to avoid a circular import (live-inject.mjs already imports nothing
222 * from live.mjs). The two must stay in sync.
223 */
224function globToRegex(pattern) {
225  let re = '';
226  let i = 0;
227  while (i < pattern.length) {
228    const c = pattern[i];
229    if (c === '*') {
230      if (pattern[i + 1] === '*') {
231        if (pattern[i + 2] === '/') { re += '(?:.*/)?'; i += 3; }
232        else { re += '.*'; i += 2; }
233      } else {
234        re += '[^/]*';
235        i += 1;
236      }
237    } else if (c === '?') {
238      re += '[^/]';
239      i += 1;
240    } else if (/[.+^${}()|[\]\\]/.test(c)) {
241      re += '\\' + c;
242      i += 1;
243    } else {
244      re += c;
245      i += 1;
246    }
247  }
248  return new RegExp('^' + re + '$');
249}
250 
251// ---------------------------------------------------------------------------
252// Helpers
253// ---------------------------------------------------------------------------
254 
255function runScript(name, args, options = {}) {
256  const scriptPath = path.join(__dirname, name);
257  const cmd = `node "${scriptPath}" ${args.map(a => `"${a}"`).join(' ')}`;
258  try {
259    return execSync(cmd, { encoding: 'utf-8', cwd: options.cwd || process.cwd(), timeout: 15_000 });
260  } catch (err) {
261    // execSync throws on non-zero exit; return stdout if any
262    return err.stdout || err.message || '';
263  }
264}
265 
266function safeParse(out) {
267  try { return JSON.parse(String(out).trim()); } catch { return null; }
268}
269 
270/**
271 * Return { pid, port, token } for the running live server, starting one if needed.
272 */
273function ensureServerRunning(cwd = process.cwd()) {
274  // Try to reuse an existing server
275  try {
276    const existing = readLiveServerInfo(cwd)?.info;
277    if (existing && existing.pid) {
278      try {
279        process.kill(existing.pid, 0); // throws if dead
280        return existing;
281      } catch { /* stale PID file — the server script will clean it up */ }
282    }
283  } catch { /* no PID file */ }
284 
285  // Start a new server
286  const out = runScript('live-server.mjs', ['--background'], { cwd });
287  return safeParse(out);
288}
289 
290// ---------------------------------------------------------------------------
291// Auto-execute
292// ---------------------------------------------------------------------------
293 
294const _running = process.argv[1];
295if (_running?.endsWith('live.mjs') || _running?.endsWith('live.mjs/')) {
296  liveCli();
297}
298