@futurelastic/colab-handbook 1.12.0-rc.18 → 1.12.0-rc.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.18"
30
+ "version": "1.12.0-rc.19"
31
31
  }
package/tools/colab CHANGED
@@ -7293,6 +7293,7 @@ const HELP_ADOPT = `colab adopt [--repo <path>] [--json] [--no-verify] [--axis a
7293
7293
  [--writes <free|direct|isolated>] [--channels <c1,c2,...>]
7294
7294
  [--production <url>|none] [--deploy <push-main|tag|manual|none>]
7295
7295
  [--stack "<text>"] [--answered-by <name>] [--reason "<text>"]
7296
+ [--fork | --no-fork]
7296
7297
 
7297
7298
  Detects what a repo already states in .github/project.yml, ASKS a human only what could not be
7298
7299
  detected (flags, or a forced multiple-choice menu at a TTY — every row is a numbered choice,
@@ -7314,6 +7315,14 @@ accepted and reads as free — no adopter's descriptor breaks, and none is re-as
7314
7315
  --answered-by N who is answering, alongside COLAB_HUMAN=1 (see THE HUMAN GATE below)
7315
7316
  --reason "..." required alongside a lowered or evidence-contradicted exposure answer;
7316
7317
  written into the file, next to the key it justifies
7318
+ --fork / --no-fork
7319
+ a repo you own that tracks an upstream you don't (#449) is DETECTED — a
7320
+ remote named \`upstream\` whose URL differs from origin's. Assert it with
7321
+ --fork when the upstream remote is named otherwise; deny it with --no-fork.
7322
+ On a fork, step 5 of the remaining list is the append-only Conventions block
7323
+ (never the thin-shell conversion), the upstream's own agent workflow is
7324
+ named, and a new CLAUDE.md gets no AGENTS.md stub (CONVENTIONS.md §9,
7325
+ "A fork of an upstream")
7317
7326
 
7318
7327
  Any answer flag (--room/--exposure/--writes/--channels/--production/--deploy/--stack) makes the
7319
7328
  whole run NON-INTERACTIVE — it never half-prompts. With no answer flags and no TTY, and something
@@ -7442,7 +7451,7 @@ const ADOPT_ROW_ORDER = ['tier', 'room', 'exposure', 'writes', 'channels'];
7442
7451
  * read from a remote's HEAD, and the report says so (`detected.trunk.source`), never presented
7443
7452
  * as though it were.
7444
7453
  */
7445
- function adoptGitExtras(repoAbs) {
7454
+ function adoptGitExtras(repoAbs, opts = {}) {
7446
7455
  let trunk = git.detectTrunk(repoAbs);
7447
7456
  let trunkSource = trunk ? 'origin-head' : null;
7448
7457
  if (!trunk) {
@@ -7456,7 +7465,26 @@ function adoptGitExtras(repoAbs) {
7456
7465
  const hooksPath = hp.ok && hp.stdout ? hp.stdout : null;
7457
7466
  let hooksDirFiles = [];
7458
7467
  try { hooksDirFiles = fs.readdirSync(path.join(repoAbs, '.githooks')); } catch (_) { /* absent */ }
7459
- return { trunk, trunkSource, hooksPath, hooksDirFiles };
7468
+ // #449: `git ls-files` for the migrations candidate scan (adopt never asks `migrations:`).
7469
+ const ls = git.git(['ls-files'], repoAbs);
7470
+ const trackedFiles = ls.ok ? ls.stdout.split('\n').filter(Boolean) : undefined;
7471
+ return { trunk, trunkSource, hooksPath, hooksDirFiles, trackedFiles, fork: adoptDetectFork(repoAbs, opts) };
7472
+ }
7473
+
7474
+ /**
7475
+ * #449 — is this a repo you own that tracks an upstream you don't? DETECTED, never asked (§9):
7476
+ * a remote named `upstream` whose URL differs from origin's (the conventional name for the repo a
7477
+ * fork tracks). `--fork` asserts it when the upstream remote is named otherwise; `--no-fork`
7478
+ * denies it when a remote named `upstream` means something else. Returns null when not a fork.
7479
+ */
7480
+ function adoptDetectFork(repoAbs, opts = {}) {
7481
+ if (opts.noFork) return null;
7482
+ const up = git.git(['remote', 'get-url', 'upstream'], repoAbs);
7483
+ const origin = git.git(['remote', 'get-url', 'origin'], repoAbs);
7484
+ const upUrl = up.ok && up.stdout ? up.stdout : null;
7485
+ if (upUrl && !(origin.ok && origin.stdout === upUrl)) return { remote: 'upstream', url: upUrl, source: opts.fork ? 'flag' : 'upstream-remote' };
7486
+ if (opts.fork) return { remote: null, url: null, source: 'flag' };
7487
+ return null;
7460
7488
  }
7461
7489
 
7462
7490
  /** The `{ readFile, listDir, tags }` adapter tools/lib/adopt.js asks for — matching the local
@@ -7693,6 +7721,7 @@ function printAdoptReport(report, repoAbs, verify, localFinish) {
7693
7721
  print(`detected trunk: ${t.detected || '(unknown)'}${trunkSourceNote}${t.declared !== null ? ` (declared: ${t.declared}${t.agree === false ? ' ⚠ disagrees with detected' : ''})` : ''}`);
7694
7722
  print(`stack candidates: ${report.detected.stackCandidates.length ? report.detected.stackCandidates.join(', ') : '(none found)'}`);
7695
7723
  print(`declared ports: ${fmtVal(report.detected.ports)}`);
7724
+ if (report.fork) print(`fork of an upstream: yes — ${report.fork.source === 'flag' ? '--fork' : `remote "${report.fork.remote}" ${report.fork.url}`} (step 5 is the append-only block, §9 "A fork of an upstream")`);
7696
7725
  print(`legacy tier letter, derived from (production, deploy): ${report.legacyTierLetter ?? '(undetermined — production is set but deploy matches none of push-main/tag/manual)'}`);
7697
7726
  print('');
7698
7727
  print('Derived consequences:');
@@ -7892,9 +7921,10 @@ async function cmdAdopt(argv) {
7892
7921
  '--deploy': 'deploy', '--stack': 'stack', '--answered-by': 'answeredBy', '--reason': 'reason',
7893
7922
  '--trunk': 'trunk',
7894
7923
  },
7895
- flags: { '--json': 'json', '--no-verify': 'noVerify', '--local': 'local', '--no-labels': 'noLabels', '-h': 'help', '--help': 'help' },
7924
+ flags: { '--json': 'json', '--no-verify': 'noVerify', '--local': 'local', '--no-labels': 'noLabels', '--fork': 'fork', '--no-fork': 'noFork', '-h': 'help', '--help': 'help' },
7896
7925
  });
7897
7926
  if (opts.help) return print(HELP_ADOPT);
7927
+ if (opts.fork && opts.noFork) throw new UserError('--fork and --no-fork contradict each other — pass one');
7898
7928
  if (opts.trunk !== undefined && !opts.local) {
7899
7929
  throw new UserError('--trunk only means something with --local — on an ordinary adoption trunk is DETECTED, never asked (CONVENTIONS.md §9)');
7900
7930
  }
@@ -7910,7 +7940,7 @@ async function cmdAdopt(argv) {
7910
7940
  if (local.exit !== undefined) return local.exit;
7911
7941
  }
7912
7942
  const io = adoptIo(repoAbs);
7913
- const extra = adoptGitExtras(repoAbs);
7943
+ const extra = adoptGitExtras(repoAbs, opts);
7914
7944
  if (local) { extra.trunk = local.trunk; extra.trunkSource = 'local-integration'; }
7915
7945
  const report = adopt.detect(io, extra);
7916
7946
  const cfg = report.cfg;
@@ -8179,7 +8209,7 @@ async function cmdAdopt(argv) {
8179
8209
  fs.mkdirSync(path.dirname(descriptorFile), { recursive: true });
8180
8210
  fs.writeFileSync(descriptorFile, newText);
8181
8211
 
8182
- const afterExtra = adoptGitExtras(repoAbs);
8212
+ const afterExtra = adoptGitExtras(repoAbs, opts);
8183
8213
  if (local) { afterExtra.trunk = local.trunk; afterExtra.trunkSource = 'local-integration'; }
8184
8214
  const after = adopt.detect(adoptIo(repoAbs), afterExtra);
8185
8215
  // #417: a NEW repo (no descriptor before this run, plain adopt) gets the thin-shell CLAUDE.md
@@ -8194,7 +8224,8 @@ async function cmdAdopt(argv) {
8194
8224
  }
8195
8225
  for (const e of entries) print(`✓ wrote ${e.key}: ${fmtVal(e.value)}`);
8196
8226
  if (shell) {
8197
- if (shell.claude === 'written') print('✓ wrote CLAUDE.md — the thin shell: @AGENTS.md + the Conventions block (§9 step 5, #417)');
8227
+ if (shell.claude === 'written' && shell.fork) print('✓ wrote CLAUDE.md — the Conventions block alone: a fork with no upstream AGENTS.md gets no stub (§9 "A fork of an upstream", #449)');
8228
+ else if (shell.claude === 'written') print('✓ wrote CLAUDE.md — the thin shell: @AGENTS.md + the Conventions block (§9 step 5, #417)');
8198
8229
  else if (shell.claude === 'skipped') print(`· CLAUDE.md not written — ${shell.reason}`);
8199
8230
  if (shell.agents === 'written') print('✓ wrote AGENTS.md — a stub; the repo\'s own instructions go here');
8200
8231
  }
@@ -8230,6 +8261,14 @@ function adoptWriteShell(repoAbs, after) {
8230
8261
  const version = handbookVersion(root);
8231
8262
  const atTag = version === 'v0' ? null : stamp.gitIn(root, ['show', `${version}:templates/repo-CLAUDE-block.md`]);
8232
8263
  const blockText = atTag && atTag.ok && atTag.out ? atTag.out : fs.readFileSync(blockFile, 'utf8');
8264
+ // #449: on a fork, every file adopt creates is one the upstream may add later — a merge conflict
8265
+ // forever after. So no AGENTS.md stub there: with the upstream's own AGENTS.md the shell imports
8266
+ // it, without one CLAUDE.md is the block alone.
8267
+ const forkNoAgents = !!(after && after.fork) && !fs.existsSync(agentsAbs);
8268
+ if (forkNoAgents) {
8269
+ fs.writeFileSync(claudeAbs, adopt.renderClaudeShell(blockText, { version, trunk, tier, importAgents: false }));
8270
+ return { claude: 'written', agents: null, fork: true };
8271
+ }
8233
8272
  fs.writeFileSync(claudeAbs, adopt.renderClaudeShell(blockText, { version, trunk, tier }));
8234
8273
  let agents = 'exists';
8235
8274
  if (!fs.existsSync(agentsAbs)) { fs.writeFileSync(agentsAbs, adopt.renderAgentsStub()); agents = 'written'; }
@@ -18,7 +18,8 @@
18
18
  * listDir(relPath) -> string[] non-recursive listing, [] if unreadable/absent
19
19
  * tags() -> string[] | null every git tag, or null if undeterminable
20
20
  *
21
- * Git facts that are NOT plain file reads (trunk, `core.hooksPath`) are passed in separately via
21
+ * Git facts that are NOT plain file reads (trunk, `core.hooksPath`, the fork remote and `git ls-files`
22
+ * for #449) are passed in separately via
22
23
  * `extra`, rather than folded into `io` — `detectTrunk()` already lives in `tools/lib/git.js` and
23
24
  * belongs to the CLI layer, not duplicated here.
24
25
  *
@@ -210,22 +211,108 @@ function deriveConsequences({ exposure, writes, room }) {
210
211
 
211
212
  // ---------------------------------------------------------------------- §9 remainder checklist
212
213
 
214
+ const migrationPaths = require('./migration-paths.js');
215
+
213
216
  /**
214
- * §9's steps 3-9, unconditionally — this commit never performs any of them (Boundary, #199's
215
- * plan: "adopt writes the descriptor and nothing else"), so the remainder is the same regardless
216
- * of what the descriptor already states. Handed back as data, not prose, so a caller (a report
217
- * printer, or a future `handbook-sync` call site) does not grow its own paraphrase of these steps.
217
+ * #449 — the agent workflow an upstream ships inside the fork: entries under `.claude/skills/`
218
+ * and `.claude/commands/`, plus a committed `AGENTS.md`. Upstream-owned files compete with the
219
+ * `code-*` skills, and deleting or editing them is a fork patch that conflicts on every upstream
220
+ * merge — so adopt only NAMES them, for the precedence line the appended block carries.
218
221
  */
219
- function remainingSteps() {
220
- return [
221
- { n: 3, text: 'Create the full label set (13 names) — `colab labels --ensure`, CONVENTIONS.md §9 step 3 (#206)' },
222
+ function detectUpstreamAgentFiles(io) {
223
+ const out = [];
224
+ for (const dir of ['.claude/skills', '.claude/commands']) {
225
+ for (const e of io.listDir(dir).slice().sort()) {
226
+ if (e.startsWith('.')) continue;
227
+ out.push(`${dir}/${e}`);
228
+ }
229
+ }
230
+ return out;
231
+ }
232
+
233
+ /**
234
+ * #449 — where this repo's migrations might live, beyond what `migrations:` and the two defaults
235
+ * already cover. Two heuristics over `git ls-files`, both CANDIDATES for a human, never written:
236
+ * a `migrations/` directory nothing covers (the audit's own rule, `undeclaredMigrationDirs`), and
237
+ * a directory holding tracked `*.sql` files nothing covers (a fork whose upstream keeps them in
238
+ * `modules/<name>/sql/` — measured: the no-new-migrations gate was blind there). The `.sql` rule
239
+ * over-reports seeds and fixtures on purpose: a false candidate costs a glance, a missed layout
240
+ * leaves a human-only gate seeing nothing.
241
+ */
242
+ function detectMigrationCandidates(cfg, trackedFiles) {
243
+ const parsed = migrationPaths.parseMigrationPaths(cfg);
244
+ const declared = parsed.paths;
245
+ const files = trackedFiles || [];
246
+ const dirs = new Set(migrationPaths.undeclaredMigrationDirs(files, declared));
247
+ for (const file of files) {
248
+ if (!/\.sql$/i.test(file)) continue;
249
+ const segs = String(file).split('/');
250
+ if (segs.length < 2) continue; // a root-level .sql is not a layout
251
+ if (segs.some((s) => s === 'node_modules' || s === 'vendor')) continue;
252
+ if (migrationPaths.isMigrationPath(file, declared)) continue;
253
+ const dir = `${segs.slice(0, -1).join('/')}/`;
254
+ if ([...dirs].some((d) => dir.startsWith(d))) continue;
255
+ dirs.add(dir);
256
+ }
257
+ return { declared: parsed.declared ? declared : null, candidates: [...dirs].sort() };
258
+ }
259
+
260
+ const MIGRATION_CANDIDATES_SHOWN = 6;
261
+
262
+ /** The step-2 remainder line about `migrations:` — adopt never asks it, so it always reports it. */
263
+ function migrationsStepText(m) {
264
+ const tail = 'project.schema.md `migrations`; `colab adopt` does not ask it, step 2';
265
+ if (m && m.declared && m.declared.length) {
266
+ const extra = m.candidates.length ? ` — still uncovered, check: ${listShort(m.candidates)}` : '';
267
+ return `\`migrations:\` declared (${m.declared.join(', ')})${extra} — ${tail}`;
268
+ }
269
+ if (m && m.candidates.length) {
270
+ return `Declare \`migrations:\` in .github/project.yml — candidate layouts outside database/migrations/ and prisma/migrations/: ${listShort(m.candidates)}. Until declared, the no-new-migrations gate cannot see them — ${tail}`;
271
+ }
272
+ return `Declare \`migrations:\` in .github/project.yml if this repo keeps migrations anywhere but database/migrations/ or prisma/migrations/ (none detected) — ${tail}`;
273
+ }
274
+
275
+ function listShort(items) {
276
+ const shown = items.slice(0, MIGRATION_CANDIDATES_SHOWN).join(', ');
277
+ return items.length > MIGRATION_CANDIDATES_SHOWN ? `${shown} (+${items.length - MIGRATION_CANDIDATES_SHOWN} more)` : shown;
278
+ }
279
+
280
+ /**
281
+ * §9's remainder, as data, not prose, so a caller (a report printer, or a future `handbook-sync`
282
+ * call site) does not grow its own paraphrase of these steps. Adopt writes the descriptor and
283
+ * nothing else (Boundary, #199's plan), so steps 3-9 are always listed.
284
+ *
285
+ * `ctx` (all optional, #449):
286
+ * migrations — `detectMigrationCandidates()`'s result; adds the step-2 `migrations:` line
287
+ * (absent ctx = the pre-#449 list, steps 3-9 only)
288
+ * fork — `{ remote, url, source }` when this repo tracks an upstream it does not own:
289
+ * step 5 becomes the append-only block instead of the thin-shell conversion
290
+ * (CONVENTIONS.md §9, *A fork of an upstream*)
291
+ * upstreamAgentFiles — on a fork, the upstream's own agent workflow, named for the precedence line
292
+ */
293
+ function remainingSteps(ctx = {}) {
294
+ const steps = [];
295
+ if (ctx.migrations) steps.push({ n: 2, text: migrationsStepText(ctx.migrations) });
296
+ steps.push(
297
+ { n: 3, text: 'Create the full label set (21 names) — `colab labels --ensure`, CONVENTIONS.md §9 step 3 (#206)' },
222
298
  { n: 4, text: 'Add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4' },
223
- { n: 5, text: 'Make CLAUDE.md the thin shell — `@AGENTS.md` plus templates/repo-CLAUDE-block.md, repo prose in AGENTS.md (adopt writes both on a new repo, #417), step 5' },
299
+ );
300
+ if (ctx.fork) {
301
+ steps.push({ n: 5, text: `Fork of an upstream (${ctx.fork.source === 'flag' ? '--fork' : `remote "${ctx.fork.remote}"`}): do NOT make CLAUDE.md the thin shell — append templates/repo-CLAUDE-block.md at the END of the upstream's CLAUDE.md (create it only if upstream has none), record that append as a fork patch, leave AGENTS.md and the upstream prose untouched; CONVENTIONS.md §9 "A fork of an upstream", step 5` });
302
+ const agentFiles = ctx.upstreamAgentFiles || [];
303
+ if (agentFiles.length) {
304
+ steps.push({ n: 5, text: `Upstream ships its own agent workflow (${listShort(agentFiles)}): leave it in place, and say in the appended block that fork work runs code-start → code-wrap → code-ship, not that workflow — §9 "A fork of an upstream", step 5` });
305
+ }
306
+ } else {
307
+ steps.push({ n: 5, text: 'Make CLAUDE.md the thin shell — `@AGENTS.md` plus templates/repo-CLAUDE-block.md, repo prose in AGENTS.md (adopt writes both on a new repo, #417), step 5' });
308
+ }
309
+ steps.push(
224
310
  { n: 6, text: "Make sure CI meets §7's outcome — `colab template <name>`, step 6" },
225
311
  { n: 7, text: 'Register the repo — `colab register`, step 7' },
226
312
  { n: 8, text: 'Leave existing branches alone — nothing to do, step 8' },
227
313
  { n: 9, text: 'Do not create `dev` unless genuinely Tier A or Tier C — nothing to do, step 9' },
228
- ];
314
+ );
315
+ return steps;
229
316
  }
