great-cto 3.59.0 → 3.60.0

package/board/scripts/lib/session-usage.mjs

@@ -86,6 +86,68 @@ export function projectName(cwd, homeDir = home()) {
   return path.basename(cwd) || null;
 }
 
+const canonical = (p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+
+/** Stable repository identity, including linked worktrees. Never infer it from a title/basename. */
+function repositoryIdentity(cwd) {
+  for (let dir = canonical(cwd); ; dir = path.dirname(dir)) {
+    const marker = path.join(dir, '.git');
+    try {
+      const stat = fs.statSync(marker);
+      let gitDir;
+      if (stat.isDirectory()) gitDir = marker;
+      else {
+        const match = fs.readFileSync(marker, 'utf8').match(/^gitdir:\s*(.+)\s*$/m);
+        if (!match) return null;
+        gitDir = path.resolve(dir, match[1].trim());
+      }
+      let common = gitDir;
+      try { common = path.resolve(gitDir, fs.readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim()); } catch { /* main checkout */ }
+      return { common: canonical(common), root: dir };
+    } catch { /* continue to parent */ }
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+/** Filter before aggregation: children without cwd inherit only their own host's parent. */
+export function projectUsageIndex(index, projectPath) {
+  if (!projectPath) return index;
+  const root = canonical(projectPath);
+  const git = repositoryIdentity(root);
+  const projectRelative = git ? path.relative(git.root, root) : null;
+  const identities = new Map();
+  const entries = Object.entries(index.files || {});
+  const sessions = new Map();
+  for (const [, e] of entries) if (e.meta?.session) sessions.set(`${e.host}|${e.meta.session}`, e);
+  const inheritedCwd = e => {
+    const visited = new Set();
+    while (e) {
+      if (e.meta?.cwd) return e.meta.cwd;
+      const key = `${e.host}|${e.meta?.parent}`;
+      if (!e.meta?.parent || visited.has(key)) return null;
+      visited.add(key); e = sessions.get(key);
+    }
+    return null;
+  };
+  const matches = (cwd) => {
+    if (!cwd || typeof cwd !== 'string' || !path.isAbsolute(cwd)) return false;
+    if (identities.has(cwd)) return identities.get(cwd);
+    const actual = canonical(cwd);
+    const repo = repositoryIdentity(actual);
+    // Transfer the selected project's relative directory to this worktree.
+    // A shared Git database alone does not make sibling monorepo apps one project.
+    const scopeRoot = git && repo && git.common === repo.common
+      ? path.resolve(repo.root, projectRelative)
+      : root;
+    const rel = path.relative(scopeRoot, actual);
+    const inside = rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
+    const match = git && repo ? git.common === repo.common && inside : inside;
+    identities.set(cwd, match);
+    return match;
+  };
+  return { ...index, files: Object.fromEntries(entries.filter(([, e]) => matches(inheritedCwd(e)))) };
+}
+
 // ── file discovery ────────────────────────────────────────────────────────────
 
 function walk(dir, maxDepth, out) {
@@ -823,7 +885,8 @@ function laneDetail(samples, { fromMs, now }) {
  * @param {object} index  from scanUsage
  * @param {{days?:number, now?:number, codexTitles?:Record<string,string>, prices?:object, top?:number}} opts
  */
-export function summarizeUsage(index, { days = 30, now = Date.now(), codexTitles = {}, prices = effectivePrices(), top = 10, claudeReadings = [], claudeRecorderState = 'off' } = {}) {
+export function summarizeUsage(index, { days = 30, now = Date.now(), codexTitles = {}, prices = effectivePrices(), top = 10, claudeReadings = [], claudeRecorderState = 'off', projectPath = null } = {}) {
+  index = projectUsageIndex(index, projectPath);
   const span = Math.max(1, Math.min(365, Math.floor(days) || 30));
   const dates = [];
   for (let i = span - 1; i >= 0; i--) dates.push(dayOf(now - i * 86400000));
@@ -918,7 +981,7 @@ export function summarizeUsage(index, { days = 30, now = Date.now(), codexTitles
     // The conversation's own file names it; a subagent's file only fills a gap.
     const own = !e.meta?.parent;
     if (own || !s.title) s.title = (host === 'codex' ? codexTitles[e.meta?.session] : null) || e.meta?.title || e.meta?.prompt || s.title;
-    if (own || !s.project) s.project = projectName(e.meta?.cwd) || s.project;
+    if (own || !s.project) s.project = projectName(projectPath || e.meta?.cwd) || s.project;
     if (own || !s.fn) s.fn = fn;
   }
 
@@ -940,6 +1003,11 @@ export function summarizeUsage(index, { days = 30, now = Date.now(), codexTitles
 
   return {
     state: 'counted',
+    ...(projectPath ? {
+      scope: { kind: 'project', path: canonical(projectPath) },
+      files: Object.keys(index.files || {}).length,
+      seen: Object.fromEntries(['claude', 'codex'].map(host => [host, Object.values(index.files || {}).some(e => e.host === host)])),
+    } : {}),
     window: { from, to: dates[dates.length - 1], days: span },
     hosts: Object.fromEntries(Object.entries(hosts).map(([k, h]) => [k, {
       tokens: tokensOf(h), input: h.in, output: h.out, cacheRead: h.cr, cacheWrite: h.cw + h.cwh, reasoning: h.rs,
@@ -957,8 +1025,8 @@ export function summarizeUsage(index, { days = 30, now = Date.now(), codexTitles
       tools: rank(l.tools, 15), skills: rank(l.skills, 15), agents: rank(l.agents, 15), mcp: rank(l.mcp, 15, mcpLabel),
     }])),
     limits: {
-      codex: codexLimits ? { ...codexLimits, plan: codexLimits.plan || codexPlan?.plan || null, detail: codexLimitDetail(codexPoints, { fromMs, now }) } : null,
-      claude: { ...claudeLimits(hourly.claude, { fromMs, now, lastHit }), plan: claudePlanDetail(claudeReadings, { fromMs, now }), recorder: claudeRecorderState },
+      codex: !projectPath && codexLimits ? { ...codexLimits, plan: codexLimits.plan || codexPlan?.plan || null, detail: codexLimitDetail(codexPoints, { fromMs, now }) } : null,
+      claude: { ...claudeLimits(hourly.claude, { fromMs, now, lastHit }), plan: projectPath ? null : claudePlanDetail(claudeReadings, { fromMs, now }), recorder: claudeRecorderState },
     },
     unpricedModels: [...unpriced].sort(),
     // Claude Code only: Codex does not write hook outcomes to its session logs.

package/board/scripts/skill-lint.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * scripts/skill-lint.mjs — structural validator for skills/*\/SKILL.md, the skill
+ * counterpart of agent-prompt-lint.mjs. Agents had a lint, a review and a retire
+ * loop; skills shipped with none, so a skill whose frontmatter did not load, whose
+ * name drifted from its directory, or which pointed at a deleted script was found
+ * only by a model failing to use it.
+ *
+ * Rules:
+ *   SK-001 error  YAML frontmatter present and parses
+ *   SK-002 error  `name` equals the skill's directory
+ *   SK-003 error  `description` present, 40–1024 chars (the model routes on it)
+ *   SK-004 warn   SKILL.md over 20 KB (loaded whole into context) — HEAVY_ALLOWED exempts
+ *   SK-005 error  a relative link or backticked repo path points at a file that does not exist
+ *   SK-006 error  a private absolute path (/Users/<name>/…, /home/<name>/…)
+ *   SK-007 error  an unquoted frontmatter value strict YAML reads differently (`: `, ` #`, a reserved first character)
+ *
+ * Usage:
+ *   node scripts/skill-lint.mjs [--root <repo>] [--json]
+ * Exit: 0 clean or warnings only · 1 errors · 2 invalid invocation
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const SIZE_BUDGET = 20 * 1024;
+export const DESC_MIN = 40;
+export const DESC_MAX = 1024;
+
+/** Skills allowed over the size budget, each with the reason it is allowed. */
+export const HEAVY_ALLOWED = {
+  'ui-ux-pro-max': 'vendored design reference (MIT, upstream layout); its tables are the payload and are loaded only for UI work',
+};
+
+// Backticked paths into great_cto's own tree. docs/ and tests/ are left out on
+// purpose: skills name those as paths in the *target* project far more often.
+const REPO_PATH = /^(scripts|skills|agents|commands|shared|hooks|packages)\/[A-Za-z0-9._/-]+\.[A-Za-z0-9]+$/;
+const MD_LINK = /\[[^\]\n]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const TICKED = /`([^`\n]+)`/g;
+const PRIVATE_PATH = /(?<![\w.~$}])\/(?:Users|home)\/[A-Za-z0-9][A-Za-z0-9._-]*\//g;
+
+/**
+ * Minimal YAML frontmatter reader: top-level `key: value`, block scalars
+ * (`|` / `>`), and indented continuation (lists, nested maps) kept as text.
+ * Throws on a top-level line that is not a key.
+ */
+/**
+ * Unquoted top-level values that a strict YAML parser reads differently from how
+ * this file's lenient parser reads them — so the frontmatter "works" here and the
+ * skill (or agent, or command) silently fails to load elsewhere. ECC shipped a
+ * preflight for exactly this after a release did (techwolf-ai/ai-first-toolkit
+ * preflight.py, v1.12.2). Quote the value to fix it.
+ */
+export function strictYamlIssues(text) {
+  const t = String(text).replace(/\r\n/g, '\n');
+  if (!t.startsWith('---\n')) return [];
+  const end = t.indexOf('\n---', 3);
+  if (end === -1) return [];
+  const out = [];
+  for (const line of t.slice(4, end).split('\n')) {
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s+(.+)$/);
+    if (!m) continue;
+    const v = m[2].trim();
+    if (/^["'|>\[{]/.test(v)) continue;            // quoted, block scalar or flow collection
+    if (/:\s/.test(v) || /:$/.test(v)) out.push(`\`${m[1]}\`: an unquoted value containing ": " is read as a nested mapping`);
+    else if (/\s#/.test(v)) out.push(`\`${m[1]}\`: an unquoted " #" starts a comment — the value is cut there`);
+    else if (/^[@`%&*!]/.test(v)) out.push(`\`${m[1]}\`: an unquoted value may not start with ${v[0]}`);
+  }
+  return out;
+}
+
+export function parseFrontmatter(text) {
+  const t = String(text).replace(/\r\n/g, '\n');
+  if (!t.startsWith('---\n')) return null;
+  const end = t.indexOf('\n---', 3);
+  if (end === -1) return null;
+  const yaml = t.slice(4, end);
+  const body = t.slice(end + 4).replace(/^\n/, '');
+  const data = {};
+  let key = null;
+  let block = false;
+  for (const line of yaml.split('\n')) {
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    if (/^\s/.test(line)) {
+      if (key === null) throw new Error(`indented line before any key: ${line.slice(0, 60)}`);
+      const v = line.trim();
+      if (block || typeof data[key] === 'string') data[key] = data[key] ? `${data[key]} ${v}` : v;
+      continue;
+    }
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:(?:\s+(.*)|\s*)$/);
+    if (!m) throw new Error(`unparseable line: ${line.slice(0, 60)}`);
+    key = m[1];
+    const v = (m[2] ?? '').trim();
+    block = /^[|>][+-]?$/.test(v);
+    data[key] = block ? '' : v === '' ? null : v.replace(/^(["'])([\s\S]*)\1$/, '$2');
+  }
+  return { data, body };
+}
+
+const placeholder = (s) => /[{}<>*…$]|\.\.\./.test(s);
+
+function danglingRefs(text, skillDir, repoRoot) {
+  const out = [];
+  const exists = (rel) => [skillDir, repoRoot].some((base) => fs.existsSync(path.resolve(base, rel)));
+  for (const m of text.matchAll(MD_LINK)) {
+    const target = m[1].replace(/#.*$/, '');
+    if (!target || /^[a-z][a-z0-9+.-]*:/i.test(m[1]) || m[1].startsWith('#') || target.startsWith('/') || placeholder(target)) continue;
+    if (!exists(target)) out.push(`link to missing file \`${target}\``);
+  }
+  for (const m of text.matchAll(TICKED)) {
+    const p = m[1].trim().replace(/:\d+(-\d+)?$/, '');
+    if (!REPO_PATH.test(p) || placeholder(p)) continue;
+    if (!exists(p)) out.push(`reference to missing file \`${p}\``);
+  }
+  return out;
+}
+
+function lintOne(name, file, repoRoot) {
+  const errors = [];
+  const warnings = [];
+  const push = (list, rule, msg) => list.push({ skill: name, rule, msg });
+  const text = fs.readFileSync(file, 'utf8');
+
+  let fm = null;
+  try {
+    fm = parseFrontmatter(text);
+    if (!fm) push(errors, 'SK-001', 'no `---` frontmatter at the start of the file');
+  } catch (e) {
+    push(errors, 'SK-001', `frontmatter does not parse: ${e.message}`);
+  }
+  if (fm) {
+    const { name: n, description: d } = fm.data;
+    if (n !== name) push(errors, 'SK-002', `name \`${n ?? '(missing)'}\` does not match directory \`${name}\``);
+    if (typeof d !== 'string' || !d.trim()) push(errors, 'SK-003', 'frontmatter missing `description`');
+    else if (d.length < DESC_MIN) push(errors, 'SK-003', `description too short (${d.length} chars; min ${DESC_MIN})`);
+    else if (d.length > DESC_MAX) push(errors, 'SK-003', `description too long (${d.length} chars; max ${DESC_MAX})`);
+  }
+
+  const bytes = Buffer.byteLength(text);
+  if (bytes > SIZE_BUDGET && !HEAVY_ALLOWED[name]) {
+    push(warnings, 'SK-004', `${(bytes / 1024).toFixed(1)} KB over the ${SIZE_BUDGET / 1024} KB budget — loaded whole into context`);
+  }
+  for (const msg of danglingRefs(text, path.dirname(file), repoRoot)) push(errors, 'SK-005', msg);
+  for (const m of text.matchAll(PRIVATE_PATH)) push(errors, 'SK-006', `private absolute path \`${m[0]}…\``);
+  for (const msg of strictYamlIssues(text)) push(errors, 'SK-007', msg);
+  return { errors, warnings };
+}
+
+/** Lint every skills/<name>/SKILL.md under repoRoot. */
+export function lintSkills({ repoRoot }) {
+  const dir = path.join(repoRoot, 'skills');
+  const names = fs.readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, 'SKILL.md')))
+    .map((e) => e.name).sort();
+  const errors = [];
+  const warnings = [];
+  for (const n of names) {
+    const r = lintOne(n, path.join(dir, n, 'SKILL.md'), repoRoot);
+    errors.push(...r.errors);
+    warnings.push(...r.warnings);
+  }
+  return { skills: names.length, errors, warnings };
+}
+
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (isMain) {
+  const a = process.argv.slice(2);
+  const i = a.indexOf('--root');
+  if (i >= 0 && !a[i + 1]) { process.stderr.write('usage: skill-lint.mjs [--root <repo>] [--json]\n'); process.exit(2); }
+  const repoRoot = i >= 0 ? path.resolve(a[i + 1]) : path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  let r;
+  try { r = lintSkills({ repoRoot }); } catch (e) { process.stderr.write(`skill-lint: ${e.message}\n`); process.exit(2); }
+  if (a.includes('--json')) {
+    process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+  } else {
+    for (const e of r.errors) process.stdout.write(`ERROR ${e.rule} skills/${e.skill}: ${e.msg}\n`);
+    for (const w of r.warnings) process.stdout.write(`warn  ${w.rule} skills/${w.skill}: ${w.msg}\n`);
+    const heavy = Object.keys(HEAVY_ALLOWED).join(', ');
+    process.stdout.write(`skill-lint: ${r.skills} skills · ${r.errors.length} errors · ${r.warnings.length} warnings (heavy by allow-list: ${heavy})\n`);
+  }
+  process.exit(r.errors.length ? 1 : 0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "3.59.0",
+  "version": "3.60.0",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",

package/postinstall.mjs

@@ -138,32 +138,38 @@ function main() {
  *   - never block. The board takes the better part of a minute to become
  *     responsive; the installer does not wait for it. Detached, unref'd, output
  *     discarded.
- *   - never in CI, and never when asked not to. Both already guard the notice
- *     above; `GREAT_CTO_NO_BOARD=1` opts out of this specifically.
+ *   - never in CI or a Node test runner, and never when asked not to. A test
+ *     HOME isolates files, NOT ports: a detached board would still claim the
+ *     user's :3141 and serve fixture projects after the test exits.
+ *     `GREAT_CTO_NO_BOARD=1` opts out of this specifically.
  *   - never twice. `ensure` probes the port first and adopts a board that is
  *     already answering, whoever started it.
  */
-function ensureBoard() {
-  if (process.env.GREAT_CTO_NO_BOARD) return;
+export function ensureBoard({ env = process.env, spawnFn = spawn,
+  write = (text) => process.stdout.write(text) } = {}) {
+  if (env.CI || env.GREAT_CTO_QUIET_POSTINSTALL || env.GREAT_CTO_NO_BOARD || env.NODE_TEST_CONTEXT) return false;
   try {
     const here = dirname(fileURLToPath(import.meta.url));
     const entry = join(here, 'index.mjs');
-    if (!existsSync(entry)) return;
+    if (!existsSync(entry)) return false;
 
-    const child = spawn(process.execPath, [entry, 'board', 'ensure'], {
+    const child = spawnFn(process.execPath, [entry, 'board', 'ensure'], {
       detached: true,
       stdio: 'ignore',
+      env,
     });
     child.unref();
-    process.stdout.write('  great-cto: starting the board — http://localhost:3141\n');
+    write('  great-cto: starting the board — http://localhost:3141\n');
+    return true;
   } catch (e) {
     // Never fail the install — but never fail SILENTLY either. The first version
     // of this function referenced an import that was not there; the catch ate the
     // ReferenceError and the hook printed nothing, so the board simply did not
     // start and nothing said why. A swallowed error is the defect this project
     // spends most of its checks on.
-    process.stdout.write(`  great-cto: could not start the board — ${e?.message || e}\n`);
-    process.stdout.write('  Start it yourself with: great-cto board\n');
+    write(`  great-cto: could not start the board — ${e?.message || e}\n`);
+    write('  Start it yourself with: great-cto board\n');
+    return false;
   }
 }