@remits/remits-cli 0.1.113 → 0.1.114

package/index.js

@@ -24,7 +24,10 @@ const SESSIONS_FILE = path.join(SESSION_DIR, 'sessions.json');
 const CONFIG_FILE = path.join(SESSION_DIR, 'config.json');
 const LISTENER_PID_FILE = path.join(SESSION_DIR, 'listener.pid');
 const ACTIVITY_LOG_FILE = path.join(SESSION_DIR, 'activity.log');
-const SKILL_SOURCE_FILE = path.join(__dirname, 'skills', 'remits-cli', 'SKILL.md');
+const SKILL_SOURCE_DIR = path.join(__dirname, 'skills', 'remits-cli');
+const SKILL_SOURCE_FILE = path.join(SKILL_SOURCE_DIR, 'SKILL.md');
+const SKILL_REFERENCES_DIRNAME = 'references';
+const SKILL_REFERENCES_SOURCE_DIR = path.join(SKILL_SOURCE_DIR, SKILL_REFERENCES_DIRNAME);
 const ACCOUNT_REPO_INDEX_FILE = path.join(SESSION_DIR, 'account-repos.json');
 const SERVICE_STATE_FILE = path.join(SESSION_DIR, 'service-state.json');
 const ISSUES_DIR = path.join(SESSION_DIR, 'issues');