230
317
 
231
318
  // ---------------------------------------------------------------------- row state
@@ -321,6 +408,16 @@ function detect(io, extra = {}) {
321
408
  // from a remote's HEAD — tools/colab's adoptGitExtras() is the only place that computes it.
322
409
  const trunkSource = (extra && extra.trunkSource) || null;
323
410
 
411
+ // #449: a repo you own that tracks an upstream you don't. The CLI detects it (a remote named
412
+ // `upstream` whose URL differs from origin's) or takes `--fork`/`--no-fork`; null = not a fork.
413
+ const fork = (extra && extra.fork) || null;
414
+ const upstreamAgentFiles = fork ? detectUpstreamAgentFiles(io) : [];
415
+ // Only when the CLI handed over `git ls-files` — a pure-io caller without it gets no step-2 line
416
+ // rather than a false "none detected".
417
+ const migrations = extra && Array.isArray(extra.trackedFiles)
418
+ ? detectMigrationCandidates(cfg, extra.trackedFiles)
419
+ : null;
420
+
324
421
  return {
325
422
  descriptorExists: io.readFile('.github/project.yml') !== null,
326
423
  cfg,
@@ -335,7 +432,10 @@ function detect(io, extra = {}) {
335
432
  },
336
433
  legacyTierLetter,
337
434
  consequences,
338
- remaining: remainingSteps(),
435
+ fork,
436
+ upstreamAgentFiles,
437
+ migrations,
438
+ remaining: remainingSteps({ migrations, fork, upstreamAgentFiles }),
339
439
  };
340
440
  }
