@antelopejs/tooling-configs 0.4.1 → 0.5.1

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.
Files changed (41) hide show
  1. package/README.md +68 -29
  2. package/dist/bin/api-diff.mjs +235 -37
  3. package/dist/bin/body-check.mjs +14 -11
  4. package/dist/bin/capture.mjs +173 -54
  5. package/dist/bin/check-size.mjs +1 -1
  6. package/dist/bin/checks.mjs +166 -11
  7. package/dist/bin/comment-proof.mjs +29 -7
  8. package/dist/bin/garden.mjs +8 -58
  9. package/dist/bin/lease.mjs +48 -11
  10. package/dist/bin/ratchet.mjs +48 -14
  11. package/dist/bin/suppressions.mjs +3 -3
  12. package/dist/bin/sync.mjs +199 -80
  13. package/dist/bin/verify.mjs +1163 -474
  14. package/dist/capture/index.d.mts +6 -1
  15. package/dist/capture/index.mjs +1 -1
  16. package/dist/{ci-workflow-37qJa9LX.mjs → ci-workflow-COJUT12b.mjs} +121 -1
  17. package/dist/eslint.d.mts +16 -3
  18. package/dist/eslint.mjs +21 -6
  19. package/dist/formal/index.d.mts +20 -4
  20. package/dist/formal/index.mjs +71 -19
  21. package/dist/{map-B23_WMGE.mjs → map-DRyYz_Fw.mjs} +20 -1
  22. package/dist/oxc/anti-slop/index.mjs +156 -421
  23. package/dist/oxc/guardrails/index.d.mts +1 -1
  24. package/dist/oxc/guardrails/index.mjs +789 -103
  25. package/dist/oxc/lint.d.mts +13 -15
  26. package/dist/oxc/lint.mjs +19 -29
  27. package/dist/{package-CqqBgE8Y.mjs → package-Dn7VTFUW.mjs} +71 -17
  28. package/dist/{proof-stamp-DDDC0J6l.mjs → proof-stamp-DLWpPwQE.mjs} +72 -10
  29. package/dist/{ratchet-Q-JXuZIX.mjs → ratchet-ClfblHNJ.mjs} +18 -15
  30. package/dist/require-safety-comment-for-type-assertion-mnb0CIxa.mjs +181 -0
  31. package/dist/{scenes-DZVXkcxS.mjs → scenes-d-VQ0LOm.mjs} +4 -1
  32. package/dist/semver-BDxeEcP_.mjs +57 -0
  33. package/dist/{suppression-base-9L8dlMQK.mjs → suppression-base-Drnl6Y7F.mjs} +2 -2
  34. package/dist/{suppression-budget-C0SkPO5R.mjs → suppression-budget-Dvb_IqBo.mjs} +1 -1
  35. package/dist/{suppressions-DM60NkvL.mjs → suppressions-BroaaGJ_.mjs} +1 -1
  36. package/dist/{templates-BKZv-BRw.mjs → templates-lJBZFskp.mjs} +8 -3
  37. package/dist/type-aware-rules-DMuN6sHb.mjs +30 -0
  38. package/dist/{typescript-DAgQIAAR.mjs → typescript-BBbry7uU.mjs} +123 -27
  39. package/dist/verify/index.d.mts +60 -15
  40. package/package.json +3 -1
  41. package/dist/require-safety-comment-for-type-assertion-BBQ669kj.mjs +0 -83
package/dist/bin/sync.mjs CHANGED
@@ -1,16 +1,16 @@
1
1
  #!/usr/bin/env node
2
2
  import { a as formatCeilings, l as readCeilings, s as isRetired, t as CEILINGS_FILE } from "../ceilings-B7KayYIG.mjs";
3
- import { a as repositoryTools, i as parseManifest, n as managedPackage, o as templatePackage, r as packageManager, s as toolingVersions } from "../package-CqqBgE8Y.mjs";
4
- import { i as presetConfig, n as SETUP_SCRIPT, r as lefthook, t as PRESET_CONFIGS } from "../templates-BKZv-BRw.mjs";
3
+ import { a as parseManifest, c as toolingVersions, i as packageManager, o as repositoryTools, r as managedPackage, s as templatePackage, t as addedDevDependencies } from "../package-Dn7VTFUW.mjs";
4
+ import { i as presetConfig, n as SETUP_SCRIPT, r as lefthook, t as PRESET_CONFIGS } from "../templates-lJBZFskp.mjs";
5
5
  import { a as VERIFY_KINDS, c as isVerifyKind, i as SYNCED_SKILL_FILES, l as skillFolder, o as claudeLink, s as claudeLinkTarget, u as planDocsSkills } from "../shared-igPpEDpS.mjs";
6
6
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
7
7
  import { a as gitFiles, c as repositoryRoot } from "../files-DJ0TeaTU.mjs";
8
- import { i as recordedRelease, t as measureBaseline } from "../ratchet-Q-JXuZIX.mjs";
9
- import { a as ciWorkflow, c as ciNodeCallers, l as ciRenovateSyncCallers, o as placeholderTestScript, p as renovateArtifacts, r as CI_PATH, s as MISSING_CHECKS_WORKFLOW, u as hasChecksWorkflow } from "../ci-workflow-37qJa9LX.mjs";
10
- import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-C0SkPO5R.mjs";
11
- import { t as DEFAULT_SHARED } from "../map-B23_WMGE.mjs";
8
+ import { i as recordedRelease, t as measureBaseline } from "../ratchet-ClfblHNJ.mjs";
9
+ import { a as ciWorkflow, c as ciNodeCallers, l as ciRenovateSyncCallers, o as placeholderTestScript, p as renovateArtifacts, r as CI_PATH, s as MISSING_CHECKS_WORKFLOW, u as hasChecksWorkflow } from "../ci-workflow-COJUT12b.mjs";
10
+ import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-Dvb_IqBo.mjs";
11
+ import { t as DEFAULT_SHARED } from "../map-DRyYz_Fw.mjs";
12
12
  import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
