devlyn-cli 4.2.7 → 4.2.9

package/README.md

@@ -35,7 +35,7 @@ That's it. The installer asks:
 
 In a project, AGENTS.md readers load the skills from `.agents/skills/`; Claude Code loads only `.claude/skills/` and reads AGENTS.md when the project has no CLAUDE.md; a CLAUDE.md the installer creates imports an existing AGENTS.md (`@AGENTS.md`). Global installs skills only: `~/.agents/skills/` (omp, Pi, Grok) and `~/.codex/skills/` (Codex), plus `~/.claude/skills/` for Claude Code. Every target gets the `devlyn-ideate` skill and the `devlyn-engines` utility. In Codex / omp / Pi, invoke them as skills (`$devlyn-ideate`); in Claude Code and Grok they're slash commands (`/devlyn-ideate`). Rerunning refreshes skills and the managed instruction block while preserving project rules outside it. See [Migration from earlier versions](#migration-from-earlier-versions) for legacy migration and merge recovery.
 
-Without prompts, `npx devlyn-cli -y` installs AGENTS.md + `.agents/skills/` plus every target this project already has; add `--claude` for Claude Code. With `--global` it installs for every project on this machine, plus `~/.claude/skills/` with `--claude` or when it already has a devlyn install.
+Without prompts, `npx devlyn-cli -y` installs AGENTS.md + `.agents/skills/` plus every target this project already has; add `--claude` for Claude Code. With `--global` it installs for every project on this machine, plus `~/.claude/skills/` with `--claude` or when it already has a devlyn install. After a project install or update, the installer names the changed files to commit, including installed files a `.gitignore` hides, so teammates and `/devlyn-ideate` drains can use them.
 
 ---
 

package/bin/devlyn.js

@@ -3,13 +3,13 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { execSync } = require('child_process');
+const { execSync, spawnSync } = require('child_process');
 
 const CONFIG_SOURCE = path.join(__dirname, '..', 'config');
 const OPTIONAL_SKILLS_SOURCE = path.join(__dirname, '..', 'optional-skills');
 const PKG = require('../package.json');
 const { updateInstructions, InstructionError, holdsDevlynDefaults, importsAgentsMd } = require('./instructions');
-const { contentHash, fingerprint, isIgnoredEntry, trackedPaths } = require('./skill-ownership');
+const { contentHash, fingerprint, gitEnvironment, isIgnoredEntry, trackedPaths } = require('./skill-ownership');
 const SKILL_HISTORY = require('./skill-history.json');
 
 // The devlyn skill bundle installed into every skill-capable agent's loader
@@ -346,13 +346,14 @@ function listContents() {
 }
 
 // Old and retired skills in one skill root; nothing outside it.
