@stonepandastudio/cairn 0.4.0 → 0.4.2

package/README.md

@@ -79,7 +79,9 @@ Credentials come from the repo's `.env` — `JIRA_BASE_URL` / `JIRA_USER` /
 `JIRA_PASSWORD` for `jira-server` (Basic auth: Jira Server 8.5.1 predates PATs), or
 `YOUTRACK_URL` / `YOUTRACK_TOKEN` / `YOUTRACK_PROJECT` for `youtrack` (Bearer token,
 admin-read scope for the project and stage-bundle lookups). Anything already in the
-environment wins over the file.
+environment wins over the file. If the repo's own app reads those same names, set
+`tracker.envPrefix` (`cairn init --env-prefix CAIRN_`) so cairn reads
+`CAIRN_YOUTRACK_TOKEN` instead — or point `tracker.env` at a separate file.
 
 ### Legacy command names
 
@@ -168,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 51 tests.
+No runtime dependencies. Node >= 18. `npm test` runs 56 tests.

package/lib/config.js

@@ -84,6 +84,10 @@ function normalizeTracker(tracker) {
   t.issueTypes = { story: 'Story', subtask: 'Sub-task', ...(t.issueTypes || {}) };
   t.statuses = { todo: 'To Do', inProgress: 'In Progress', done: 'Done', ...(t.statuses || {}) };
   t.env = t.env || '.env';
+  // Prepended to every credential var name the provider reads — set it when the
+  // repo's app talks to the same tracker with its own credentials and `JIRA_*` /
+  // `YOUTRACK_*` would collide. Empty by default.
+  t.envPrefix = t.envPrefix || '';
   return t;
 }
 

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';
@@ -49,10 +52,14 @@ Usage: cairn init [options]
   --stack <names>          comma-separated, framework first: nestjs,typeorm | angular | cli
   --tracker <provider>     ${listProviders().join(' | ')}   (default: none)
   --project-key <KEY>      tracker project key, e.g. PROOF
-  --story-type <name>      parent issue type  (default: Story)
-  --subtask-type <name>    child issue type   (default: Sub-task)
+  --story-type <name>      parent issue type  (default: Story, jira-server only)
+  --subtask-type <name>    child issue type   (default: Sub-task, jira-server only)
+  --env-prefix <PFX>       prefix for the tracker credential vars, e.g. CAIRN_
+                           (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
 `;
 
@@ -64,8 +71,10 @@ function parseArgs(argv) {
     projectKey: null,
     storyType: 'Story',
     subtaskType: 'Sub-task',
+    envPrefix: '',
     shim: true,
     force: false,
+    forceShims: false,
     dryRun: false,
     color: process.stdout.isTTY,
   };
@@ -77,8 +86,10 @@ function parseArgs(argv) {
     else if (a === '--project-key') args.projectKey = argv[++i];
     else if (a === '--story-type') args.storyType = argv[++i];
     else if (a === '--subtask-type') args.subtaskType = argv[++i];
+    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;
@@ -100,6 +111,7 @@ function buildConfig(args) {
   if (args.tracker !== 'none') {
     cfg.tracker.projectKey = args.projectKey;
     cfg.tracker.env = '.env';
+    if (args.envPrefix) cfg.tracker.envPrefix = args.envPrefix;
     // issueTypes is a Jira concept — YouTrack has no Task/Sub-task split.
     if (args.tracker === 'jira-server') {
       cfg.tracker.issueTypes = { story: args.storyType, subtask: args.subtaskType };
@@ -143,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 });
@@ -177,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'));
@@ -190,9 +229,8 @@ function main(argv = process.argv.slice(2)) {
     );
   }
   if (args.tracker !== 'none') {
-    console.log(
-      paint.dim(`\n  Next: ensure .env has JIRA_BASE_URL, JIRA_USER, JIRA_PASSWORD, then run`),
-    );
+    const envVars = require('./tracker').providerEnv(args.tracker, args.envPrefix);
+    console.log(paint.dim(`\n  Next: ensure .env has ${envVars.join(', ')}, then run`));
     console.log(paint.dim(`        npx cairn tracker list-statuses ${args.projectKey}`));
   }
   return 0;

package/lib/tracker/index.js

@@ -1,8 +1,10 @@
 'use strict';
 
 const { loadEnv, loadRepoConfig, findRepoRoot, ConfigError } = require('../config');
-const { createJiraServer, TrackerError, NoTransitionError } = require('./jira-server');
-const { createYouTrack } = require('./youtrack');
+const jiraServer = require('./jira-server');
+const youtrack = require('./youtrack');
+const { createJiraServer, TrackerError, NoTransitionError } = jiraServer;
+const { createYouTrack } = youtrack;
 const { createNone } = require('./none');
 
 // Provider registry. Adding Linear or GitHub Issues later means adding one entry
@@ -18,6 +20,18 @@ function listProviders() {
   return Object.keys(PROVIDERS);
 }
 
+// The .env variables a provider reads. `cairn init` prints these as the next step,
+// so a youtrack repo is not told to set JIRA_* and vice versa.
+const CREDENTIAL_ENV = {
+  'jira-server': jiraServer.CREDENTIAL_ENV,
+  youtrack: youtrack.CREDENTIAL_ENV,
+  none: [],
+};
+
+function providerEnv(name, prefix = '') {
+  return (CREDENTIAL_ENV[name] || []).map((v) => prefix + v);
+}
+
 // Build a tracker straight from a tracker config block plus an env bag.
 function createTracker(trackerConfig = {}, env = process.env) {
   const name = trackerConfig.provider || 'none';
@@ -48,6 +62,7 @@ module.exports = {
   createTracker,
   trackerForRepo,
   listProviders,
+  providerEnv,
   TrackerError,
   NoTransitionError,
 };

package/lib/tracker/jira-server.js

@@ -38,14 +38,15 @@ class NoTransitionError extends TrackerError {
 const REQUIRED_ENV = ['JIRA_BASE_URL', 'JIRA_USER', 'JIRA_PASSWORD'];
 
 function createJiraServer(config = {}, env = process.env) {
-  const baseUrl = (config.baseUrl || env.JIRA_BASE_URL || '').replace(/\/+$/, '');
-  const user = config.user || env.JIRA_USER;
-  const password = config.password || env.JIRA_PASSWORD;
+  const pfx = config.envPrefix || '';
+  const baseUrl = (config.baseUrl || env[pfx + 'JIRA_BASE_URL'] || '').replace(/\/+$/, '');
+  const user = config.user || env[pfx + 'JIRA_USER'];
+  const password = config.password || env[pfx + 'JIRA_PASSWORD'];
   const projectKey = config.projectKey;
   const issueTypes = { story: 'Story', subtask: 'Sub-task', ...(config.issueTypes || {}) };
 
   function assertConfig() {
-    const missing = REQUIRED_ENV.filter((k, i) => ![baseUrl, user, password][i]);
+    const missing = REQUIRED_ENV.filter((k, i) => ![baseUrl, user, password][i]).map((k) => pfx + k);
     if (missing.length) {
       throw new TrackerError(
         `Missing Jira credentials: ${missing.join(', ')}. Set them in the repo's .env or the environment.`,
@@ -322,4 +323,4 @@ function createJiraServer(config = {}, env = process.env) {
   };
 }
 
-module.exports = { createJiraServer, TrackerError, NoTransitionError };
+module.exports = { createJiraServer, TrackerError, NoTransitionError, CREDENTIAL_ENV: REQUIRED_ENV };

package/lib/tracker/youtrack.js

@@ -21,16 +21,20 @@
 const { TrackerError, NoTransitionError } = require('./jira-server');
 
 const REQUIRED_ENV = ['YOUTRACK_URL', 'YOUTRACK_TOKEN'];
+// What `cairn init` tells the user to put in .env — includes the project, which
+// the guard treats as optional only because it can also come from cairn.config.json.
+const CREDENTIAL_ENV = ['YOUTRACK_URL', 'YOUTRACK_TOKEN', 'YOUTRACK_PROJECT'];
 const STAGE_FIELD = 'Stage';
 const ASSIGNEE_FIELD = 'Assignee';
 
 function createYouTrack(config = {}, env = process.env) {
-  const baseUrl = (config.baseUrl || env.YOUTRACK_URL || '').replace(/\/+$/, '');
-  const token = config.token || env.YOUTRACK_TOKEN;
-  const projectKey = config.projectKey || env.YOUTRACK_PROJECT;
+  const pfx = config.envPrefix || '';
+  const baseUrl = (config.baseUrl || env[pfx + 'YOUTRACK_URL'] || '').replace(/\/+$/, '');
+  const token = config.token || env[pfx + 'YOUTRACK_TOKEN'];
+  const projectKey = config.projectKey || env[pfx + 'YOUTRACK_PROJECT'];
 
   function assertConfig() {
-    const missing = REQUIRED_ENV.filter((k, i) => ![baseUrl, token][i]);
+    const missing = REQUIRED_ENV.filter((k, i) => ![baseUrl, token][i]).map((k) => pfx + k);
     if (missing.length) {
       throw new TrackerError(
         `Missing YouTrack credentials: ${missing.join(', ')}. Set them in the repo's .env or the environment.`,
@@ -314,4 +318,4 @@ function createYouTrack(config = {}, env = process.env) {
   };
 }
 
-module.exports = { createYouTrack, TrackerError, NoTransitionError };
+module.exports = { createYouTrack, TrackerError, NoTransitionError, CREDENTIAL_ENV };

package/package.json

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

package/schema.json

@@ -51,6 +51,12 @@
           "type": "string",
           "default": ".env",
           "description": "Path, relative to the repo root, of the file holding tracker credentials."
+        },
+        "envPrefix": {
+          "type": "string",
+          "default": "",
+          "description": "Prepended to every credential var the provider reads (e.g. \"CAIRN_\" → CAIRN_YOUTRACK_TOKEN). Set it only when the repo's own app reads JIRA_*/YOUTRACK_* and the names would collide.",
+          "examples": ["CAIRN_"]
         }
       }
     },