13
- import { dirname, join, posix, resolve } from "node:path";
13
+ import { basename, dirname, join, posix, resolve } from "node:path";
14
14
  import { execFileSync } from "node:child_process";
15
15
  import { isMap, isScalar, isSeq, parseDocument } from "yaml";
16
16
  import ts from "typescript";
@@ -67,6 +67,8 @@ const SHARED_RULES = [
67
67
  ["String-keyed object tables are read through own keys only", "`antelopejs/no-inherited-key-lookup`"],
68
68
  ["A type guard checks each member it narrows to; keys with `Object.hasOwn`", "`antelopejs/no-presence-only-type-guard`"],
69
69
  ["A type guard checks the nested elements and values it claims", "review; no tool"],
70
+ ["A startup read does not decide an insert another replica can race", "`antelopejs/no-read-then-insert`"],
71
+ ["`Object.assign` writes no `unknown`, `any` or mistyped value over a field", "`antelopejs/no-unsafe-object-assign`"],
70
72
  ["Every file type-aware lint reads is listed by a tsconfig", "`antelopejs/require-tsconfig-include`"],
71
73
  ["Params ≤ 5, function ≤ 120 lines, file ≤ 500 lines, depth ≤ 4, complexity ≤ 20", "`eslint/max-*`, `eslint/complexity`"],
72
74
  ["Cleanup preserves declarations, runtime exports and DMS auto-imports", "`antelopejs-api-diff <base-ref>`"],
@@ -95,9 +97,9 @@ const FULL_RULES = [
95
97
  ["A CI gate reads `needs.<id>` only of jobs in its `needs`", "`antelopejs-sync --check`"],
96
98
  ["Entry-only rules exempt no tracked outsider", "`antelopejs-sync --check`"],
97
99
  ["A DMS layer's `build/backend-boundary.ts` is the pack's plugin", "`antelopejs-sync --check`"],
98
- ["No `skipLibCheck` in the root tsconfig or one `typecheck` or `build` uses", "Reported by `antelopejs-sync` (note only)"],
99
- ["`build` skips the lib check only over what `typecheck` checks", "Reported by `antelopejs-sync` (note only)"],
100
- ["`release` runs `typecheck`", "Reported by `antelopejs-sync` (note only)"],
100
+ ["No `skipLibCheck` in the root tsconfig or one `typecheck` or `build` uses", "`antelopejs-sync --check`"],
101
+ ["`build` skips the lib check only over what `typecheck` checks", "`antelopejs-sync --check`"],
102
+ ["`release` runs `typecheck`", "`antelopejs-sync --check`"],
101
103
  ["A test names the wrong implementation it catches", "review; no tool"]
102
104
  ];
103
105
  /** Pads each column the way oxfmt does, so formatting AGENTS.md never reports sync drift. */
@@ -424,6 +426,91 @@ function checkEntryOnlyConfiguration(root) {
424
426
  };
425
427
  }
426
428
  //#endregion
429
+ //#region src/guardrails/markdown-table.ts
430
+ /** The lines of a Markdown table whose first row is the header, columns padded as oxfmt leaves them. */
431
+ function tableLines(table) {
432
+ const widths = table[0].map((_, column) => Math.max(3, ...table.map((row) => row[column].length)));
433
+ const line = (cells) => `| ${cells.map((cell, column) => cell.padEnd(widths[column])).join(" | ")} |`;
434
+ return [
435
+ line(table[0]),
436
+ line(widths.map((width) => "-".repeat(width))),
437
+ ...table.slice(1).map(line)
438
+ ];
439
+ }
440
+ //#endregion
441
+ //#region src/guardrails/docs-modules.ts
442
+ const DMS_MODULES_START = "<!-- antelopejs-dms-modules:start -->";
443
+ const DMS_MODULES_END = "<!-- antelopejs-dms-modules:end -->";
444
+ const ORGANIZATION = "https://github.com/AntelopeJS";
445
+ /** The AntelopeJS DMS modules in display order. Every README holding the markers lists exactly these. */
446
+ const DMS_MODULES = [
447
+ {
448
+ repo: "dms-builder",
449
+ row: "Edit pages, tables and data sources by clicking, as TypeScript that compiles"
450
+ },
451
+ {
452
+ repo: "dms-ai",
453
+ row: "An assistant chat in the dashboard, on your own Claude Code or Codex"
454
+ },
455
+ {
456
+ repo: "dms-database",
457
+ row: "Schemas, relation diagrams, a data browser and a query console"
458
+ },
459
+ {
460
+ repo: "dms-api",
461
+ row: "API health, request logs, per-route statistics and a request tester"
462
+ },
463
+ {
464
+ repo: "dms-automation",
465
+ row: "Node-graph automations on schedules, webhooks and DMS events, with a trace for every run"
466
+ },
467
+ {
468
+ repo: "dms-mailing",
469
+ row: "E-mail templates in a block editor, versions, a send log and delivery metrics"
470
+ },
471
+ {
472
+ repo: "dms-lang",
473
+ row: "Translation coverage, a translation matrix and a translation queue"
474
+ },
475
+ {
476
+ repo: "dms-media",
477
+ row: "A media library with folders, per-folder permissions, image sizes and light editing"
478
+ },
479
+ {
480
+ repo: "dms-saas",
481
+ row: "Self-service sign-up, plans that gate features, and Stripe billing"
482
+ },
483
+ {
484
+ repo: "dms-marketing",
485
+ row: "Traffic, conversion funnels with A/B splits and click heatmaps, without cookies"
486
+ },
487
+ {
488
+ repo: "dms-frontend",
489
+ row: "The `ajs dms` CLI, the Vue renderer and the SDK every frontend module builds on"
490
+ }
491
+ ];
492
+ /** The generated block, formatted as oxfmt leaves it. */
493
+ function modulesBlock() {
494
+ return [
495
+ DMS_MODULES_START,
496
+ "",
497
+ ...tableLines([["Module", "What it adds"], ...DMS_MODULES.map(({ repo, row }) => [`[\`${repo}\`](${ORGANIZATION}/${repo})`, row])]),
498
+ "",
499
+ DMS_MODULES_END,
500
+ ""
501
+ ].join("\n");
502
+ }
503
+ /** The README with the block between its markers rewritten. A README without markers comes back as it is. */
504
+ function placeModulesBlock(current) {
505
+ const start = current.indexOf(DMS_MODULES_START);
506
+ const end = current.indexOf(DMS_MODULES_END);
507
+ const starts = current.split(DMS_MODULES_START).length - 1;
508
+ const ends = current.split(DMS_MODULES_END).length - 1;
509
+ if (starts === 0 && ends === 0) return current;
510
+ if (starts !== 1 || ends !== 1 || end < start) throw new Error("invalid antelopejs-dms-modules markers: a README holds exactly one start marker followed by one end marker. Repair or delete them, then rerun antelopejs-sync.");
511
+ return `${current.slice(0, start)}${modulesBlock()}${current.slice(end + 35).replace(/^\r?\n/, "")}`;
512
+ }
513
+ //#endregion
427
514
  //#region src/guardrails/docs-compat.ts
