@stonepandastudio/cairn 0.4.1 → 0.4.2

package/README.md

@@ -170,4 +170,4 @@ schema.json            JSON Schema for cairn.config.json
 test/run.js            dependency-free test runner
 ```
 
-No runtime dependencies. Node >= 18. `npm test` runs 54 tests.
+No runtime dependencies. Node >= 18. `npm test` runs 56 tests.

package/lib/init.js

@@ -10,22 +10,25 @@ const {
   record,
   writeManifest,
   manifestPath,
+  hashContent,
 } = require('./manifest');
 const { listProviders } = require('./tracker');
 const { makePaint } = require('./paint');
 
 // `cairn init` — make a repo cairn-managed.
 //
-// It writes exactly three things:
+// It writes:
 //   cairn.config.json        hand-editable from here on; cairn never rewrites it
+//                            except with --force
 //   _cairn/scripts/jira.js   vendored shim, tracked in the manifest
 //   _cairn/manifest.json     the record of what was written
 //
-// Plus, when the repo still carries a copied ai/scripts/jira.js, that file is
-// replaced by a shim too. Replacing rather than deleting is deliberate: the five
-// repos have roughly forty prose references to that path, and breaking them all
-// in the same release that swaps the Jira client would make any failure
-// impossible to attribute.
+// Plus, for every copied client the repo still carries (jira.js / youtrack.js /
+// task-tracker.js under ai/scripts/), that file is replaced by the same shim —
+// replacing rather than deleting because dozens of prose references name the path
+// and the shim reads the same argv. A file already holding the shim is skipped; a
+// file hand-edited away from what cairn wrote is kept and reported unless
+// --force-shims. cairn never invents one of these paths in a repo that lacked it.
 
 const SHIM_SOURCE = 'shims/jira.js';
 const SHIM_TARGET = '_cairn/scripts/jira.js';
@@ -55,6 +58,8 @@ Usage: cairn init [options]
                            (only when the repo's app reads JIRA_*/YOUTRACK_* itself)
   --no-shim                do not vendor or replace the ai/scripts/*.js client shims
   --force                  overwrite an existing cairn.config.json
+  --force-shims            also replace an ai/scripts/*.js shim that was hand-edited
+                           since cairn wrote it (kept untouched otherwise)
   --dry-run                print what would be written, write nothing
 `;
 
@@ -69,6 +74,7 @@ function parseArgs(argv) {
     envPrefix: '',
     shim: true,
     force: false,
+    forceShims: false,
     dryRun: false,
     color: process.stdout.isTTY,
   };
@@ -83,6 +89,7 @@ function parseArgs(argv) {
     else if (a === '--env-prefix') args.envPrefix = argv[++i];
     else if (a === '--no-shim') args.shim = false;
     else if (a === '--force') args.force = true;
+    else if (a === '--force-shims') args.forceShims = args.force = true;
     else if (a === '--dry-run') args.dryRun = true;
     else if (a === '--no-color') args.color = false;
     else if (a === '-h' || a === '--help') args.help = true;
@@ -148,29 +155,52 @@ function main(argv = process.argv.slice(2)) {
     return 2;
   }
 
+  const manifest = readManifest(repoPath) || emptyManifest();
+
   const planned = [];
+  const kept = [];
   const config = buildConfig(args);
   planned.push([CONFIG_NAME, JSON.stringify(config, null, 2) + '\n', null]);
 
   const shim = readTemplate(SHIM_SOURCE);
   if (args.shim) {
     planned.push([SHIM_TARGET, shim, SHIM_SOURCE]);
-    // Only replace a legacy path if a copied client is actually there — creating
-    // one in a repo that never had it would invent a path nothing references.
+    // Replace a legacy client only where one is actually present. A file already
+    // holding the shim is left alone; one hand-edited away from what cairn wrote
+    // is kept unless --force — never silently overwrite an edit.
     for (const target of LEGACY_SHIM_TARGETS) {
-      if (fs.existsSync(path.join(repoPath, target))) {
-        planned.push([target, shim, SHIM_SOURCE]);
+      const abs = path.join(repoPath, target);
+      if (!fs.existsSync(abs)) continue;
+      const current = fs.readFileSync(abs, 'utf8');
+      const entry = manifest.files[target];
+
+      // Already the shim and already tracked — nothing to do. If it holds the
+      // shim but isn't in the manifest (someone copied it by hand), fall through
+      // so this run records it.
+      if (current === shim && entry) continue;
+
+      const modified = entry && hashContent(current) !== entry.hash;
+      if (modified && !args.forceShims) {
+        kept.push(target);
+        continue;
       }
+      const note =
+        current === shim ? 'recording existing shim' : entry ? null : `replacing ${current.split('\n').length} lines`;
+      planned.push([target, shim, SHIM_SOURCE, note]);
     }
   }
 
   if (args.dryRun) {
     console.log(paint.bold(`cairn init --dry-run  ${repoPath}`));
-    for (const [rel] of planned) console.log(`  would write  ${rel}`);
+    for (const [rel, , , note] of planned) {
+      console.log(`  would write  ${rel}${note ? paint.dim(`  (${note})`) : ''}`);
+    }
+    for (const rel of kept) {
+      console.log(paint.yellow(`  would keep   ${rel}  (hand-edited — pass --force-shims to replace)`));
+    }
     return 0;
   }
 
-  const manifest = readManifest(repoPath) || emptyManifest();
   for (const [rel, content, source] of planned) {
     const abs = path.join(repoPath, rel);
     fs.mkdirSync(path.dirname(abs), { recursive: true });
@@ -182,10 +212,14 @@ function main(argv = process.argv.slice(2)) {
   writeManifest(repoPath, manifest);
 
   console.log(paint.bold(`cairn init  ${repoPath}`));
-  for (const [rel, , source] of planned) {
-    console.log(`  ${paint.green('wrote')}  ${rel}${source ? paint.dim(`  (${source})`) : ''}`);
+  for (const [rel, , source, note] of planned) {
+    const tag = note || source;
+    console.log(`  ${paint.green('wrote')}  ${rel}${tag ? paint.dim(`  (${tag})`) : ''}`);
   }
   console.log(`  ${paint.green('wrote')}  ${path.relative(repoPath, manifestPath(repoPath)).replace(/\\/g, '/')}`);
+  for (const rel of kept) {
+    console.log(paint.yellow(`  kept   ${rel}  (hand-edited since cairn wrote it — pass --force-shims to replace)`));
+  }
 
   const gitignore = path.join(repoPath, '.gitignore');
   const hasIgnore = fs.existsSync(gitignore) && /^_cairn\b/m.test(fs.readFileSync(gitignore, 'utf8'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonepandastudio/cairn",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Shared AI workflow scaffolding for Stone Panda repos — issue tracker client and drift doctor.",
   "license": "UNLICENSED",
   "repository": {