-function cleanupDeprecated(skillsDir) {
+function cleanupDeprecated(skillsDir, written) {
   let removed = 0;
   const deprecated = DEPRECATED_DIRS.flatMap((relPath) =>
     legacySkillPaths(skillsDir, path.basename(relPath)).map((fullPath) => [relPath, fullPath]));
   for (const [relPath, fullPath] of deprecated) {
     if (fs.existsSync(fullPath)) {
       fs.rmSync(fullPath, { recursive: true });
+      written.push(fullPath);
       log(`  ✕ ${relPath}/ (removed)`, 'dim');
       removed++;
     }
@@ -361,6 +362,7 @@ function cleanupDeprecated(skillsDir) {
     const fullPath = path.join(skillsDir, name);
     if (isShippedCopy(fullPath, hashes)) {
       fs.rmSync(fullPath, { recursive: true });
+      written.push(fullPath);
       log(`  ✕ skills/${name}/ (removed)`, 'dim');
       removed++;
     }
@@ -372,27 +374,30 @@ function cleanupDeprecated(skillsDir) {
 // are in place. An optional skill found under an old spelling is installed under its new name
 // before the old copy goes, so an interrupted migration never loses it. An unedited 0.6.0-0.7.1
 // copy is refreshed in place. Any other folder under a 4.0 name is the user's own; `-y` leaves it.
-function retireRenamedSkills(skillsDir) {
+function retireRenamedSkills(skillsDir, written, installedSkills) {
   const optional = new Set(OPTIONAL_ADDONS.filter((addon) => addon.type === 'local').map((addon) => addon.name));
   const refreshed = [];
   for (const [oldName, newName] of Object.entries(RENAMED_SKILLS)) {
     const found = legacySkillPaths(skillsDir, oldName).filter((fullPath) => fs.existsSync(fullPath));
     if (found.length > 0 && optional.has(newName)) {
-      installOptionalSkillInto(skillsDir, newName);
+      installOptionalSkillInto(skillsDir, newName, written, installedSkills);
       refreshed.push(newName);
     } else if (isShippedCopy(path.join(skillsDir, newName), PRE_STANDARD_SKILL_MD_SHA256)) {
       refreshPreStandardCopy(skillsDir, newName);
+      written.push(path.join(skillsDir, newName));
+      installedSkills.set(path.join(skillsDir, newName), [path.join(skillsDir, newName, 'SKILL.md')]);
       refreshed.push(newName);
     }
     for (const fullPath of found) {
       fs.rmSync(fullPath, { recursive: true, force: true });
+      written.push(fullPath);
       log(`  ✕ ${path.basename(fullPath)}/ (renamed to ${newName})`, 'dim');
     }
   }
   return refreshed;
 }
 
-function copyRecursive(src, dest, baseDir) {
+function copyRecursive(src, dest, baseDir, files = []) {
   const stats = fs.statSync(src);
 
   if (stats.isDirectory()) {
@@ -401,7 +406,7 @@ function copyRecursive(src, dest, baseDir) {
     }
 
     for (const item of fs.readdirSync(src)) {
-      copyRecursive(path.join(src, item), path.join(dest, item), baseDir);
+      copyRecursive(path.join(src, item), path.join(dest, item), baseDir, files);
     }
   } else {
     const destDir = path.dirname(dest);
@@ -409,8 +414,10 @@ function copyRecursive(src, dest, baseDir) {
       fs.mkdirSync(destDir, { recursive: true });
     }
     fs.copyFileSync(src, dest);
+    files.push(dest);
     log(`  → ${path.relative(baseDir, dest)}`, 'dim');
   }
+  return files;
 }
 
 function clearInstallMarker(skillsDir) {
@@ -610,30 +617,34 @@ function singleSelect(message, items, initial) {
   });
 }
 
-// After install(), whose preflight already cleared every selected addon before any change.
-function installLocalSkill(skillName, roots) {
+// After preflight has cleared every selected addon before any change.
+function installLocalSkill(skillName, roots, written = [], installedSkills = new Map()) {
   if (!fs.existsSync(path.join(OPTIONAL_SKILLS_SOURCE, skillName))) {
     log(`   ⚠️  Skill "${skillName}" not found`, 'yellow');
     return false;
   }
   log(`\n🛠️  Installing ${skillName}...`, 'cyan');
   for (const root of roots) {
-    installOptionalSkillInto(root, skillName);
+    installOptionalSkillInto(root, skillName, written, installedSkills);
     writeInstallMarker(root, [skillName], readInstallManifest(root));
+    written.push(path.join(root, DEVLYN_INSTALL_MARKER));
   }
   return true;
 }
 
 // One optional skill into one skill-loader directory, replacing any older copy of it. A
 // copy under its name before the 4.0.0 rename goes only once the new one is complete.
-function installOptionalSkillInto(target, skillName) {
+function installOptionalSkillInto(target, skillName, written, installedSkills) {
   const dest = path.join(target, skillName);
   fs.rmSync(dest, { recursive: true, force: true });
-  copyRecursive(path.join(OPTIONAL_SKILLS_SOURCE, skillName), dest, target);
+  installedSkills.set(dest, copyRecursive(path.join(OPTIONAL_SKILLS_SOURCE, skillName), dest, target));
   assertCompleteSkillInstall(OPTIONAL_SKILLS_SOURCE, target, [skillName]);
+  written.push(dest);
   const oldName = Object.keys(RENAMED_SKILLS).find((name) => RENAMED_SKILLS[name] === skillName);
   for (const fullPath of oldName ? legacySkillPaths(target, oldName) : []) {
+    if (!fs.existsSync(fullPath)) continue;
     fs.rmSync(fullPath, { recursive: true, force: true });
+    written.push(fullPath);
   }
 }
 
@@ -679,10 +690,7 @@ function installSkillPack(packName) {
   }
 }
 
-function installAddon(addon, roots) {
-  if (addon.type === 'local') {
-    return installLocalSkill(addon.name, roots);
-  }
+function installAddon(addon) {
   if (addon.type === 'mcp') {
     return installMcpServer(addon.name, addon.command);
   }
@@ -691,13 +699,13 @@ function installAddon(addon, roots) {
 
 // The core skills into one skill root, replacing older copies and retired skills, then the
 // marker that records a complete install.
-function installCoreSkills(skillsDir) {
+function installCoreSkills(skillsDir, written = [], installedSkills = new Map()) {
   const sourceSkillsDir = path.join(CONFIG_SOURCE, 'skills');
   log(`\n📁 Installing devlyn skills to ${skillsDir.replace(os.homedir(), '~')}`, 'green');
   fs.mkdirSync(skillsDir, { recursive: true });
   const previous = readInstallManifest(skillsDir);
   clearInstallMarker(skillsDir);
-  const removed = cleanupDeprecated(skillsDir);
+  const removed = cleanupDeprecated(skillsDir, written);
   if (removed > 0) {
     log(`\n🧹 Cleaned up ${removed} deprecated file${removed > 1 ? 's' : ''}`, 'yellow');
   }
@@ -707,11 +715,13 @@ function installCoreSkills(skillsDir) {
     if (!fs.existsSync(src)) continue;
     // Full replace: copyRecursive is an overlay, so stale files would otherwise persist.
     fs.rmSync(dest, { recursive: true, force: true });
-    copyRecursive(src, dest, skillsDir);
+    installedSkills.set(dest, copyRecursive(src, dest, skillsDir));
+    written.push(dest);
   }
   assertCompleteSkillInstall(sourceSkillsDir, skillsDir, DEVLYN_CORE_SKILLS);
-  const refreshed = retireRenamedSkills(skillsDir);
+  const refreshed = retireRenamedSkills(skillsDir, written, installedSkills);
   writeInstallMarker(skillsDir, [...DEVLYN_CORE_SKILLS, ...refreshed], previous);
+  written.push(path.join(skillsDir, DEVLYN_INSTALL_MARKER));
 }
 
 function readProjectGitignore() {
@@ -763,7 +773,9 @@ function updateProjectGitignore(markerEntry) {
   if (!gitignoreContent.equals(original)) {
     fs.writeFileSync(gitignorePath, gitignoreContent);
     log('  → .gitignore (updated project install rules)', 'dim');
+    return true;
   }
+  return false;
 }
 
 // With the Claude target in the same run, an AGENTS.md that links to this project's CLAUDE.md (a
@@ -783,17 +795,19 @@ function agentsMdIsClaudeMd() {
   return target !== null && fs.existsSync(target) && fs.realpathSync.native(target) === fs.realpathSync.native(claude);
 }
 
-function installAgentsProject(withClaude) {
+function installAgentsProject(withClaude, installedSkills = new Map()) {
+  const written = [];
   if (!agentsMdIsClaudeMd()) {
-    updateInstructions('AGENTS.md');
+    if (updateInstructions('AGENTS.md')) written.push('AGENTS.md');
   } else if (withClaude) {
     log('  → AGENTS.md is CLAUDE.md here, so it gets the devlyn block written there', 'dim');
   } else {
     throw new InstructionError('AGENTS.md is CLAUDE.md under another name here. Choose CLAUDE.md as well '
       + '(npx devlyn-cli -y --claude) so the devlyn block is written once, into CLAUDE.md.');
   }
-  installCoreSkills(skillRoots('agents', false)[0]);
-  updateProjectGitignore('.agents/skills/.devlyn-install.json');
+  installCoreSkills(skillRoots('agents', false)[0], written, installedSkills);
+  if (updateProjectGitignore('.agents/skills/.devlyn-install.json')) written.push('.gitignore');
+  return written;
 }
 
 // Whether Claude Code reads the devlyn defaults of AGENTS.md through an `@AGENTS.md` import in this CLAUDE.md text.
@@ -817,12 +831,13 @@ function installClaudeInstructions() {
     throw new InstructionError('Claude Code reads AGENTS.md here, and its devlyn defaults need an update. Codex, omp, Pi and Grok '
       + 'read them too, with .agents/skills, so choose AGENTS.md as well (npx devlyn-cli -y --claude) to update both together.');
   }
-  updateInstructions('CLAUDE.md', initial, !imported);
+  const changed = updateInstructions('CLAUDE.md', initial, !imported);
   if (imported) log('  → CLAUDE.md imports AGENTS.md, which holds the devlyn block', 'dim');
+  return changed;
 }
 
 // Project CLAUDE.md and .claude/: skills and settings.
-function installClaudeCore() {
+function installClaudeCore(installedSkills = new Map()) {
   const skillsDir = skillRoots('claude', false)[0];
   const targetDir = path.dirname(skillsDir);
   // Read before any write, so settings this install cannot merge leave the Claude target as it was.
@@ -845,16 +860,17 @@ function installClaudeCore() {
       && (!settings.env || typeof settings.env !== 'object' || Array.isArray(settings.env))) {
     throw unmergeable('env must be a JSON object');
   }
-  installClaudeInstructions();
+  const written = installClaudeInstructions() ? ['CLAUDE.md'] : [];
   for (const relPath of DEPRECATED_FILES) {
     const fullPath = path.join(targetDir, relPath);
     if (fs.existsSync(fullPath)) {
       fs.unlinkSync(fullPath);
       log(`  ✕ ${relPath} (deprecated)`, 'dim');
+      written.push(`.claude/${relPath}`);
     }
   }
-  installCoreSkills(skillsDir);
-  updateProjectGitignore('.claude/skills/.devlyn-install.json');
+  installCoreSkills(skillsDir, written, installedSkills);
+  if (updateProjectGitignore('.claude/skills/.devlyn-install.json')) written.push('.gitignore');
 
   // One-hour foreground Bash calls and one-hour prompt caching serve a drain host that waits in the foreground.
   let settingsChanged = false;
@@ -885,6 +901,7 @@ function installClaudeCore() {
   if (settingsChanged) {
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     log('  → settings.json', 'dim');
+    written.push('.claude/settings.json');
   }
   // Their ownership cannot be established, so the other retired settings stay; name the ones present.
   const retired = [
@@ -894,6 +911,7 @@ function installClaudeCore() {
   if (retired.length > 0) {
     log(`  Retired devlyn settings may remain in .claude/settings.json: ${retired.join(', ')} — delete those you did not add yourself.`, 'yellow');
   }
+  return written;
 }
 
 // Installs the targets in one scope; returns the skill roots written.
@@ -908,21 +926,90 @@ function install(targets, global, optionalNames = []) {
       + 'would apply to every project. Run from a project folder, or use --global for skills only.');
   }
   const roots = targets.flatMap((target) => skillRoots(target, global));
+  const written = [];
+  const installedSkills = new Map();
   if (!global) readProjectGitignore();
   preflightSkills(roots, optionalNames,
     !global && targets.includes('claude') ? path.dirname(skillRoots('claude', false)[0]) : null);
   // AGENTS.md first, whatever order the menu gave: a new CLAUDE.md holds the block only when AGENTS.md does not.
   for (const target of ['agents', 'claude'].filter((name) => targets.includes(name))) {
     if (global) skillRoots(target, true).forEach((root) => installCoreSkills(root));
-    else if (target === 'agents') installAgentsProject(targets.includes('claude'));
-    else installClaudeCore();
+    else if (target === 'agents') written.push(...installAgentsProject(targets.includes('claude'), installedSkills));
+    else written.push(...installClaudeCore(installedSkills));
   }
+  for (const name of optionalNames) installLocalSkill(name, roots, written, installedSkills);
   log(`\n✅ devlyn ${PKG.version} installed`, 'green');
   if (global) log('The principles block installs per project: run npx devlyn-cli in the project without --global.');
+  else noticeProjectChanges(written, installedSkills);
   noticeGlobalDrift(roots);
   return roots;
 }
 
+// Advisory only: a successful install stays successful when Git is unavailable or fails.
+function noticeProjectChanges(paths, installedSkills = new Map()) {
+  if (!paths.length && !installedSkills.size) return;
+  const cwd = projectDir();
+  const relative = (name) => path.relative(cwd, path.resolve(cwd, name)).split(path.sep).join('/');
+  paths = [...new Set(paths.map(relative))];
+  const env = { ...gitEnvironment(), GIT_OPTIONAL_LOCKS: '0' };
+  const git = (args, input) => spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8', env, input });
+  const repo = git(['rev-parse', '--show-toplevel']);
+  if (repo.error || repo.status !== 0) return;
+  const status = git(['status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames',
+    '--', ...paths.map((name) => `:(icase,literal)${name}`)]);
+  if (status.error || status.status !== 0) return;
+  // Porcelain paths are repository-relative, even when installing in a nested project.
+  const changed = status.stdout.split('\0').filter(Boolean).map((entry) =>
+    path.relative(cwd, path.resolve(repo.stdout.replace(/\r?\n$/, ''), entry.slice(3))).split(path.sep).join('/'));
+  // Keep the installed folder/file scope, using Git's spelling on case-insensitive volumes.
+  const pending = [...new Set(paths.flatMap((name) => [...new Set(changed
+    .map((file) => file.split('/').slice(0, name.split('/').length).join('/')))]
+    .filter((file) => {
+      if (file === name) return true;
+      if (file.toLowerCase() !== name.toLowerCase()) return false;
+      // Case folding alone can include independently edited files on case-sensitive volumes.
+      // Removed paths have no identity left to compare, so require their exact spelling.
+      try {
+        const written = fs.lstatSync(path.resolve(cwd, name), { bigint: true, throwIfNoEntry: false });
+        const reported = fs.lstatSync(path.resolve(cwd, file), { bigint: true, throwIfNoEntry: false });
+        return written && reported && written.dev === reported.dev && written.ino === reported.ino;
+      } catch (error) {
+        log(`Cannot compare Git path ${file} with installed path ${name}: ${error.message}`, 'yellow');
+        return false;
+      }
+    })))];
+  // Check only files this run copied, grouped by skill: ignoring a whole skill is deliberate.
+  // check-ignore omits tracked files, so a complete committed install stays quiet on reruns.
+  const groups = [...installedSkills.values()].map((files) => files.map(relative));
+  const files = groups.flat();
+  let ignored = [];
+  let rule;
+  if (files.length) {
+    const result = git(['check-ignore', '-z', '--stdin'], files.join('\0') + '\0');
+    if (result.error || ![0, 1].includes(result.status)) return;
+    const matches = new Set(result.stdout.split('\0').filter(Boolean));
+    ignored = [...new Set(groups.flatMap((group) => {
+      const hidden = group.filter((file) => matches.has(file));
+      return hidden.length === group.length ? [] : hidden;
+    }))];
+    if (ignored.length) {
+      const verbose = git(['check-ignore', '-v', '-z', '--stdin'], ignored[0] + '\0');
+      if (verbose.error || verbose.status !== 0) return;
+      const [source, line, pattern] = verbose.stdout.split('\0');
+      rule = `${source}:${line}: ${pattern}`;
+    }
+  }
+  if (!pending.length && !ignored.length) return;
+  const quote = (name) => /^[a-zA-Z0-9_./-]+$/.test(name) ? name : `'${name.replace(/'/g, "'\\''")}'`;
+  log('Commit these changes for teammates and /devlyn-ideate drains to use them:', 'yellow');
+  if (ignored.length) log(`.gitignore hides ${ignored.length} installed files (${rule}).`, 'yellow');
+  const commands = [];
+  if (pending.length) commands.push(`git add -- ${pending.map(quote).join(' ')}`);
+  if (ignored.length) commands.push(`git add -f -- ${ignored.map(quote).join(' ')}`);
+  commands.push(`git commit -m "chore(devlyn): update devlyn-cli to ${PKG.version}"`);
+  log(`  ${commands.join(' && ')}`, 'dim');
+}
+
 // A devlyn install in a user root this run does not refresh drifts and can shadow the
 // project's copy; name it without touching it.
 function noticeGlobalDrift(installed) {
@@ -982,11 +1069,11 @@ async function init({ yes, claude, global }) {
   const scope = await singleSelect('Where', ['This project', 'Global — every project on this machine'], global ? 1 : 0);
   // Ask about optional addons (local skills + external packs; MCP servers belong to Claude Code)
   const selectedAddons = await multiSelect('Optional skills & packs', OPTIONAL_ADDONS.filter((addon) => addon.type !== 'mcp' || targets.includes('claude')));
-  const roots = install(targets, scope === 1, selectedAddons.filter((addon) => addon.type === 'local').map((addon) => addon.name));
+  install(targets, scope === 1, selectedAddons.filter((addon) => addon.type === 'local').map((addon) => addon.name));
 
   if (selectedAddons.length > 0) {
-    for (const addon of selectedAddons) {
-      installAddon(addon, roots);
+    for (const addon of selectedAddons.filter((addon) => addon.type !== 'local')) {
+      installAddon(addon);
     }
   } else {
     log('💡 No optional addons selected', 'dim');

package/bin/skill-ownership.js

@@ -52,15 +52,20 @@ function fingerprint(dir) {
   return crypto.createHash('sha256').update(JSON.stringify(entries)).digest('hex');
 }
 
+function gitEnvironment() {
+  const env = { ...process.env, LC_ALL: 'C' };
+  for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR',
+    'GIT_LITERAL_PATHSPECS', 'GIT_GLOB_PATHSPECS', 'GIT_NOGLOB_PATHSPECS', 'GIT_ICASE_PATHSPECS',
+    'GIT_CEILING_DIRECTORIES', 'GIT_DISCOVERY_ACROSS_FILESYSTEM']) delete env[key];
+  return env;
+}
+
 // Use the index, not status: even files deleted locally need ownership checks.
 // Inspect the repository containing this root, including global dotfiles repos.
 function trackedPaths(root) {
   let cwd = root;
   while (!fs.existsSync(cwd)) cwd = path.dirname(cwd);
-  const env = { ...process.env, LC_ALL: 'C' };
-  for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR',
-    'GIT_LITERAL_PATHSPECS', 'GIT_GLOB_PATHSPECS', 'GIT_NOGLOB_PATHSPECS', 'GIT_ICASE_PATHSPECS',
-    'GIT_CEILING_DIRECTORIES', 'GIT_DISCOVERY_ACROSS_FILESYSTEM']) delete env[key];
+  const env = gitEnvironment();
   const git = (args) => spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8', env });
   const repo = git(['rev-parse', '--show-toplevel']);
   if (repo.error?.code === 'ENOENT') return [];
@@ -76,4 +81,4 @@ function trackedPaths(root) {
   return files.stdout.split('\0').filter(Boolean).map((file) => path.resolve(repo.stdout.trim(), file));
 }
 
-module.exports = { contentHash, fingerprint, isIgnoredEntry, trackedPaths };
+module.exports = { contentHash, fingerprint, gitEnvironment, isIgnoredEntry, trackedPaths };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "4.2.7",
+  "version": "4.2.9",
   "description": "Loop & harness engineering for AI coding agents (Claude Code, Codex, and any AGENTS.md-driven agent) — core engineering principles for CLAUDE.md/AGENTS.md and a loop designer that splits one intent into tasks agents drain hands-free",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {