@stonepandastudio/cairn 0.3.1 → 0.4.1

package/README.md

@@ -12,7 +12,7 @@ agreeing.
 
 ```bash
 npm i -D @stonepandastudio/cairn
-npx cairn init --stack backend --tracker jira-server --project-key MYPROJ --story-type Task
+npx cairn init --stack nestjs,typeorm --tracker jira-server --project-key MYPROJ --story-type Task
 ```
 
 ## What v1 does
@@ -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
 
@@ -134,16 +136,17 @@ overwriting a hand edit is the destructive outcome.
 
 ### Workspace config (`repos.json`)
 
-- `repos[]` — name, path, stack. Per-repo settings live in each repo's own
-  `cairn.config.json`; the inline `vars` blocks are a fallback used only until a repo
-  has been through `cairn init`, so migration can happen one repo at a time.
+- `repos[]` — name, path, stack (`"angular"` or a list `["nestjs", "typeorm"]` —
+  framework first). Per-repo settings live in each repo's own `cairn.config.json`;
+  the inline `vars` blocks are a fallback used only until a repo has been through
+  `cairn init`, so migration can happen one repo at a time.
 - `pathAliases` — local → canonical. When one repo names a stub `execute-tests.md`
   where the others use `execute-test-plan.md`, aliasing folds them onto the cohort's
   names instead of reporting one `MISSING` and one `STRANDED` for the same file.
 - `shared[]` — glob rules. `cohort: "all"` compares every repo; `cohort: "stack"`
-  compares backend-with-backend. `requires: { tracker: true }` skips repos with no
-  tracker. A repo with no config has an *unknown* tracker, not an absent one, and is
-  never skipped on that basis.
+  groups by the first stack entry (all `nestjs` repos together, whatever the ORM).
+  `requires: { tracker: true }` skips repos with no tracker. A repo with no config
+  has an *unknown* tracker, not an absent one, and is never skipped on that basis.
 - Anything not matched by a rule — `ai/contexts/`, `ai/progress/`, `ai/tasks/`,
   `DATABASE_SCHEMA.md` — is per-project by design and never inspected.
   `ai/INITIAL_PROMPT.md` is explicitly excluded: variants at ~0% shared content make
@@ -167,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 47 tests.
+No runtime dependencies. Node >= 18. `npm test` runs 54 tests.

package/lib/config.js