428
515
  const DOCS_COMPAT_START = "<!-- antelopejs-docs-compat:start -->";
429
516
  const DOCS_COMPAT_END = "<!-- antelopejs-docs-compat:end -->";
@@ -442,27 +529,19 @@ const RESOLVED_SECTIONS = [
442
529
  ];
443
530
  /** The generated block, rows sorted by package name, formatted as oxfmt leaves it. */
444
531
  function compatBlock(rows) {
445
- const table = [[
446
- "Package",
447
- "Supported",
448
- "Tested with"
449
- ], ...[...rows].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0).map(({ name, supported, tested }) => [
450
- `\`${name}\``,
451
- `\`${supported.replaceAll("|", "\\|")}\``,
452
- tested === void 0 ? UNRESOLVED : `\`${tested}\``
453
- ])];
454
- const widths = [
455
- 0,
456
- 1,
457
- 2
458
- ].map((column) => Math.max(3, ...table.map((row) => row[column].length)));
459
- const line = (cells) => `| ${cells.map((cell, column) => cell.padEnd(widths[column])).join(" | ")} |`;
532
+ const sorted = [...rows].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
460
533
  return [
461
534
  DOCS_COMPAT_START,
462
535
  "",
463
- line(table[0]),
464
- line(widths.map((width) => "-".repeat(width))),
465
- ...table.slice(1).map(line),
536
+ ...tableLines([[
537
+ "Package",
538
+ "Supported",
539
+ "Tested with"
540
+ ], ...sorted.map(({ name, supported, tested }) => [
541
+ `\`${name}\``,
542
+ `\`${supported.replaceAll("|", "\\|")}\``,
543
+ tested === void 0 ? UNRESOLVED : `\`${tested}\``
544
+ ])]),
466
545
  "",
467
546
  DOCS_COMPAT_END,
468
547
  ""
@@ -632,12 +711,14 @@ function sharesLockfile(root) {
632
711
  function lockPath(shared, directory) {
633
712
  return shared ? LOCKFILE : relative$1(directory, LOCKFILE);
634
713
  }
635
- function readLock(root, shared, directory) {
714
+ function readLock(root, shared, directory, documents) {
636
715
  const path = join(root, lockPath(shared, directory));
637
- return existsSync(path) ? {
638
- document: parseDocument(readFileSync(path, "utf8")),
716
+ if (!documents.has(path) && existsSync(path)) documents.set(path, parseDocument(readFileSync(path, "utf8")));
717
+ const document = documents.get(path);
718
+ return document && {
719
+ document,
639
720
  importer: shared ? directory || "." : "."
640
- } : void 0;
721
+ };
641
722
  }
642
723
  /** Adds one package's `docs-files` lines and, when it needs one, its README with the generated blocks. */
643
724
  function planPackage(root, plan, lock, standard, { directory, ranges, published, node }) {
@@ -648,7 +729,7 @@ function planPackage(root, plan, lock, standard, { directory, ranges, published,
648
729
  if (isDirectory(root, docs)) plan.docsFiles.push(docs);
649
730
  const current = existsSync(join(root, readme)) ? readFileSync(join(root, readme), "utf8") : void 0;
650
731
  const nodeRange = standard && current !== void 0 ? node : void 0;
651
- if (ranges.size === 0 && nodeRange === void 0) return;
732
+ if (ranges.size === 0 && current === void 0) return;
652
733
  const rows = [...ranges].map(([name, supported]) => ({
653
734
  name,
654
735
  supported,
@@ -659,7 +740,7 @@ function planPackage(root, plan, lock, standard, { directory, ranges, published,
659
740
  plan.readmes.push({
660
741
  path: readme,
661
742
  current,
662
- content: rows.length > 0 ? placeCompatBlock(withRequirements, compatBlock(rows)) : withRequirements ?? ""
743
+ content: placeModulesBlock(rows.length > 0 ? placeCompatBlock(withRequirements, compatBlock(rows)) : withRequirements ?? "")
663
744
  });
664
745
  } catch (error) {
665
746
  plan.errors.push(`${readme}: ${error instanceof Error ? error.message : String(error)}`);
@@ -690,7 +771,8 @@ function planDocs(root, manager) {
690
771
  exists: (path) => existsSync(join(root, path))
691
772
  };
692
773
  const shared = sharesLockfile(root);
693
- const locks = new Map(packages.map(({ directory }) => [directory, manager === "pnpm" ? readLock(root, shared, directory) : void 0]));
774
+ const documents = /* @__PURE__ */ new Map();
775
+ const locks = new Map(qualifying.map(({ directory }) => [directory, manager === "pnpm" ? readLock(root, shared, directory, documents) : void 0]));
694
776
  const missing = manager === "pnpm" ? qualifying.filter(({ directory }) => !locks.get(directory)) : [];
695
777
  if (missing.length) {
696
778
  for (const path of new Set(missing.map(({ directory }) => lockPath(shared, directory)))) plan.errors.push(`${path} is missing, and the docs-compat block reads Tested with from it: run pnpm install, then rerun antelopejs-sync.`);
@@ -1164,17 +1246,20 @@ function scriptsOf(files) {
1164
1246
  return;
1165
1247
  }
1166
1248
  }
1167
- /** The package.json and tsconfig facts that keep `typecheck` the lib check no other script skips: `build` skips the lib check only over a program `typecheck` checks in full, no tsconfig a script uses or the root one sets `skipLibCheck: true`, and `release` runs `typecheck`. A file that cannot be read yields a note and never an error. */
1168
- function checkTypecheckCoverage(root) {
1249
+ /** The package.json and tsconfig facts that keep `typecheck` the lib check no other script skips: `build` skips the lib check only over a program `typecheck` checks in full, no tsconfig a script uses or the root one sets `skipLibCheck: true`, and `release` runs `typecheck`. Under `check` a broken fact is an error; otherwise it is a `Note:` advisory. A file that cannot be read yields a `Note:` advisory and never an error. */
1250
+ function checkTypecheckCoverage(root, check) {
1169
1251
  const files = coverageFiles(root);
1170
1252
  const scripts = scriptsOf(files);
1171
- if (scripts === void 0) return unreadableNotes(files);
1172
- return [
1253
+ const findings = scripts === void 0 ? [] : [
1173
1254
  ...skipCoverageErrors(scripts),
1174
1255
  ...skipLibCheckErrors(files, scripts),
1175
- ...releaseErrors(files, scripts),
1176
- ...unreadableNotes(files)
1256
+ ...releaseErrors(files, scripts)
1177
1257
  ];
1258
+ const notes = check ? unreadableNotes(files) : [...findings, ...unreadableNotes(files)];
1259
+ return {
1260
+ errors: check ? findings : [],
1261
+ advisories: notes.map((note) => `Note: ${note}`)
1262
+ };
1178
1263
  }
1179
1264
  /** The kind-specific text of each shared skill. */
1180
1265
  const KIND_TEXT = {
@@ -1202,27 +1287,33 @@ const KIND_TEXT = {
1202
1287
  title: "Verify module",
1203
1288
  user: "The user of a module is an app developer: they add it to `antelope.config.ts`, configure it, and other modules call the interfaces it implements.",
1204
1289
  launch: "`new` runs the setup (`pnpm run build` by default), then starts every `services` entry of `verify.config.ts` in its own Docker container on a free loopback port, named `<prefix>-<repo>-<service>-<run>` (`VERIFY_CONTAINER_PREFIX`, default `verify`), and waits for each readiness command. A provider with sandbox keys in `saas.env` records the missing ones.",
1205
- builtins: "- `module-dev`: a fixture project installs the module as `local` with `moduleConfig(services)` as its config, plus a consumer module. `ajs project dev` must answer, the consumer must load every implemented interface, Ctrl+C must exit 130 and the port must refuse afterwards.",
1290
+ builtins: "- `module-dev`: a fixture project installs the module as `local` with `moduleConfig(services)` as its config, plus the `companions(services)` modules and a consumer module. `ajs project dev` must answer, the consumer must load every implemented interface, Ctrl+C must exit 130 and the port must refuse afterwards.",
1206
1291
  layer: `- \`services\`: image, port, readiness command and a \`reset\` command run before every journey, so each starts from a clean state.
1207
1292
  - \`moduleConfig(services)\`: the module's configuration, pointing at the run's containers.
1293
+ - \`companions(services)\`: other modules the fixture project loads, keyed by name, each a \`source\` and an optional \`config\` as in \`antelope.config.ts\`. Add the provider of every interface the module imports that it does not implement, such as \`@antelopejs/api\` for \`@antelopejs/interface-api\`, or the module never finishes starting.
1208
1294
  - \`saas: { env, sandbox }\`: a SaaS module runs against the provider's sandbox with keys from these environment variables. Without every key, each journey is NOT VERIFIED and so is the verdict, never PASS or PASS+NOTES.
1209
1295
  - \`journeys\`: the module's own journeys. Each writes through the module with \`context.call(...)\` and reads the result back with \`context.native(...)\` (\`redis-cli\`, \`mongosh\`, \`psql\`, the Mailpit API) inside the service container.`,
1210
1296
  smoke: "`module-dev` and one write read back through the native client",
1211
1297
  gotchas: ["Every container is the run's own. Never point a journey at a shared instance such as a developer's local database.", "A sandbox key missing from the environment is a NOT VERIFIED verdict."]
1212
1298
  },
1213
1299
  template: {
1214
- description: "Drive this AntelopeJS template the way a new user does: scaffold a project with `ajs project init` from an offline interfaces manifest, install it, run its own `pnpm run checks`, run `ajs project dev --watch` and hit its welcome page, endpoint or ready line. Use to prove a change to the template works before merge, to verify a PR, or to run the release canary.",
1300
+ description: "Drive this AntelopeJS template the way a new user does: scaffold a project with `ajs project init`, or a module with `ajs module init`, from an offline interfaces manifest, install it, run its own `pnpm run checks`, run `ajs project dev --watch` and hit its welcome page, endpoint or ready line. Use to prove a change to the template works before merge, to verify a PR, or to run the release canary.",
1215
1301
  title: "Verify template",
1216
- user: "The user of a template is someone running `ajs project init --template`: they get a copy of the repository without `.agents/` and `.claude/skills/` and expect it to install, pass its checks and run.",
1217
- launch: "`new` copies the working tree, uncommitted changes included, into a local git repository, and lists it in an offline interfaces manifest (`templates`, or `projectTemplates` when `template.project` is set) under `template.name`. Journeys point `ajs config set git` at it, so no step reaches GitHub. Every `services` entry of `verify.config.ts` then starts in its own Docker container on a free loopback port, as for a module.",
1302
+ user: "The user of a template is someone running `ajs project init --template`, or `ajs module init --template` for a module template: they get a copy of the repository without `.agents/` and `.claude/skills/` and expect it to install, pass its checks and run.",
1303
+ launch: "`new` copies the working tree, uncommitted changes included, into a local git repository, and lists it in an offline interfaces manifest (`templates`, or `projectTemplates` when `template.project` is set) under `template.name`. `context.scaffold` creates from it with `ajs project init`, or with `ajs module init` when `template.module` is set. Journeys point `ajs config set git` at it, so no step reaches GitHub. Every `services` entry of `verify.config.ts` then starts in its own Docker container on a free loopback port, as for a module.",
1218
1304
  builtins: `- \`scaffold-dev\`: \`ajs project init <app> --template <name> --pm pnpm --git-init\`, \`pnpm install --frozen-lockfile\`, then \`ajs project dev --watch\` with \`PORT\` set until \`template.probe\` answers: a path and status on that port, or a \`log\` line followed by \`settleMs\` of still running. Ctrl+C must exit 130.
1219
- - \`scaffold-checks\`: the same scaffold and install, then the project's own \`pnpm run checks\`.`,
1305
+ - \`scaffold-checks\`: the same scaffold and install, then the project's own \`pnpm run checks\`.
1306
+ - For a module template (\`template.module\`), both run \`ajs module init <app> --template <name> --pm pnpm --git-init\` in place of \`ajs project init\`, and \`scaffold-dev\` runs \`pnpm run build\` before \`ajs project dev --watch --project playground\`.
1307
+
1308
+ Both take their project from \`context.prepared("scaffolded", ...)\`, so the run scaffolds and installs it once. A repository journey that prepares \`scaffolded\` shares that build, so its build must be the same \`context.scaffold\` then \`pnpm install --frozen-lockfile --prefer-offline\`.`,
1220
1309
  layer: `- \`template.name\`: the listing name users pass to \`--template\`.
1221
1310
  - \`template.project\`: list it under \`projectTemplates\`.
1311
+ - \`template.module\`: a module template, listed under \`templates\` and created with \`ajs module init\`; it excludes \`template.project\`.
1222
1312
  - \`services\`: image, port, readiness command and \`reset\`, as for a module. \`new\` starts them in Docker on free ports; a journey reads them with \`context.service(name)\` and \`context.native(...)\` and passes their endpoints to the project it starts through the \`env\` of \`context.dev\`.
1313
+ - \`context.dev(name, project, { command })\`: a template that is not an \`ajs\` project starts with its own command, such as \`["node", "ace", "serve"]\`, in place of \`ajs project dev\`. The harness records its PID, so \`context.stop\` and \`clean\` stop it, and \`template.probe\` decides when it is ready. Leave \`scaffold-dev\` and \`scaffold-checks\` out of its features: both run \`ajs\`.
1223
1314
  - \`template.probe\`: \`path\`, \`status\` and \`body\` for an HTTP welcome page or endpoint, or \`log\` and \`settleMs\` for a template that serves nothing.`,
1224
- smoke: "`scaffold-dev` and `scaffold-checks`",
1225
- gotchas: ["`ajs project init` leaves out `.agents/` and `.claude/skills/`, so the scaffolded project carries neither this skill nor anything else under `.agents/`. Never expect either folder there.", "Every file a user gets is user-facing here, tests included; only `.github/` and `.claude/` outside `.claude/skills/` are not."]
1315
+ smoke: "`scaffold-dev` and `scaffold-checks`, or, for a template that is not an `ajs` project, its own journeys that start it with `context.dev(name, project, { command })`",
1316
+ gotchas: ["`ajs project init` and `ajs module init` leave out `.agents/` and `.claude/skills/`, so the scaffolded project or module carries neither this skill nor anything else under `.agents/`. Never expect either folder there.", "Every file a user gets is user-facing here, tests included; only `.github/` and `.claude/` outside `.claude/skills/` are not."]
1226
1317
  }
1227
1318
  };
1228
1319
  //#endregion
@@ -1294,14 +1385,15 @@ Each step writes \`<run>/evidence/<feature>/<journey>/<NN-step>/\` with \`comman
1294
1385
  ${BIN} clean <run>
1295
1386
  \`\`\`
1296
1387
 
1297
- Each journey deletes its scratch folder and \`HOME\`, its install included, when it ends: passed, failed or interrupted. Only its evidence stays. \`clean\` stops what the run started, by recorded PID and container name, and removes everything but \`evidence/\` and \`run.json\`, the folders \`context.prepared\` kept included. Run it after every run, failed ones included.
1388
+ Each journey deletes its scratch folder and \`HOME\`, its install included, when it ends: passed, failed or interrupted. Only its evidence stays. \`clean\` stops what the run started, by recorded PID and container name, and removes everything but \`evidence/\` and \`run.json\`, the folders \`context.prepared\` kept included. Run it after every run, failed ones included. It cleans only a run this checkout created, the folder \`new\` printed: it refuses the shared runs folder, a repository's folder of runs and another checkout's run, which belong to other sessions. Never delete under the runs folder yourself, with \`rm\` or a glob over run names.
1298
1389
 
1299
1390
  ## The repository's own layer
1300
1391
 
1301
1392
  - \`verify.config.ts\` default-exports a \`VerifyConfig\` from \`@antelopejs/tooling-configs/verify\`:
1302
1393
  - \`doors\`: one entry per door kind (\`data\`, \`format\`, \`contract\`, \`outbound\`, \`exposure\`, \`publish\`), each \`null\` when it cannot apply or \`{ globs, funnels, why }\`.
1303
- - \`journeys\`: the repository's journeys by id, each \`{ title, entryPoint, run(context) }\`, using the check helpers the same import exports. A check states what the product must do; an environment that went away is never a failing check. When a journey fails, the harness reruns each service's readiness command, up to four times over about 3.5 s, and looks at every \`ajs project dev\` the journey started, its own readiness probe included. The journey ends NOT VERIFIED, not FAIL, when a service still fails every rerun, an app was killed by SIGKILL, SIGTERM, SIGHUP or SIGINT that the harness did not send, or the app the harness started failed to bind the port the harness gave it (\`EADDRINUSE\` naming that port). An app that exits on its own with an exit code, one that crashes by another signal such as SIGABRT or SIGSEGV, and one that logs \`EADDRINUSE\` for any other port are the product's failure. A change that takes its own service down still reads as an outage: the service stays down, so the journey is NOT VERIFIED. For anything else the journey depends on, such as a process it started with \`context.command\` or an outside endpoint, probe it when a check fails and call \`context.notVerified(reason)\` when it no longer answers.
1304
- - \`context.prepared(key, build)\` does the preparation many journeys repeat once per run, such as scaffolding and installing a project, and returns the journey's own copy at \`<work>/<key>\`. The first journey that asks for \`key\` runs \`build(folder)\` on the empty folder with its usual steps, after a step \`prepared <key>\` that marks them as the build and says whether it was kept. A build is kept until \`clean\` only when it returns, records at least one check, passes every check, and leaves only files, directories and symlinks in the folder. Every later journey of the run, also in a later \`journey\` command, gets a fresh copy and one step, \`prepared <key>\`, that names the journey that built it and holds that build's evidence under \`build/\`. A build that is not kept is built again by the next journey, and rerunning the journey that built builds again. An absolute symlink into the folder points into each copy; other symlinks keep their target. \`build\` writes only inside the folder it is given: a write elsewhere, such as a sibling under \`<work>\` or the repository, stays with the journey that built. Two concurrent \`journey\` commands that reach the same key at once both build, and the first to finish is kept. The commands \`build\` runs get a \`HOME\` of their own that is deleted when it ends: redo after \`prepared\` anything a later step needs in \`HOME\`, such as \`ajs config set git\`. Pass the same \`build\` for a key in every journey.
1394
+ - \`journeys\`: the repository's journeys by id, each \`{ title, entryPoint, run(context) }\`, using the check helpers the same import exports. A check states what the product must do; an environment that went away is never a failing check. When a journey fails, the harness reruns each service's readiness command, up to four times over about 3.5 s, and looks at every \`ajs project dev\` the journey started, its own readiness probe included. The journey ends NOT VERIFIED, not FAIL, when a service still fails every rerun, an app was killed by SIGKILL, SIGTERM, SIGHUP or SIGINT that the harness did not send, or the app the harness started failed to bind the port the harness gave it (\`EADDRINUSE\` naming that port), or the first failing step is an install, image pull or image build whose failed requests went only to fixed public registry names that also fail a fresh DNS and TCP probe at verdict time. A registry that answers that probe makes the failure the product's, whatever the output says. An app that exits on its own with an exit code, one that crashes by another signal such as SIGABRT or SIGSEGV, and one that logs \`EADDRINUSE\` for any other port are the product's failure. A change that takes its own service down still reads as an outage: the service stays down, so the journey is NOT VERIFIED. For anything else the journey depends on, such as a process it started with \`context.command\` or an outside endpoint, probe it when a check fails and call \`context.notVerified(reason)\` when it no longer answers.
1395
+
1396
+ - \`context.prepared(key, build)\` does the preparation many journeys repeat once per run, such as scaffolding and installing a project, and returns the journey's own copy at \`<work>/<key>\`. The first journey that asks for \`key\` runs \`build(folder)\` on the empty folder with its usual steps, after a step \`prepared <key>\` that marks them as the build and says whether it was kept. A build is kept until \`clean\` only when it returns, records at least one check, passes every check, and leaves only files, directories and symlinks in the folder. Every later journey of the run, also in a later \`journey\` command, gets a fresh copy and one step, \`prepared <key>\`, that names the journey that built it and holds that build's evidence under \`build/\`. A build that is not kept is built again by the next journey, and rerunning the journey that built builds again. An absolute symlink into the folder points into each copy; other symlinks keep their target. A file with a hard link outside the folder, such as a package file pnpm links from its store, is linked into each copy rather than copied: \`context.edit\` gives it a new inode, and a journey that writes it another way replaces it instead of writing it in place. \`build\` writes only inside the folder it is given: a write elsewhere, such as a sibling under \`<work>\` or the repository, stays with the journey that built. Two concurrent \`journey\` commands that reach the same key at once both build, and the first to finish is kept. A project \`build\` creates with \`scaffold\` starts each copy as \`scaffold\` starts one: a copy with no installed module gets a module cache an earlier passing journey kept, and a passing journey keeps the registry modules installed into its copy. The commands \`build\` runs get a \`HOME\` of their own that is deleted when it ends: redo after \`prepared\` anything a later step needs in \`HOME\`, such as \`ajs config set git\`. Pass the same \`build\` for a key in every journey.
1305
1397
  - \`env\`, \`setup\` (commands replacing the build), \`userFacing\` and \`shared\` (globs replacing the kind's default; \`shared\` lists the files whose change runs every feature), and \`formal\` (formal checks: \`name\`, \`covers\`, \`command\`, \`violation\` with an optional \`states\` group for the counterexample length, and optionally \`behaviour\` and \`baseCommand\`).
1306
1398
  ${text.layer}
1307
1399
  - \`features/README.md\`: the index of the features; \`map\` does not read it as a feature.
@@ -1329,7 +1421,7 @@ ${BIN} map
1329
1421
  6. **One-way doors.** The section comes right after the result line and is mandatory. \`${BIN} doors\` prints the \`One-way-door:\` line of the diff. Every file the path rules flag needs a door row or a false positive with its reason.
1330
1422
  7. **Result.** FAIL if any rule fails. NOT VERIFIED when any journey of a required feature is NOT VERIFIED, for example a SaaS module run without its sandbox keys, however many other journeys passed. PASS+NOTES when everything required ran and passed but the judgement lists something no journey reached or something the owner should look at. PASS otherwise.
1331
1423
 
1332
- Write your judgement to \`<run>/evidence/judgement.json\`:
1424
+ Write your judgement to a JSON file:
1333
1425
 
1334
1426
  \`\`\`json
1335
1427
  {
@@ -1345,13 +1437,13 @@ Write your judgement to \`<run>/evidence/judgement.json\`:
1345
1437
  }
1346
1438
  \`\`\`
1347
1439
 
1348
- A door row is \`{ "kind", "location", "irreversible", "containment" }\`, where \`containment\` says what limits the damage. Then render the verdict:
1440
+ A door row is \`{ "kind", "location", "irreversible", "containment" }\`, where \`containment\` says what limits the damage. Pass it to \`verdict\` in the same step:
1349
1441
 
1350
1442
  \`\`\`bash
1351
- ${BIN} verdict <run> --pr <n>
1443
+ ${BIN} verdict <run> --pr <n> --judgement <file>
1352
1444
  \`\`\`
1353
1445
 
1354
- \`verdict\` writes \`evidence/verdict.md\` and exits 1 unless the result is PASS or PASS+NOTES. Report the verdict and what you saw in your own reply, from a thread that did not write the change.
1446
+ \`verdict\` stores it as \`evidence/judgement.json\`, writes \`evidence/verdict.md\` and exits 1 when an input is missing or the result is not PASS or PASS+NOTES. Read \`verdict.md\` only after it exits. Report the verdict and what you saw in your own reply, from a thread that did not write the change.
1355
1447
 
1356
1448
  ## Trust
1357
1449
 
@@ -1472,24 +1564,47 @@ function planSharedKind(root, kind) {
1472
1564
  path,
1473
1565
  content
1474
1566
  });
1475
- const link = claudeLink(kind);
1476
- const target = claudeLinkTarget(kind);
1567
+ const link = planLink(root, claudeLink(kind), claudeLinkTarget(kind));
1568
+ return {
1569
+ actions: [...actions, ...link.actions],
1570
+ errors: [...errors, ...link.errors]
1571
+ };
1572
+ }
1573
+ function planLink(root, link, target) {
1477
1574
  const stat = lstatSync(join(root, link), { throwIfNoEntry: false });
1478
- if (stat === void 0) actions.push({
1479
- kind: "link",
1480
- path: link,
1481
- target
1482
- });
1483
- else if (!stat.isSymbolicLink()) errors.push(`${link} is not a symlink. Move it away, then rerun antelopejs-sync.`);
1484
- else if (readlinkSync(join(root, link)) !== target) actions.push({
1485
- kind: "link",
1486
- path: link,
1487
- target
1488
- });
1575
+ if (stat === void 0) return {
1576
+ actions: [{
1577
+ kind: "link",
1578
+ path: link,
1579
+ target
1580
+ }],
1581
+ errors: []
1582
+ };
1583
+ if (!stat.isSymbolicLink()) return {
1584
+ actions: [],
1585
+ errors: [`${link} is not a symlink. Move it away, then rerun antelopejs-sync.`]
1586
+ };
1587
+ if (readlinkSync(join(root, link)) !== target) return {
1588
+ actions: [{
1589
+ kind: "link",
1590
+ path: link,
1591
+ target
1592
+ }],
1593
+ errors: []
1594
+ };
1489
1595
  return {
1490
- actions,
1491
- errors
1596
+ actions: [],
1597
+ errors: []
1598
+ };
1599
+ }
1600
+ /** The `.claude/skills` link of an own skill under `.agents/skills`; one elsewhere is already where Claude Code reads it, or is not an agent skill. */
1601
+ function planOwnLink(root, skill) {
1602
+ const folder = skill === void 0 ? void 0 : dirname(skill);
1603
+ if (folder === void 0 || dirname(folder) !== ".agents/skills") return {
1604
+ actions: [],
1605
+ errors: []
1492
1606
  };
1607
+ return planLink(root, `.claude/skills/${basename(folder)}`, `../../${folder}`);
1493
1608
  }
1494
1609
  function planStaleKinds(root, keep) {
1495
1610
  const actions = [];
@@ -1525,7 +1640,8 @@ function planStaleKinds(root, keep) {
1525
1640
  function planVerify(root, options) {
1526
1641
  const { kind, errors } = resolveKind(root, options.flag, options.manifest, options.profile);
1527
1642
  const shared = kind !== void 0 && kind !== "custom" ? kind : void 0;
1528
- const wanted = shared ? planSharedKind(root, shared) : {
1643
+ const own = shared ? void 0 : ownVerificationSkill(root);
1644
+ const wanted = shared ? planSharedKind(root, shared) : kind === "custom" ? planOwnLink(root, own) : {
1529
1645
  actions: [],
1530
1646
  errors: []
1531
1647
  };
@@ -1535,7 +1651,7 @@ function planVerify(root, options) {
1535
1651
  } : planStaleKinds(root, shared);
1536
1652
  return {
1537
1653
  kind,
1538
- verificationSkill: shared ? skillPath(shared) : ownVerificationSkill(root),
1654
+ verificationSkill: shared ? skillPath(shared) : own,
1539
1655
  actions: [...wanted.actions, ...stale.actions],
1540
1656
  errors: [...errors, ...wanted.errors],
1541
1657
  notes: stale.notes
@@ -1608,7 +1724,7 @@ const MANAGED_ARTIFACTS = [
1608
1724
  path: "package.json",
1609
1725
  profiles: ["full", "template"],
1610
1726
  desired: (current, context) => ({
1611
- content: context.profile === "full" ? managedPackage(current, context.versions, context) : templatePackage(current, context),
1727
+ content: context.profile === "full" ? managedPackage(current, context.versions, context) : templatePackage(current, context.versions, context),
1612
1728
  notes: []
1613
1729
  })
1614
1730
  },
@@ -1652,7 +1768,7 @@ const MANAGED_ARTIFACTS = [
1652
1768
  },
1653
1769
  {
1654
1770
  path: SUPPRESSIONS_FILE,
1655
- profiles: ["full"],
1771
+ profiles: ["full", "template"],
1656
1772
  desired: (_current, context) => ({
1657
1773
  content: context.suppressionBudget,
1658
1774
  notes: []
@@ -1757,12 +1873,13 @@ function repositoryContext(root, current, profile, verificationSkill) {
1757
1873
  nuxt: Boolean(manifest.dependencies?.nuxt || manifest.devDependencies?.nuxt || readdirSync(root).some((name) => name.startsWith("nuxt.config."))),
1758
1874
  claude: profile === "full" ? claudeProse(root, current) : "",
1759
1875
  baseline: "",
1760
- suppressionBudget: profile === "full" ? adoptedBudget(root, current.get(SUPPRESSIONS_FILE)) : "",
1876
+ suppressionBudget: adoptedBudget(root, current.get(SUPPRESSIONS_FILE)),
1761
1877
  managesCi: current.has(".github/workflows/ci.yml") || !hasChecksWorkflow(root),
1762
1878
  verificationSkill: profile === "template" && inScaffoldExcludedPath(verificationSkill) ? void 0 : verificationSkill,
1763
1879
  glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file))),
1764
1880
  docs: profile === "full" && current.has("package.json") ? planDocs(root, manager) : void 0,
1765
- placeholderTests: current.has("package.json") && placeholderTestScript(manifest.scripts?.test)
1881
+ placeholderTests: current.has("package.json") && placeholderTestScript(manifest.scripts?.test),
1882
+ captures: existsSync(join(root, "docs/captures.ts"))
1766
1883
  };
1767
1884
  }
1768
1885
  function writeArtifacts(root, artifacts) {
@@ -1802,7 +1919,9 @@ function syncRepository(root, options = {}) {
1802
1919
  let plan = [...planSync(current, modes, context), ...standalone];
1803
1920
  const errors = plan.filter((artifact) => artifact.kind === "error").map(({ message }) => message);
1804
1921
  const entryOnly = checkEntryOnlyConfiguration(root);
1922
+ const coverage = checkTypecheckCoverage(root, Boolean(options.check));
1805
1923
  errors.push(...entryOnly.errors, ...verify.errors, ...writing.errors);
1924
+ errors.push(...coverage.errors);
1806
1925
  const notes = plan.flatMap((artifact) => artifact.kind === "migrated" ? artifact.notes : []);
1807
1926
  (options.check ? errors : notes).push(...repositoryNotices(root, context));
1808
1927
  if (!errors.length && profile === "full" && !options.check && !current.has("guardrails.ratchet.json") && manifest.scripts?.["sync:check"] === void 0) {
@@ -1821,9 +1940,9 @@ function syncRepository(root, options = {}) {
1821
1940
  writeArtifacts(root, writes);
1822
1941
  applyVerifyActions(root, actions);
1823
1942
  }
1824
- const requiredDependencies = ["lefthook", "knip"];
1825
- if (context.typeAware) requiredDependencies.push("oxlint-tsgolint");
1826
- const dependenciesAdded = profile === "full" && requiredDependencies.some((name) => !manifest.devDependencies?.[name]);
1943
+ const templateDependencies = ["knip"];
1944
+ if (context.typeAware) templateDependencies.push("oxlint-tsgolint");
1945
+ const dependenciesAdded = profile === "full" ? addedDevDependencies(manifest, context.versions, context).length > 0 : templateDependencies.some((name) => !manifest.devDependencies?.[name]);
1827
1946
  return {
1828
1947
  artifacts: plan,
1829
1948
  paths: errors.length ? [] : [...writes, ...actions].map(({ path }) => path),
@@ -1831,7 +1950,7 @@ function syncRepository(root, options = {}) {
1831
1950
  errors,
1832
1951
  notes,
1833
1952
  verifyNotes: options.check || errors.length ? [] : verify.notes,
1834
- advisories: [...entryOnly.advisories, ...checkTypecheckCoverage(root).map((finding) => `Note: ${finding}`)],
1953
+ advisories: [...entryOnly.advisories, ...coverage.advisories],
1835
1954
  dependenciesAdded
1836
1955
  };
1837
1956
  }