1/**
2 * Context loader: prints PRODUCT.md (and DESIGN.md if present) as one
3 * markdown block on stdout, or exits with empty stdout when no PRODUCT.md
4 * is found anywhere. The skill keys off "empty stdout" to branch into the
5 * init flow.
6 *
7 * Path resolution (first match wins):
8 *   1. Active project root, if PRODUCT.md or DESIGN.md is there
9 *   2. Active project .agents/context/ then docs/
10 *   3. Monorepo root context, using the same order, as a per-file fallback
11 *   4. $IMPECCABLE_CONTEXT_DIR (absolute or cwd-relative) — power-user
12 *      escape hatch, only consulted when defaults are empty
13 *   5. Active project root as a "nothing found" default
14 *
15 * `resolveContextDir()` and `loadContext()` are also exported for the
16 * server-side scripts (live.mjs, live-server.mjs) that need the structured
17 * shape rather than the markdown block.
18 */
19import fs from 'node:fs';
20import os from 'node:os';
21import path from 'node:path';
22import { fileURLToPath } from 'node:url';
23import { parseTargetOptions } from './lib/target-args.mjs';
24 
25const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
26const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
27const FALLBACK_DIRS = ['.agents/context', 'docs'];
28const MONOREPO_MARKER_FILES = ['pnpm-workspace.yaml', 'turbo.json', 'nx.json', 'lerna.json'];
29const MONOREPO_FALLBACK_PROJECT_DIRS = ['apps', 'packages'];
30const WORKSPACE_DISCOVERY_IGNORED_DIRS = new Set([
31  'node_modules',
32  '.git',
33  'dist',
34  'build',
35  '.next',
36  '.nuxt',
37  '.svelte-kit',
38  '.turbo',
39  '.cache',
40  'coverage',
41]);
42 
43// ─── Update check ──────────────────────────────────────────────────────────
44// Piggyback a lightweight skill-version check on the once-per-session boot.
45// When a newer skill ships, append an UPDATE_AVAILABLE directive so the agent
46// can offer `npx impeccable update`. Everything here is best-effort and
47// silent on failure: a network problem, sandbox, or missing cache must never
48// block context output or print an error.
49 
50const UPDATE_HOST = (process.env.IMPECCABLE_UPDATE_HOST || 'https://impeccable.style').replace(/\/$/, '');
51const UPDATE_CACHE_PATH =
52  process.env.IMPECCABLE_UPDATE_CACHE || path.join(os.homedir(), '.impeccable', 'update-check.json');
53const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // throttle the network poll to once a day
54const RENOTIFY_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000; // don't re-surface the same version for a week
55const FETCH_TIMEOUT_MS = 1200;
56 
57export function resolveContextDir(cwd = process.cwd(), options = {}) {
58  return resolveContext(cwd, options).contextDir;
59}
60 
61export function loadContext(cwd = process.cwd(), options = {}) {
62  const resolved = resolveContext(cwd, options);
63  const absCwd = path.resolve(cwd);
64  const productPath = resolved.productPath;
65  const designPath = resolved.designPath;
66  const product = productPath ? safeRead(productPath) : null;
67  const design = designPath ? safeRead(designPath) : null;
68  return {
69    hasProduct: !!product,
70    product,
71    productPath: productPath ? path.relative(absCwd, productPath) : null,
72    hasDesign: !!design,
73    design,
74    designPath: designPath ? path.relative(absCwd, designPath) : null,
75    contextDir: resolved.contextDir,
76    productContextDir: productPath ? path.dirname(productPath) : null,
77    designContextDir: designPath ? path.dirname(designPath) : null,
78    projectRoot: resolved.projectRoot,
79    repoRoot: resolved.repoRoot,
80    isMonorepo: resolved.isMonorepo,
81  };
82}
83 
84function resolveContext(cwd = process.cwd(), options = {}) {
85  const absCwd = path.resolve(cwd);
86  const project = resolveProject(absCwd, options);
87  const projectContextDir = resolveLocalContextDir(project.projectRoot);
88  const rootContextDir = project.isMonorepo && project.repoRoot !== project.projectRoot
89    ? resolveLocalContextDir(project.repoRoot)
90    : null;
91 
92  let productPath =
93    (projectContextDir ? firstExisting(projectContextDir, PRODUCT_NAMES) : null)
94    || (rootContextDir ? firstExisting(rootContextDir, PRODUCT_NAMES) : null);
95  let designPath =
96    (projectContextDir ? firstExisting(projectContextDir, DESIGN_NAMES) : null)
97    || (rootContextDir ? firstExisting(rootContextDir, DESIGN_NAMES) : null);
98 
99  let envContextDir = null;
100  if (!productPath && !designPath) {
101    envContextDir = resolveEnvContextDir(absCwd);
102    if (envContextDir) {
103      productPath = firstExisting(envContextDir, PRODUCT_NAMES);
104      designPath = firstExisting(envContextDir, DESIGN_NAMES);
105    }
106  }
107 
108  return {
109    contextDir: productPath
110      ? path.dirname(productPath)
111      : designPath
112        ? path.dirname(designPath)
113        : envContextDir || project.projectRoot,
114    productPath,
115    designPath,
116    projectRoot: project.projectRoot,
117    repoRoot: project.repoRoot,
118    isMonorepo: project.isMonorepo,
119    targetDir: project.targetDir,
120  };
121}
122 
123export function resolveProjectRoot(cwd = process.cwd(), options = {}) {
124  return resolveProject(cwd, options).projectRoot;
125}
126 
127export function resolveTargetSelection(cwd = process.cwd(), options = {}) {
128  if (hasTargetOption(options)) return null;
129  const project = resolveProject(cwd);
130  if (
131    !project.isMonorepo
132    || !project.projectRoot
133    || !project.repoRoot
134    || path.resolve(project.projectRoot) !== path.resolve(project.repoRoot)
135  ) {
136    return null;
137  }
138  const targetCandidates = discoverTargetCandidates(project.repoRoot);
139  // No discoverable child apps (e.g. `workspaces: ["."]`, a root-only workspace,
140  // or a marker file with no apps/packages children): there is nothing to choose,
141  // so treat the repo root as the active project rather than blocking on an empty
142  // selection prompt that the user cannot answer.
143  if (targetCandidates.length === 0) return null;
144  return {
145    targetPath: null,
146    projectRoot: project.projectRoot,
147    repoRoot: project.repoRoot,
148    targetCandidates,
149  };
150}
151 
152function resolveProject(cwd = process.cwd(), options = {}) {
153  const absCwd = path.resolve(cwd);
154  const targetDir = resolveTargetDir(absCwd, options);
155  let repoRoot = findMonorepoRoot(targetDir);
156  if (!repoRoot && targetDir !== absCwd) {
157    const cwdRepoRoot = findMonorepoRoot(absCwd);
158    if (cwdRepoRoot && isPathInside(targetDir, cwdRepoRoot)) {
159      repoRoot = cwdRepoRoot;
160    }
161  }
162  if (!repoRoot) {
163    return {
164      targetDir,
165      projectRoot: absCwd,
166      repoRoot: absCwd,
167      isMonorepo: false,
168    };
169  }
170  return {
171    targetDir,
172    projectRoot: resolveWorkspaceProjectRoot(repoRoot, targetDir) || repoRoot,
173    repoRoot,
174    isMonorepo: true,
175  };
176}
177 
178function isPathInside(candidate, root) {
179  const rel = path.relative(root, candidate);
180  return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
181}
182 
183function resolveLocalContextDir(root) {
184  if (firstExisting(root, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
185    return root;
186  }
187  for (const rel of FALLBACK_DIRS) {
188    const candidate = path.resolve(root, rel);
189    if (firstExisting(candidate, [...PRODUCT_NAMES, ...DESIGN_NAMES])) {
190      return candidate;
191    }
192  }
193  return null;
194}
195 
196function resolveEnvContextDir(cwd) {
197  const envDir = process.env.IMPECCABLE_CONTEXT_DIR;
198  if (!envDir || !envDir.trim()) return null;
199  const trimmed = envDir.trim();
200  return path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
201}
202 
203function resolveTargetDir(cwd, options = {}) {
204  const targetPath = options && typeof options === 'object' ? options.targetPath : null;
205  if (!targetPath || !String(targetPath).trim()) return cwd;
206  const abs = path.isAbsolute(targetPath) ? targetPath : path.resolve(cwd, targetPath);
207  try {
208    const stat = fs.statSync(abs);
209    return stat.isDirectory() ? abs : path.dirname(abs);
210  } catch {
211    return path.extname(abs) ? path.dirname(abs) : abs;
212  }
213}
214 
215function findMonorepoRoot(startDir) {
216  let dir = path.resolve(startDir);
217  const homeDir = path.resolve(os.homedir());
218  while (true) {
219    if (dir === homeDir) return null;
220    // isMonorepoRoot is checked before hasGitBoundary on purpose: a workspace
221    // root that also carries its own .git is still recognized. The trade-off is
222    // deliberate — a directory with a monorepo *marker* but no workspace patterns
223    // and no apps/packages children is not a monorepo root, so its .git stops
224    // traversal and a further-up root is not searched. The nested .git is treated
225    // as an independent project boundary, which is the intended isolation.
226    if (isMonorepoRoot(dir)) return dir;
227    if (hasGitBoundary(dir)) return null;
228    const parent = path.dirname(dir);
229    if (parent === dir) return null;
230    dir = parent;
231  }
232}
233 
234function isMonorepoRoot(dir) {
235  if (readWorkspacePatterns(dir).some((pattern) => !normalizeWorkspacePattern(pattern).startsWith('!'))) return true;
236  if (!MONOREPO_MARKER_FILES.some((file) => fs.existsSync(path.join(dir, file)))) return false;
237  return hasFallbackWorkspaceChildren(dir);
238}
239 
240function hasGitBoundary(dir) {
241  return fs.existsSync(path.join(dir, '.git'));
242}
243 
244function hasFallbackWorkspaceChildren(dir) {
245  for (const name of MONOREPO_FALLBACK_PROJECT_DIRS) {
246    const base = path.join(dir, name);
247    let entries;
248    try {
249      entries = fs.readdirSync(base, { withFileTypes: true });
250    } catch {
251      continue;
252    }
253    if (entries.some((entry) => entry.isDirectory() && !isIgnoredWorkspaceDiscoveryDir(entry.name))) return true;
254  }
255  return false;
256}
257 
258function discoverTargetCandidates(repoRoot) {
259  const roots = new Map();
260  const patterns = readWorkspacePatterns(repoRoot);
261  for (const pattern of patterns) {
262    for (const root of discoverRootsForPattern(repoRoot, pattern)) {
263      roots.set(path.relative(repoRoot, root).split(path.sep).join('/'), root);
264    }
265  }
266  if (MONOREPO_MARKER_FILES.some((file) => fs.existsSync(path.join(repoRoot, file)))) {
267    for (const name of MONOREPO_FALLBACK_PROJECT_DIRS) {
268      const base = path.join(repoRoot, name);
269      let entries;
270      try {
271        entries = fs.readdirSync(base, { withFileTypes: true });
272      } catch {
273        continue;
274      }
275      for (const entry of entries) {
276        if (!entry.isDirectory() || isIgnoredWorkspaceDiscoveryDir(entry.name)) continue;
277        const root = path.join(base, entry.name);
278        roots.set(path.relative(repoRoot, root).split(path.sep).join('/'), root);
279      }
280    }
281  }
282  return [...roots.entries()]
283    .filter(([rel]) => rel && !rel.startsWith('..'))
284    // Honor negated workspace patterns (e.g. "!packages/internal"). resolveWorkspaceProjectRoot
285    // sends an excluded package back to the repo root, so an excluded folder must not appear as a
286    // selectable target — choosing it would silently resolve to the root instead.
287    .filter(([rel]) => !isExcludedByWorkspacePattern(rel.split('/').filter(Boolean), patterns))
288    .sort(([a], [b]) => a.localeCompare(b))
289    .map(([rel, root]) => {
290      const targetExample = findTargetExample(repoRoot, root);
291      return {
292        name: path.basename(root),
293        path: rel,
294        targetExample,
295        ...resolveCandidateContextSummary(repoRoot, root, targetExample),
296      };
297    });
298}
299 
300function resolveCandidateContextSummary(repoRoot, projectRoot, targetPath) {
301  const ctx = resolveContext(repoRoot, { targetPath });
302  return {
303    productStatus: contextSourceStatus(ctx.productPath, repoRoot, projectRoot),
304    productPath: contextSourcePath(ctx.productPath, repoRoot),
305    designStatus: contextSourceStatus(ctx.designPath, repoRoot, projectRoot),
306    designPath: contextSourcePath(ctx.designPath, repoRoot),
307  };
308}
309 
310// Selection candidates surface one of four statuses: 'child' (a canonical
311// PRODUCT.md/DESIGN.md directly in the app root), 'inherited' (resolved from the
312// repo root in a monorepo), 'missing' (no file found), and 'fallback'. 'fallback'
313// intentionally covers two non-canonical locations: a file inside the project
314// root but in a subdirectory (FALLBACK_DIRS, e.g. `.agents/context/`), and a file
315// outside both the project and repo roots (IMPECCABLE_CONTEXT_DIR override).
316function contextSourceStatus(filePath, repoRoot, projectRoot) {
317  if (!filePath) return 'missing';
318  const absPath = path.resolve(filePath);
319  const absProjectRoot = path.resolve(projectRoot);
320  const absRepoRoot = path.resolve(repoRoot);
321  if (isPathInsideOrEqual(absPath, absProjectRoot)) {
322    return path.dirname(absPath) === absProjectRoot ? 'child' : 'fallback';
323  }
324  if (absProjectRoot !== absRepoRoot && isPathInsideOrEqual(absPath, absRepoRoot)) {
325    return 'inherited';
326  }
327  return 'fallback';
328}
329 
330function contextSourcePath(filePath, repoRoot) {
331  if (!filePath) return null;
332  const rel = path.relative(repoRoot, filePath);
333  if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
334    return rel.split(path.sep).join('/');
335  }
336  return filePath;
337}
338 
339function discoverRootsForPattern(repoRoot, rawPattern) {
340  const pattern = normalizeWorkspacePattern(rawPattern);
341  if (!pattern || pattern.startsWith('!')) return [];
342  const segments = pattern.split('/').filter(Boolean);
343  if (!segments.length) return [];
344  const firstGlobIndex = segments.findIndex((segment) => segment.includes('*'));
345  const literalPrefix = firstGlobIndex === -1 ? segments : segments.slice(0, firstGlobIndex);
346  const base = path.join(repoRoot, ...literalPrefix);
347  if (!fs.existsSync(base)) return [];
348  if (segments.includes('**')) {
349    const packageRoots = [];
350    walkDirs(base, (dir) => {
351      if (dir !== base && isCandidateProjectRoot(dir)) packageRoots.push(dir);
352    });
353    if (packageRoots.length) return packageRoots;
354    return directChildDirs(base);
355  }
356  return expandSimplePattern(repoRoot, segments);
357}
358 
359function expandSimplePattern(repoRoot, patternSegments, index = 0, current = repoRoot) {
360  if (index >= patternSegments.length) return fs.existsSync(current) ? [current] : [];
361  const segment = patternSegments[index];
362  if (!segment.includes('*')) {
363    return expandSimplePattern(repoRoot, patternSegments, index + 1, path.join(current, segment));
364  }
365  let entries;
366  try {
367    entries = fs.readdirSync(current, { withFileTypes: true });
368  } catch {
369    return [];
370  }
371  const roots = [];
372  for (const entry of entries) {
373    if (!entry.isDirectory() || isIgnoredWorkspaceDiscoveryDir(entry.name)) continue;
374    if (!segmentMatches(segment, entry.name)) continue;
375    roots.push(...expandSimplePattern(repoRoot, patternSegments, index + 1, path.join(current, entry.name)));
376  }
377  return roots;
378}
379 
380function directChildDirs(dir) {
381  try {
382    return fs.readdirSync(dir, { withFileTypes: true })
383      .filter((entry) => entry.isDirectory() && !isIgnoredWorkspaceDiscoveryDir(entry.name))
384      .map((entry) => path.join(dir, entry.name));
385  } catch {
386    return [];
387  }
388}
389 
390function walkDirs(root, visit) {
391  let entries;
392  try {
393    entries = fs.readdirSync(root, { withFileTypes: true });
394  } catch {
395    return;
396  }
397  for (const entry of entries) {
398    if (!entry.isDirectory() || isIgnoredWorkspaceDiscoveryDir(entry.name)) continue;
399    const dir = path.join(root, entry.name);
400    visit(dir);
401    walkDirs(dir, visit);
402  }
403}
404 
405function isCandidateProjectRoot(dir) {
406  return !!(
407    fs.existsSync(path.join(dir, 'package.json'))
408    || firstExisting(dir, [...PRODUCT_NAMES, ...DESIGN_NAMES])
409    || fs.existsSync(path.join(dir, 'src'))
410    || fs.existsSync(path.join(dir, 'app'))
411    || fs.existsSync(path.join(dir, 'pages'))
412    || fs.existsSync(path.join(dir, 'public'))
413  );
414}
415 
416function isIgnoredWorkspaceDiscoveryDir(name) {
417  return name.startsWith('.') || WORKSPACE_DISCOVERY_IGNORED_DIRS.has(name);
418}
419 
420function findTargetExample(repoRoot, projectRoot) {
421  const examples = [
422    'src/App.jsx',
423    'src/App.tsx',
424    'src/main.jsx',
425    'src/main.tsx',
426    'src/index.jsx',
427    'src/index.ts',
428    'app/page.tsx',
429    'pages/index.tsx',
430    'public/index.html',
431  ];
432  for (const rel of examples) {
433    const abs = path.join(projectRoot, rel);
434    if (fs.existsSync(abs)) return path.relative(repoRoot, abs).split(path.sep).join('/');
435  }
436  return path.relative(repoRoot, projectRoot).split(path.sep).join('/');
437}
438 
439function resolveWorkspaceProjectRoot(repoRoot, targetDir) {
440  const rel = path.relative(repoRoot, targetDir);
441  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return repoRoot;
442  const relSegments = rel.split(path.sep).filter(Boolean);
443  const patterns = readWorkspacePatterns(repoRoot);
444  const excluded = isExcludedByWorkspacePattern(relSegments, patterns);
445  if (!excluded) {
446    for (const pattern of patterns) {
447      const projectRoot = projectRootFromWorkspacePattern(repoRoot, relSegments, pattern);
448      if (projectRoot) return projectRoot;
449    }
450  }
451  if (excluded) return repoRoot;
452  if (
453    relSegments.length >= 2
454    && MONOREPO_FALLBACK_PROJECT_DIRS.includes(relSegments[0])
455  ) {
456    return path.join(repoRoot, relSegments[0], relSegments[1]);
457  }
458  const nearest = nearestProjectLikeRoot(repoRoot, targetDir);
459  if (nearest) return nearest;
460  return repoRoot;
461}
462 
463function isExcludedByWorkspacePattern(relSegments, patterns) {
464  return patterns.some((rawPattern) => {
465    const pattern = normalizeWorkspacePattern(rawPattern);
466    if (!pattern.startsWith('!')) return false;
467    return workspacePatternMatchesRel(pattern.slice(1), relSegments);
468  });
469}
470 
471function nearestProjectLikeRoot(repoRoot, targetDir) {
472  let dir = path.resolve(targetDir);
473  const stop = path.resolve(repoRoot);
474  while (dir && dir !== stop) {
475    if (
476      firstExisting(dir, [...PRODUCT_NAMES, ...DESIGN_NAMES])
477      || fs.existsSync(path.join(dir, 'package.json'))
478    ) {
479      return dir;
480    }
481    const parent = path.dirname(dir);
482    if (parent === dir) break;
483    dir = parent;
484  }
485  return null;
486}
487 
488function nearestPackageRootBetween(repoRoot, targetDir, stopDir) {
489  let dir = path.resolve(targetDir);
490  const stop = path.resolve(stopDir || repoRoot);
491  const root = path.resolve(repoRoot);
492  while (dir && dir !== stop && isPathInsideOrEqual(dir, root)) {
493    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
494    const parent = path.dirname(dir);
495    if (parent === dir) break;
496    dir = parent;
497  }
498  return null;
499}
500 
501function isPathInsideOrEqual(candidate, root) {
502  return path.resolve(candidate) === path.resolve(root) || isPathInside(candidate, root);
503}
504 
505function workspacePatternMatchesRel(pattern, relSegments) {
506  const patternSegments = normalizeWorkspacePattern(pattern).split('/').filter(Boolean);
507  if (!patternSegments.length) return false;
508  if (patternSegments.includes('**')) {
509    const firstGlobIndex = patternSegments.findIndex((segment) => segment.includes('*'));
510    const literalPrefix = firstGlobIndex === -1
511      ? patternSegments
512      : patternSegments.slice(0, firstGlobIndex);
513    if (relSegments.length < literalPrefix.length + 1) return false;
514    for (let i = 0; i < literalPrefix.length; i++) {
515      if (!segmentMatches(literalPrefix[i], relSegments[i])) return false;
516    }
517    return true;
518  }
519  if (relSegments.length < patternSegments.length) return false;
520  for (let i = 0; i < patternSegments.length; i++) {
521    if (!segmentMatches(patternSegments[i], relSegments[i])) return false;
522  }
523  return true;
524}
525 
526function readWorkspacePatterns(repoRoot) {
527  return [
528    ...readPackageWorkspaces(repoRoot),
529    ...readPnpmWorkspaces(repoRoot),
530    ...readLernaWorkspaces(repoRoot),
531  ].filter(Boolean);
532}
533 
534function readPackageWorkspaces(repoRoot) {
535  const pkg = readJson(path.join(repoRoot, 'package.json'));
536  const workspaces = pkg?.workspaces;
537  if (Array.isArray(workspaces)) return workspaces;
538  if (Array.isArray(workspaces?.packages)) return workspaces.packages;
539  return [];
540}
541 
542function readLernaWorkspaces(repoRoot) {
543  const lerna = readJson(path.join(repoRoot, 'lerna.json'));
544  return Array.isArray(lerna?.packages) ? lerna.packages : [];
545}
546 
547function readPnpmWorkspaces(repoRoot) {
548  try {
549    const body = fs.readFileSync(path.join(repoRoot, 'pnpm-workspace.yaml'), 'utf-8');
550    const patterns = [];
551    let inPackages = false;
552    for (const line of body.split(/\r?\n/)) {
553      const trimmed = stripYamlInlineComment(line).trim();
554      if (!trimmed || trimmed.startsWith('#')) continue;
555      const flowMatch = trimmed.match(/^packages:\s*\[(.*)\]\s*$/);
556      if (flowMatch) {
557        patterns.push(...parseYamlFlowList(flowMatch[1]));
558        inPackages = false;
559        continue;
560      }
561      if (/^packages:\s*$/.test(trimmed)) {
562        inPackages = true;
563        continue;
564      }
565      if (inPackages && /^[A-Za-z0-9_-]+:\s*/.test(trimmed)) break;
566      if (inPackages) {
567        const match = trimmed.match(/^-\s*(.+)$/);
568        if (match) patterns.push(unquoteYamlValue(match[1]));
569      }
570    }
571    return patterns;
572  } catch {
573    return [];
574  }
575}
576 
577function stripYamlInlineComment(line) {
578  let quote = null;
579  for (let i = 0; i < line.length; i++) {
580    const ch = line[i];
581    if ((ch === '"' || ch === "'") && line[i - 1] !== '\\') {
582      quote = quote === ch ? null : quote || ch;
583      continue;
584    }
585    if (ch === '#' && !quote) return line.slice(0, i);
586  }
587  return line;
588}
589 
590function parseYamlFlowList(body) {
591  const items = [];
592  let quote = null;
593  let current = '';
594  for (let i = 0; i < body.length; i++) {
595    const ch = body[i];
596    if ((ch === '"' || ch === "'") && body[i - 1] !== '\\') {
597      quote = quote === ch ? null : quote || ch;
598      current += ch;
599      continue;
600    }
601    if (ch === ',' && !quote) {
602      const value = unquoteYamlValue(current);
603      if (value) items.push(value);
604      current = '';
605      continue;
606    }
607    current += ch;
608  }
609  const value = unquoteYamlValue(current);
610  if (value) items.push(value);
611  return items;
612}
613 
614function unquoteYamlValue(value) {
615  return String(value || '')
616    .trim()
617    .replace(/^['"]|['"]$/g, '');
618}
619 
620function readJson(filePath) {
621  try {
622    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
623  } catch {
624    return null;
625  }
626}
627 
628function projectRootFromWorkspacePattern(repoRoot, relSegments, rawPattern) {
629  const pattern = normalizeWorkspacePattern(rawPattern);
630  if (!pattern || pattern.startsWith('!')) return null;
631  const patternSegments = pattern.split('/').filter(Boolean);
632  if (!patternSegments.length) return null;
633  if (patternSegments.includes('**')) {
634    return projectRootFromDoubleStarPattern(repoRoot, relSegments, patternSegments);
635  }
636  if (relSegments.length < patternSegments.length) return null;
637  for (let i = 0; i < patternSegments.length; i++) {
638    if (!segmentMatches(patternSegments[i], relSegments[i])) return null;
639  }
640  return path.join(repoRoot, ...relSegments.slice(0, patternSegments.length));
641}
642 
643function projectRootFromDoubleStarPattern(repoRoot, relSegments, patternSegments) {
644  const firstGlobIndex = patternSegments.findIndex((segment) => segment.includes('*'));
645  const literalPrefix = firstGlobIndex === -1
646    ? patternSegments
647    : patternSegments.slice(0, firstGlobIndex);
648  if (relSegments.length < literalPrefix.length + 1) return null;
649  for (let i = 0; i < literalPrefix.length; i++) {
650    if (!segmentMatches(literalPrefix[i], relSegments[i])) return null;
651  }
652  const prefixDir = path.join(repoRoot, ...literalPrefix);
653  const targetDir = path.join(repoRoot, ...relSegments);
654  const packageRoot = nearestPackageRootBetween(repoRoot, targetDir, prefixDir);
655  if (packageRoot) return packageRoot;
656  return path.join(repoRoot, ...relSegments.slice(0, literalPrefix.length + 1));
657}
658 
659function normalizeWorkspacePattern(pattern) {
660  return String(pattern || '')
661    .trim()
662    .replace(/^['"]|['"]$/g, '')
663    .replace(/^\.\//, '')
664    .replace(/\/+$/, '');
665}
666 
667function segmentMatches(patternSegment, relSegment) {
668  if (patternSegment === '*') return true;
669  if (!patternSegment.includes('*')) return patternSegment === relSegment;
670  const re = new RegExp(`^${escapeRegExp(patternSegment).replace(/\\\*/g, '[^/]*')}$`);
671  return re.test(relSegment);
672}
673 
674function firstExisting(dir, names) {
675  for (const name of names) {
676    const abs = path.join(dir, name);
677    if (fs.existsSync(abs)) return abs;
678  }
679  return null;
680}
681 
682function safeRead(p) {
683  try {
684    return fs.readFileSync(p, 'utf-8');
685  } catch {
686    return null;
687  }
688}
689 
690function escapeRegExp(value) {
691  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
692}
693 
694/**
695 * Pull the register (`brand` or `product`) out of PRODUCT.md by looking
696 * for a `## Register` section and reading the first non-empty line that
697 * follows it. Returns null when the file is legacy / register-less.
698 */
699export function extractRegister(product) {
700  if (!product) return null;
701  const lines = product.split('\n');
702  for (let i = 0; i < lines.length; i++) {
703    if (/^##\s+Register\b/i.test(lines[i].trim())) {
704      for (let j = i + 1; j < lines.length; j++) {
705        const next = lines[j].trim();
706        if (!next) continue;
707        const word = next.toLowerCase();
708        if (word === 'brand' || word === 'product') return word;
709        return null;
710      }
711    }
712  }
713  return null;
714}
715 
716/**
717 * Read the installed skill's own version from the sibling SKILL.md frontmatter
718 * (this file lives at `<skill>/scripts/context.mjs`). Returns null when the
719 * frontmatter is missing or unreadable.
720 */
721function readLocalSkillVersion() {
722  try {
723    const here = path.dirname(fileURLToPath(import.meta.url));
724    const skillMd = path.join(here, '..', 'SKILL.md');
725    const content = fs.readFileSync(skillMd, 'utf-8');
726    const match = content.match(/^version:\s*(.+)$/m);
727    return match ? match[1].trim().replace(/^["']|["']$/g, '') : null;
728  } catch {
729    return null;
730  }
731}
732 
733function readUpdateCache() {
734  try {
735    return JSON.parse(fs.readFileSync(UPDATE_CACHE_PATH, 'utf-8'));
736  } catch {
737    return {};
738  }
739}
740 
741function writeUpdateCache(cache) {
742  try {
743    fs.mkdirSync(path.dirname(UPDATE_CACHE_PATH), { recursive: true });
744    fs.writeFileSync(UPDATE_CACHE_PATH, JSON.stringify(cache));
745  } catch {
746    // Best-effort: a read-only home dir just means we re-poll next session.
747  }
748}
749 
750/** Compare dotted numeric versions. Returns >0 when a is newer than b. */
751function compareSemver(a, b) {
752  const pa = String(a).split('.').map(n => parseInt(n, 10) || 0);
753  const pb = String(b).split('.').map(n => parseInt(n, 10) || 0);
754  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
755    const diff = (pa[i] || 0) - (pb[i] || 0);
756    if (diff !== 0) return diff;
757  }
758  return 0;
759}
760 
761async function fetchLatestSkillVersion() {
762  try {
763    const res = await fetch(`${UPDATE_HOST}/api/version`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
764    if (!res.ok) return null;
765    const data = await res.json();
766    return typeof data?.skills === 'string' ? data.skills : null;
767  } catch {
768    return null; // offline, sandboxed, timed out, or bad JSON: all non-fatal
769  }
770}
771 
772function buildUpdateDirective(localVersion, latestVersion) {
773  return (
774    `UPDATE_AVAILABLE: A newer Impeccable skill is available ` +
775    `(installed v${localVersion}, latest v${latestVersion}). ` +
776    `Before continuing, ask the user once: "A newer Impeccable (v${latestVersion}) is available. ` +
777    `Update now? It runs \`npx impeccable update\`." ` +
778    `If they agree, run \`npx impeccable update\` (the update applies to the next session, not this one). ` +
779    `Either way, continue the current task without waiting, and do not raise this again.`
780  );
781}
782 
783/**
784 * Best-effort update directive for the boot output. Returns a string to append
785 * or null. Polls the version endpoint at most once per day (cached globally in
786 * the user's home dir) and re-surfaces a given version at most once per week so
787 * the agent never nags. Opt out entirely with IMPECCABLE_NO_UPDATE_CHECK=1.
788 */
789// Read the unified config's top-level `updateCheck` (local overrides shared).
790// Inlined rather than importing hook-lib so the boot path stays lightweight.
791function updateCheckDisabledByConfig(cwd = process.cwd()) {
792  let value;
793  for (const name of ['config.json', 'config.local.json']) {
794    try {
795      const raw = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', name), 'utf-8'));
796      if (raw && typeof raw === 'object' && typeof raw.updateCheck === 'boolean') value = raw.updateCheck;
797    } catch { /* missing or malformed: ignore */ }
798  }
799  return value === false;
800}
801 
802async function computeUpdateDirective(now = Date.now()) {
803  try {
804    if (process.env.IMPECCABLE_NO_UPDATE_CHECK) return null;
805    if (updateCheckDisabledByConfig()) return null;
806    const localVersion = readLocalSkillVersion();
807    if (!localVersion) return null;
808 
809    const cache = readUpdateCache();
810 
811    // Poll the network only when the throttle window has elapsed. Stamp
812    // lastCheck even on failure so an offline machine doesn't poll every boot.
813    if (!cache.lastCheck || now - cache.lastCheck > CHECK_INTERVAL_MS) {
814      const latest = await fetchLatestSkillVersion();
815      cache.lastCheck = now;
816      if (latest) cache.latestVersion = latest;
817      writeUpdateCache(cache);
818    }
819 
820    const latest = cache.latestVersion;
821    if (!latest || compareSemver(latest, localVersion) <= 0) return null;
822 
823    // Anti-nag: surface a given version at most once per RENOTIFY window.
824    if (cache.notifiedVersion === latest && cache.notifiedAt && now - cache.notifiedAt < RENOTIFY_INTERVAL_MS) {
825      return null;
826    }
827    cache.notifiedVersion = latest;
828    cache.notifiedAt = now;
829    writeUpdateCache(cache);
830 
831    return buildUpdateDirective(localVersion, latest);
832  } catch {
833    return null;
834  }
835}
836 
837async function cli() {
838  let cliOptions;
839  try {
840    cliOptions = parseCliOptions(process.argv.slice(2));
841  } catch (err) {
842    if (err?.name === 'TargetArgError') {
843      process.stderr.write(`${err.message}\n`);
844      process.exit(1);
845    }
846    throw err;
847  }
848  const targetProvided = hasTargetOption(cliOptions);
849  const targetExists = targetProvided ? pathExistsForTarget(process.cwd(), cliOptions.targetPath) : null;
850  const selection = resolveTargetSelection(process.cwd(), cliOptions);
851  if (selection) {
852    process.stdout.write(buildTargetSelectionDirective(selection) + '\n');
853    process.exit(0);
854  }
855  const ctx = loadContext(process.cwd(), cliOptions);
856  const updateDirective = await computeUpdateDirective();
857 
858  if (!ctx.hasProduct) {
859    // Direct stdout message instead of relying on empty output as a signal
860    // — cheap models miss the empty case more often than the explicit one.
861    const parts = [
862      'NO_PRODUCT_MD: This project has no PRODUCT.md yet. ' +
863      'Stop the current task, load reference/init.md, and follow its ' +
864      'instructions to write PRODUCT.md before resuming.',
865    ];
866    parts.push(buildResolvedContextDirective(ctx, cliOptions, { targetExists }));
867    if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
868      parts.push(buildMissingTargetDirective());
869    }
870    if (updateDirective) parts.push(updateDirective);
871    process.stdout.write(parts.join('\n\n---\n\n') + '\n');
872    process.exit(0);
873  }
874  const parts = [`# PRODUCT.md\n\n${ctx.product.trim()}`];
875  if (ctx.hasDesign) {
876    parts.push(`# DESIGN.md\n\n${ctx.design.trim()}`);
877  }
878  parts.push(buildResolvedContextDirective(ctx, cliOptions, { targetExists }));
879  if (shouldWarnMissingTarget(ctx, targetProvided, targetExists)) {
880    parts.push(buildMissingTargetDirective());
881  }
882  const register = extractRegister(ctx.product);
883  const next = register
884    ? `NEXT STEP: This project's register is \`${register}\`. You MUST now read \`reference/${register}.md\` before producing any design output.`
885    : `NEXT STEP: You MUST now read the matching register reference (\`reference/brand.md\` or \`reference/product.md\`) before producing any design output. Pick based on PRODUCT.md above.`;
886  parts.push(next);
887  if (updateDirective) parts.push(updateDirective);
888  process.stdout.write(parts.join('\n\n---\n\n') + '\n');
889}
890 
891function parseCliOptions(args) {
892  return parseTargetOptions(args, { strict: true });
893}
894 
895function hasTargetOption(options) {
896  return !!(options && typeof options.targetPath === 'string' && options.targetPath.trim());
897}
898 
899function pathExistsForTarget(cwd, targetPath) {
900  const abs = path.isAbsolute(targetPath) ? targetPath : path.resolve(cwd, targetPath);
901  return fs.existsSync(abs);
902}
903 
904function buildResolvedContextDirective(ctx, options, { targetExists = null } = {}) {
905  const targetPath = hasTargetOption(options) ? options.targetPath : null;
906  return `RESOLVED_CONTEXT:\n${JSON.stringify({
907    targetPath,
908    ...(targetPath ? { targetExists } : {}),
909    projectRoot: ctx.projectRoot,
910    repoRoot: ctx.repoRoot,
911    productPath: ctx.productPath,
912    designPath: ctx.designPath,
913  }, null, 2)}`;
914}
915 
916function shouldWarnMissingTarget(ctx, targetProvided, targetExists = null) {
917  if (ctx.isMonorepo && targetProvided && targetExists === false) return true;
918  return !!(
919    ctx.isMonorepo
920    && (!targetProvided || targetExists === false)
921    && ctx.projectRoot
922    && ctx.repoRoot
923    && path.resolve(ctx.projectRoot) === path.resolve(ctx.repoRoot)
924  );
925}
926 
927function buildMissingTargetDirective() {
928  const script = process.argv[1] || 'context.mjs';
929  return (
930    'MONOREPO_TARGET_REQUIRED: This is a monorepo and context.mjs ran without --target. ' +
931    'If the user named a file, route, or child app, do not answer from this output. ' +
932    `Rerun \`node ${script} --target <path>\` and answer from that run's RESOLVED_CONTEXT fields.`
933  );
934}
935 
936function buildTargetSelectionDirective(selection) {
937  return (
938    `TARGET_SELECTION_REQUIRED:\n${JSON.stringify(selection, null, 2)}\n\n` +
939    'Show each app with its productStatus/productPath and designStatus/designPath so the user can see child overrides, inherited root files, fallback files, or missing files before choosing. ' +
940    'Ask the user which app Impeccable should use, then rerun Impeccable helper commands from that child app cwd using this same scripts directory. ' +
941    'Use `--target <path>` only as a fallback when changing cwd is not possible, or when the user explicitly named a file/path.'
942  );
943}
944 
945// Run cli() only when this module is the entry point. Compare realpaths
946// rather than endsWith(): a loose suffix match also fires for unrelated
947// scripts like `load-context.mjs`, and realpath tolerates symlinked
948// invocation (the test harness symlinks the skill dir).
949function invokedAsScript() {
950  const arg = process.argv[1];
951  if (!arg) return false;
952  try {
953    return fs.realpathSync(arg) === fs.realpathSync(fileURLToPath(import.meta.url));
954  } catch {
955    return false;
956  }
957}
958 
959if (invokedAsScript()) {
960  cli();
961}
962