@@ -13,7 +13,7 @@ const CAIRN_DIR = '_cairn';
 // generated directory from slowly acquiring hand-maintained state.
 
 const DEFAULTS = {
-  stack: 'unknown',
+  stack: ['unknown'],
   tracker: { provider: 'none' },
   agents: {},
   vars: {},
@@ -21,6 +21,21 @@ const DEFAULTS = {
 
 class ConfigError extends Error {}
 
+// `stack` is a list — the framework first, then composable add-ons
+// (`["nestjs", "typeorm"]`). A bare string or a comma-separated string is
+// accepted and normalized. The doctor's `cohort: "stack"` groups by the first
+// entry; the v2 renderer layers a preset per entry, in order.
+function normalizeStack(value) {
+  if (Array.isArray(value)) {
+    const list = value.map((s) => String(s).trim()).filter(Boolean);
+    return list.length ? list : ['unknown'];
+  }
+  if (typeof value === 'string' && value.trim()) {
+    return value.split(',').map((s) => s.trim()).filter(Boolean);
+  }
+  return ['unknown'];
+}
+
 function configPath(repoPath) {
   return path.join(repoPath, CONFIG_NAME);
 }
@@ -69,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;
 }
 
@@ -110,6 +129,7 @@ function loadRepoConfig(repoPath, { fallbackVars = null, required = false } = {}
   const cfg = {
     ...DEFAULTS,
     ...raw,
+    stack: normalizeStack(raw.stack),
     tracker: normalizeTracker(raw.tracker),
     agents: raw.agents || {},
     vars: raw.vars || fallbackVars || {},
@@ -142,5 +162,6 @@ module.exports = {
   findRepoRoot,
   loadEnv,
   loadRepoConfig,
+  normalizeStack,
   parseEnv,
 };

package/lib/doctor/index.js

@@ -20,7 +20,7 @@ const { matchRule, readFile } = require('./scan');
 const { buildNormalizer } = require('./normalize');
 const diff = require('./diff');
 const { makePaint, stripAnsi, table } = require('../paint');
-const { loadRepoConfig } = require('../config');
+const { loadRepoConfig, normalizeStack } = require('../config');
 const { readManifest, statusFor } = require('../manifest');
 
 function hash(s) {
@@ -55,7 +55,8 @@ function resolveRepos(config, configDir) {
     return {
       name: entry.name,
       path: repoPath.replace(/\\/g, '/'),
-      stack: entry.stack || repoConfig.stack,
+      // A list — framework first, then add-ons. `cohort: "stack"` groups by [0].
+      stack: normalizeStack(entry.stack || repoConfig.stack),
       vars: { ...(repoConfig.vars || {}), ...(entry.vars || {}) },
       tracker: repoConfig.tracker,
       managed: !repoConfig.unmanaged,
@@ -72,7 +73,9 @@ function cohortGroups(rule, repos) {
   if (rule.cohort === 'stack') {
     const byStack = new Map();
     for (const repo of repos) {
-      const key = repo.stack || 'unknown';
+      // Compare at framework granularity — the shared contracts live there, and
+      // ORM/add-on differences are resolved by composing presets, not by cohort.
+      const key = (repo.stack && repo.stack[0]) || 'unknown';
       if (!byStack.has(key)) byStack.set(key, []);
       byStack.get(key).push(repo);
     }
@@ -94,7 +97,7 @@ function repoMeetsRequirements(repo, rule) {
   if (req.tracker === true && repo.managed && (!repo.tracker || repo.tracker.provider === 'none')) {
     return false;
   }
-  if (req.stack && repo.stack !== req.stack) return false;
+  if (req.stack && !(repo.stack || []).includes(req.stack)) return false;
   return true;
 }
 
@@ -514,4 +517,4 @@ function main(argv = process.argv.slice(2)) {
   return 0;
 }
 
-module.exports = { main, analyze, analyzeManaged, resolveRepos, render, HELP, stripAnsi };
+module.exports = { main, analyze, analyzeManaged, resolveRepos, cohortGroups, render, HELP, stripAnsi };

package/lib/init.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const { CONFIG_NAME, configPath, cairnDir } = require('./config');
+const { CONFIG_NAME, configPath, cairnDir, normalizeStack } = require('./config');
 const {
   emptyManifest,
   readManifest,
@@ -46,11 +46,13 @@ const HELP = `cairn init — make a repo cairn-managed
 Usage: cairn init [options]
 
   --repo <path>            repo to initialise (default: cwd)
-  --stack <name>           backend | frontend | cli | ...   (default: unknown)
+  --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
   --dry-run                print what would be written, write nothing
@@ -64,6 +66,7 @@ function parseArgs(argv) {
     projectKey: null,
     storyType: 'Story',
     subtaskType: 'Sub-task',
+    envPrefix: '',
     shim: true,
     force: false,
     dryRun: false,
@@ -77,6 +80,7 @@ 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 === '--dry-run') args.dryRun = true;
@@ -94,12 +98,13 @@ function buildConfig(args) {
   const cfg = {
     $schema: `./node_modules/${require('../package.json').name}/schema.json`,
     cairn: require('../package.json').version,
-    stack: args.stack,
+    stack: normalizeStack(args.stack),
     tracker: { provider: args.tracker },
   };
   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 };
@@ -190,9 +195,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.3.1",
+  "version": "0.4.1",
   "description": "Shared AI workflow scaffolding for Stone Panda repos — issue tracker client and drift doctor.",
   "license": "UNLICENSED",
   "repository": {

package/schema.json

@@ -12,9 +12,12 @@
       "description": "Version of @stonepandastudio/cairn this repo is pinned to."
     },
     "stack": {
-      "type": "string",
-      "description": "Comparison cohort for the doctor and, from v2, the preset to render from.",
-      "examples": ["backend", "frontend", "cli"]
+      "description": "Framework first, then composable add-ons. `cohort: \"stack\"` in the doctor groups by the first entry; the v2 renderer layers one preset per entry, in order. A bare or comma-separated string is also accepted.",
+      "anyOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+      ],
+      "examples": ["angular", ["nestjs", "typeorm"], "cli"]
     },
     "tracker": {
       "type": "object",
@@ -48,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_"]
         }
       }
     },