@stonepandastudio/cairn 0.3.0 → 0.4.0

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
@@ -134,16 +134,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 +168,4 @@ schema.json            JSON Schema for cairn.config.json
 test/run.js            dependency-free test runner
 ```
 
-No runtime dependencies. Node >= 18. `npm test` runs 46 tests.
+No runtime dependencies. Node >= 18. `npm test` runs 51 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);
 }
@@ -110,6 +125,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 +158,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,
@@ -29,19 +29,29 @@ const { makePaint } = require('./paint');
 
 const SHIM_SOURCE = 'shims/jira.js';
 const SHIM_TARGET = '_cairn/scripts/jira.js';
-const LEGACY_SHIM_TARGET = 'ai/scripts/jira.js';
+
+// Copied tracker-client filenames seen across the repos. `cairn init` replaces
+// every one that exists with the shim — the snap-proof repos carry all three
+// (`task-tracker.js` dispatching to `jira.js` / `youtrack.js`), and the docs
+// that reference them by path keep working because the shim reads the same
+// argv. A repo that never had one is left alone; the shim is never invented.
+const LEGACY_SHIM_TARGETS = [
+  'ai/scripts/jira.js',
+  'ai/scripts/youtrack.js',
+  'ai/scripts/task-tracker.js',
+];
 
 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)
-  --no-shim                do not vendor the ai/scripts/jira.js compatibility shim
+  --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
 `;
@@ -84,7 +94,7 @@ 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') {
@@ -140,10 +150,12 @@ function main(argv = process.argv.slice(2)) {
   const shim = readTemplate(SHIM_SOURCE);
   if (args.shim) {
     planned.push([SHIM_TARGET, shim, SHIM_SOURCE]);
-    // Only replace the legacy path if a copied client is actually there. Creating
-    // it in a repo that never had one would invent a path nothing references.
-    if (fs.existsSync(path.join(repoPath, LEGACY_SHIM_TARGET))) {
-      planned.push([LEGACY_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.
+    for (const target of LEGACY_SHIM_TARGETS) {
+      if (fs.existsSync(path.join(repoPath, target))) {
+        planned.push([target, shim, SHIM_SOURCE]);
+      }
     }
   }
 
@@ -186,4 +198,4 @@ function main(argv = process.argv.slice(2)) {
   return 0;
 }
 
-module.exports = { main, buildConfig, HELP, SHIM_TARGET, LEGACY_SHIM_TARGET, cairnDir };
+module.exports = { main, buildConfig, HELP, SHIM_TARGET, LEGACY_SHIM_TARGETS, cairnDir };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonepandastudio/cairn",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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",