@@ -1297,7 +1300,6 @@ function updateAccountRepoIndex(cwd) {
   if (!info) {
     return;
   }
-  try { syncInstalledSkills(); } catch (_) { /* best-effort */ }
   const entry = buildAccountRepoEntryFromInfo(info, cwd, 'cwd');
   if (!entry) {
     return;
@@ -1371,7 +1373,6 @@ function discoverAccountRepos() {
   for (const root of roots) {
     walkForAccountInfo(root, 0, matches, visited, platformMatches);
   }
-  try { syncInstalledSkills(); } catch (_) { /* best-effort */ }
 
   const entries = [];
   for (const file of matches) {
@@ -1924,13 +1925,166 @@ async function loggedGet(api, cwd, endpoint, params = {}) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Skill delivery
+//
+// The skill is SKILL.md (the index and the rules) plus the reference files in
+// skills/remits-cli/references/. Both ship inside the npm package, so the whole
+// skill is available before the CLI has ever authenticated.
+//
+// Every delivered markdown file goes through deliverSkillMarkdown(), which is
+// the ONE delivery path: it substitutes the machine-specific placeholders and
+// resolves each file's table of contents to real line numbers. Writing a file
+// out with fs.writeFileSync + readFileSync instead would ship the same skill
+// with a different table of contents depending on which door it came out of.
+// ---------------------------------------------------------------------------
+
+// GitHub-style heading anchor: lowercase, punctuation dropped, spaces to hyphens.
+function headingSlug(headingText) {
+  return String(headingText || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9 _-]/g, '')
+    .trim()
+    .replace(/\s/g, '-');
+}
+
+function formatTocEntry(indent, target) {
+  if (!target) return null;
+  return indent + '- L' + target.line + '  ' + target.title;
+}
+
+// Rewrites a document's "## Table of Contents" entries to carry the line number of
+// the heading they point at, turning the TOC into a jump table:
+//
+//   - [Component Structure](#component-structure)   ->   - L59  Component Structure
+//   - Line 31: Component Structure                  ->   - L59  Component Structure
+//
+// Numbers are computed HERE, at delivery, never written into the repo file.
+// Hand-maintained line numbers rot on the first edit above them, and a WRONG
+// number is worse than none: it sends the reader to the wrong section, where it
+// may conclude the content is missing. Resolving at delivery means the numbers
+// cannot be stale, while the repo file keeps anchor links that survive edits and
+// produce clean diffs.
+//
+// INVARIANT: every rewrite is one line in, one line out. The line count must not
+// change, or the numbers computed against the input would no longer describe the
+// output. Locked down by test/skill-references.test.js.
+//
+// An entry whose target heading cannot be resolved is left exactly as written —
+// it degrades to the original text, never to a guessed number.
+function resolveTableOfContentsLineNumbers(markdown) {
+  if (!markdown || !markdown.trim()) {
+    return markdown;
+  }
+
+  const lines = markdown.split('\n');
+  const tocStart = lines.findIndex((line) => /^##\s+table of contents\s*$/i.test(line));
+  if (tocStart < 0) {
+    return markdown;
+  }
+
+  let tocEnd = lines.length;
+  for (let i = tocStart + 1; i < lines.length; i += 1) {
+    if (/^##(?!#)\s+.*$/.test(lines[i])) {
+      tocEnd = i;
+      break;
+    }
+  }
+
+  // A `#`-prefixed line inside a fenced code block is CONTENT, not a heading. The
+  // references routinely show markdown and shell samples that contain one. Indexing
+  // those shifts GitHub's duplicate-slug disambiguation (-1, -2 ...) out of step with
+  // the real headings, so a legitimate repeated heading resolves to the wrong line.
+  const byAnchor = new Map();
+  const byTitle = new Map();
+  const slugCounts = new Map();
+  let inFence = false;
+
+  lines.forEach((line, index) => {
+    if (/^\s{0,3}(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      return;
+    }
+    if (inFence) return;
+
+    const heading = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (!heading) return;
+
+    const title = heading[2].trim();
+    const target = { line: index + 1, title };
+
+    const baseSlug = headingSlug(title);
+    const seen = slugCounts.get(baseSlug) || 0;
+    slugCounts.set(baseSlug, seen + 1);
+    const slug = seen === 0 ? baseSlug : baseSlug + '-' + seen;
+
+    if (!byAnchor.has(slug)) byAnchor.set(slug, target);
+    if (!byTitle.has(title)) byTitle.set(title, target);
+  });
+
+  let changed = false;
+  for (let i = tocStart + 1; i < tocEnd; i += 1) {
+    const rewritten = resolveTocEntry(lines[i], byAnchor, byTitle);
+    if (rewritten !== null) {
+      lines[i] = rewritten;
+      changed = true;
+    }
+  }
+
+  return changed ? lines.join('\n') : markdown;
+}
+
+// The rewritten entry carries the ACTUAL heading text, not the TOC's own link text.
+// The two drift (a heading gets reworded and the TOC entry does not), and emitting
+// the heading text both self-heals that drift and guarantees the entry is a literal
+// match for the heading — so an agent can grep it as-is rather than trusting the number.
+//
+// Returns null when the line is not a resolvable TOC entry and must be left untouched.
+function resolveTocEntry(line, byAnchor, byTitle) {
+  const anchorEntry = /^(\s*)[-*]\s+\[(.+)\]\(#([^)\s]+)\)\s*$/.exec(line);
+  if (anchorEntry) {
+    return formatTocEntry(anchorEntry[1], byAnchor.get(anchorEntry[3]));
+  }
+
+  // Legacy hand-written form. Re-resolving it corrects files that have not been
+  // audited yet, instead of shipping their stale numbers.
+  const legacyEntry = /^(\s*)[-*]\s+Line\s+\d+:\s*(.+?)\s*$/.exec(line);
+  if (legacyEntry) {
+    const title = legacyEntry[2];
+    return formatTocEntry(legacyEntry[1], byTitle.get(title) || byAnchor.get(headingSlug(title)));
+  }
+
+  return null;
+}
+
+// THE single delivery path for a skill markdown file. Substitutes the placeholders
+// that only the installing machine can fill in, then resolves the table of contents.
+function deliverSkillMarkdown(sourceText, referencesDir) {
+  let body = String(sourceText);
+  body = body.split('{{ACCOUNT_REPO_INDEX_PATH}}').join(ACCOUNT_REPO_INDEX_FILE);
+  body = body.split('{{SKILL_REFERENCES_DIR}}').join(referencesDir);
+  return resolveTableOfContentsLineNumbers(body);
+}
+
 function resolveSkillTargets(target) {
   const value = String(target || 'all').toLowerCase();
   const home = os.homedir();
+  // Gemini reads a FLAT skill file, so its references cannot sit beside it as
+  // `references/`. That is why SKILL.md states the reference directory as an
+  // absolute path substituted per target rather than a relative one.
   const targets = {
-    codex: path.join(home, '.codex', 'skills', 'remits-cli', 'SKILL.md'),
-    claude: path.join(home, '.claude', 'skills', 'remits-cli', 'SKILL.md'),
-    gemini: path.join(home, '.gemini', 'skills', 'remits-cli.md')
+    codex: {
+      skillPath: path.join(home, '.codex', 'skills', 'remits-cli', 'SKILL.md'),
+      referencesDir: path.join(home, '.codex', 'skills', 'remits-cli', SKILL_REFERENCES_DIRNAME)
+    },
+    claude: {
+      skillPath: path.join(home, '.claude', 'skills', 'remits-cli', 'SKILL.md'),
+      referencesDir: path.join(home, '.claude', 'skills', 'remits-cli', SKILL_REFERENCES_DIRNAME)
+    },
+    gemini: {
+      skillPath: path.join(home, '.gemini', 'skills', 'remits-cli.md'),
+      referencesDir: path.join(home, '.gemini', 'skills', 'remits-cli', SKILL_REFERENCES_DIRNAME)
+    }
   };
 
   if (value === 'all') {
@@ -1942,34 +2096,83 @@ function resolveSkillTargets(target) {
   return [[value, targets[value]]];
 }
 
-function buildSkillSourceBody() {
+function listSkillReferenceSources() {
+  if (!fs.existsSync(SKILL_REFERENCES_SOURCE_DIR)) {
+    return [];
+  }
+  return fs.readdirSync(SKILL_REFERENCES_SOURCE_DIR)
+    .filter((name) => name.endsWith('.md'))
+    .sort();
+}
+
+function buildSkillSourceBody(referencesDir) {
   if (!fs.existsSync(SKILL_SOURCE_FILE)) {
     throw new Error('Skill source file not found: ' + SKILL_SOURCE_FILE);
   }
+  return deliverSkillMarkdown(fs.readFileSync(SKILL_SOURCE_FILE, 'utf8'), referencesDir);
+}
+
+// Install the reference set beside (or, for gemini, alongside) the skill file, and
+// prune any reference this CLI version no longer ships. A stale reference is worse
+// than a missing one: SKILL.md would not name it, but an agent listing the directory
+// would still find and trust it.
+function writeSkillReferences(referencesDir, options = {}) {
+  const names = listSkillReferenceSources();
+  const written = [];
+  if (!names.length) {
+    return written;
+  }
+
+  ensureDir(referencesDir);
+  const expected = new Set(names);
+
+  for (const name of names) {
+    const body = deliverSkillMarkdown(
+      fs.readFileSync(path.join(SKILL_REFERENCES_SOURCE_DIR, name), 'utf8'),
+      referencesDir
+    );
+    const targetPath = path.join(referencesDir, name);
+    if (options.overwrite === false && fs.existsSync(targetPath)) {
+      continue;
+    }
+    if (writeFileIfChanged(targetPath, body)) {
+      written.push(targetPath);
+    }
+  }
+
+  try {
+    for (const existing of fs.readdirSync(referencesDir)) {
+      if (existing.endsWith('.md') && !expected.has(existing)) {
+        fs.unlinkSync(path.join(referencesDir, existing));
+      }
+    }
+  } catch (_) {
+    // Best-effort pruning; a stale file never blocks delivery of the current set.
+  }
 
-  let sourceBody = fs.readFileSync(SKILL_SOURCE_FILE, 'utf8');
-  sourceBody = sourceBody.replace('{{ACCOUNT_REPO_INDEX_PATH}}', ACCOUNT_REPO_INDEX_FILE);
-  return sourceBody;
+  return written;
 }
 
 function syncInstalledSkills(target = 'all') {
   const targets = resolveSkillTargets(target);
-  const sourceBody = buildSkillSourceBody();
   const summary = {
     updated: [],
     failed: []
   };
 
-  for (const [agent, targetPath] of targets) {
+  for (const [agent, spec] of targets) {
     try {
-      ensureDir(path.dirname(targetPath));
-      if (writeFileIfChanged(targetPath, sourceBody)) {
-        summary.updated.push({ agent, path: targetPath });
+      ensureDir(path.dirname(spec.skillPath));
+      if (writeFileIfChanged(spec.skillPath, buildSkillSourceBody(spec.referencesDir))) {
+        summary.updated.push({ agent, path: spec.skillPath });
+      }
+      for (const referencePath of writeSkillReferences(spec.referencesDir)) {
+        summary.updated.push({ agent, path: referencePath });
       }
     } catch (error) {
       summary.failed.push({
         agent,
-        path: targetPath,
+        path: spec.skillPath,
         reason: error && error.message ? error.message : String(error)
       });
     }
@@ -1985,19 +2188,24 @@ async function installSkillsCommand(flags) {
 
   const overwrite = flags.overwrite === true || flags.overwrite === 'true';
   const targets = resolveSkillTargets(flags.target || 'all');
-  const sourceBody = buildSkillSourceBody();
 
   const installed = [];
   const skipped = [];
 
-  for (const [agent, targetPath] of targets) {
-    ensureDir(path.dirname(targetPath));
-    if (fs.existsSync(targetPath) && !overwrite) {
-      skipped.push({ agent, path: targetPath, reason: 'already exists (use --overwrite true)' });
-      continue;
+  for (const [agent, spec] of targets) {
+    ensureDir(path.dirname(spec.skillPath));
+    if (fs.existsSync(spec.skillPath) && !overwrite) {
+      skipped.push({ agent, path: spec.skillPath, reason: 'already exists (use --overwrite true)' });
+    } else {
+      atomicWriteFile(spec.skillPath, buildSkillSourceBody(spec.referencesDir));
+      installed.push({ agent, path: spec.skillPath });
+    }
+    // References are refreshed even when the skill file itself was left alone: an
+    // agent reading a customized SKILL.md still needs the reference set it points at.
+    const references = writeSkillReferences(spec.referencesDir);
+    if (references.length) {
+      installed.push({ agent, path: spec.referencesDir + ' (' + references.length + ' reference file(s))' });
     }
-    atomicWriteFile(targetPath, sourceBody);
-    installed.push({ agent, path: targetPath });
   }
 
   console.log('Skill installation complete.');
@@ -9140,6 +9348,15 @@ async function main() {
     if (autoUpdateIfNeeded(originalArgv, { requireSuccess: requireSuccessfulAutoUpdate })) return;
   }
 
+  // Refresh the installed skill on EVERY command, not just from inside an account repo. This runs
+  // after the auto-update re-exec, so it is the new version writing the new skill. It was previously
+  // hung off updateAccountRepoIndex(), which returns early outside a repo — so a user who upgraded and
+  // then ran `remits-cli agent serve` from a plain tab (the documented way to work tickets, explicitly
+  // "no need to be in an account repo") kept the PREVIOUS skill on disk indefinitely: a stale index
+  // pointing at reference files that the upgrade had just renamed or removed. Reading and comparing the
+  // whole corpus across all three agent targets measures ~3ms, so there is nothing to save by guarding it.
+  try { syncInstalledSkills(); } catch (_) { /* best-effort */ }
+
   // Best-effort: update account-repo index whenever running from inside a remits repo
   try { updateAccountRepoIndex(process.cwd()); } catch (_) { /* not in account repo */ }
   // Auto-start the background service if not already running.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.113",
+  "version": "0.1.114",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,
@@ -12,7 +12,8 @@
   "files": [
     "index.js",
     "README.md",
-    "skills/remits-cli/SKILL.md"
+    "skills/remits-cli/SKILL.md",
+    "skills/remits-cli/references"
   ],
   "publishConfig": {
     "access": "public"