341
441
 
@@ -822,7 +922,7 @@ function renderDescriptor(rawText, entries) {
822
922
  * `tier` may be null (a shape with no legacy letter): the placeholder is then left for a human,
823
923
  * never guessed — the same rule deriveTier itself follows.
824
924
  */
825
- function renderClaudeShell(blockTemplate, { version, trunk, tier }) {
925
+ function renderClaudeShell(blockTemplate, { version, trunk, tier, importAgents = true }) {
826
926
  let block = String(blockTemplate).replace(/^\s*<!--[\s\S]*?-->\s*/, ''); // the paste note
827
927
  block = block.replace('<!-- colab-handbook @ <version> -->', `<!-- colab-handbook @ ${version} -->`);
828
928
  if (trunk) {
@@ -834,7 +934,10 @@ function renderClaudeShell(blockTemplate, { version, trunk, tier }) {
834
934
  // `<A = … · C = … · B = …>` → the one gloss that applies.
835
935
  block = block.replace(/<A = ([^·>]+?) · C = ([^·>]+?) · B = ([^>]+?)>/, (m, a, c, b) => ({ A: a, B: b, C: c })[tier] || m);
836
936
  }
837
- return `@AGENTS.md\n\n${block.replace(/\s*$/, '\n')}`;
937
+ // #449: a fork with no upstream AGENTS.md gets the block alone — no import of a file adopt
938
+ // must not create there.
939
+ const body = block.replace(/\s*$/, '\n');
940
+ return importAgents ? `@AGENTS.md\n\n${body}` : body;
838
941
  }
839
942
 
840
943
  /** The AGENTS.md stub written beside a new shell, only when no AGENTS.md exists. */
@@ -859,6 +962,8 @@ module.exports = {
859
962
  deriveTier,
860
963
  deriveConsequences,
861
964
  remainingSteps,
965
+ detectUpstreamAgentFiles,
966
+ detectMigrationCandidates,
862
967
  detect,
863
968
  // commit 2
864
969
  VALID_ROOM,