@antelopejs/tooling-configs 0.4.0 → 0.5.0

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 (40) hide show
  1. package/README.md +38 -26
  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 +141 -14
  7. package/dist/bin/comment-proof.mjs +29 -7
  8. package/dist/bin/garden.mjs +2 -57
  9. package/dist/bin/ratchet.mjs +48 -14
  10. package/dist/bin/suppressions.mjs +3 -3
  11. package/dist/bin/sync.mjs +74 -41
  12. package/dist/bin/verify.mjs +898 -366
  13. package/dist/capture/index.d.mts +6 -1
  14. package/dist/capture/index.mjs +1 -1
  15. package/dist/{ci-workflow-37qJa9LX.mjs → ci-workflow-COJUT12b.mjs} +121 -1
  16. package/dist/eslint.d.mts +16 -3
  17. package/dist/eslint.mjs +21 -6
  18. package/dist/formal/index.d.mts +20 -4
  19. package/dist/formal/index.mjs +71 -19
  20. package/dist/{map-B23_WMGE.mjs → map-DRyYz_Fw.mjs} +20 -1
  21. package/dist/oxc/anti-slop/index.mjs +50 -55
  22. package/dist/oxc/guardrails/index.d.mts +1 -1
  23. package/dist/oxc/guardrails/index.mjs +520 -103
  24. package/dist/oxc/lint.d.mts +7 -15
  25. package/dist/oxc/lint.mjs +16 -28
  26. package/dist/{package-CqqBgE8Y.mjs → package-Dn7VTFUW.mjs} +71 -17
  27. package/dist/{proof-stamp-DDDC0J6l.mjs → proof-stamp-DLWpPwQE.mjs} +72 -10
  28. package/dist/{ratchet-Q-JXuZIX.mjs → ratchet-BTiPMqam.mjs} +17 -15
  29. package/dist/require-safety-comment-for-type-assertion-mnb0CIxa.mjs +181 -0
  30. package/dist/{scenes-DZVXkcxS.mjs → scenes-d-VQ0LOm.mjs} +4 -1
  31. package/dist/semver-BDxeEcP_.mjs +57 -0
  32. package/dist/{suppression-base-9L8dlMQK.mjs → suppression-base-Drnl6Y7F.mjs} +2 -2
  33. package/dist/{suppression-budget-C0SkPO5R.mjs → suppression-budget-Dvb_IqBo.mjs} +1 -1
  34. package/dist/{suppressions-DM60NkvL.mjs → suppressions-BroaaGJ_.mjs} +1 -1
  35. package/dist/{templates-BKZv-BRw.mjs → templates-lJBZFskp.mjs} +8 -3
  36. package/dist/type-aware-rules-DMuN6sHb.mjs +30 -0
  37. package/dist/{typescript-DAgQIAAR.mjs → typescript-BBbry7uU.mjs} +123 -27
  38. package/dist/verify/index.d.mts +60 -15
  39. package/package.json +3 -1
  40. package/dist/require-safety-comment-for-type-assertion-BBQ669kj.mjs +0 -83
@@ -1,7 +1,8 @@
1
1
  #!/usr/bin/env node
2
+ import { t as admits } from "../semver-BDxeEcP_.mjs";
2
3
  import { c as object, d as optTime, f as parseJson, h as time, i as isObject, l as optNum, m as strings, n as children, o as list, p as str, r as flag, s as num, t as child, u as optStr } from "../json-CG2L7YFl.mjs";
3
4
  import { n as runCliAsync } from "../cli-4Tv71vYk.mjs";
4
- import { c as ciNodeCallers, d as RENOVATE_CONFIGS, f as RENOVATE_PRESET, i as CI_RENOVATE_SYNC_REF, l as ciRenovateSyncCallers, n as CI_NODE_REF, r as CI_PATH, t as CI_CONTEXT } from "../ci-workflow-37qJa9LX.mjs";
5
+ import { c as ciNodeCallers, d as RENOVATE_CONFIGS, f as RENOVATE_PRESET, i as CI_RENOVATE_SYNC_REF, l as ciRenovateSyncCallers, n as CI_NODE_REF, r as CI_PATH, t as CI_CONTEXT } from "../ci-workflow-COJUT12b.mjs";
5
6
  import { i as ghToken, n as createApi, t as ApiError } from "../api-CCOiLN3w.mjs";
6
7
  import { parseArgs } from "node:util";
7
8
  import { inflateRawSync } from "node:zlib";
@@ -1145,62 +1146,6 @@ const packageSize = {
1145
1146
  }
1146
1147
  };
1147
1148
  //#endregion
1148
- //#region src/garden/semver.ts
1149
- const VERSION = /^v?(\d+)\.(\d+)\.(\d+)/;
1150
- function parse(text) {
1151
- const match = VERSION.exec(text.trim());
1152
- return match ? [
1153
- Number(match[1]),
1154
- Number(match[2]),
1155
- Number(match[3])
1156
- ] : void 0;
1157
- }
1158
- function compare$1(a, b) {
1159
- return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
1160
- }
1161
- function caret(floor) {
1162
- if (floor[0] > 0) return [
1163
- floor[0] + 1,
1164
- 0,
1165
- 0
1166
- ];
1167
- return floor[1] > 0 ? [
1168
- 0,
1169
- floor[1] + 1,
1170
- 0
1171
- ] : [
1172
- 0,
1173
- 0,
1174
- floor[2] + 1
1175
- ];
1176
- }
1177
- function comparator(term, version) {
1178
- const operator = /^(>=|<=|>|<|=|\^|~)?\s*(.*)$/.exec(term.trim());
1179
- const bound = parse(operator?.[2] ?? "");
1180
- if (!operator || !bound) return true;
1181
- switch (operator[1]) {
1182
- case ">=": return compare$1(version, bound) >= 0;
1183
- case ">": return compare$1(version, bound) > 0;
1184
- case "<=": return compare$1(version, bound) <= 0;
1185
- case "<": return compare$1(version, bound) < 0;
1186
- case "^": return compare$1(version, bound) >= 0 && compare$1(version, caret(bound)) < 0;
1187
- case "~": return compare$1(version, bound) >= 0 && compare$1(version, [
1188
- bound[0],
1189
- bound[1] + 1,
1190
- 0
1191
- ]) < 0;
1192
- default: return compare$1(version, bound) === 0;
1193
- }
1194
- }
1195
- /** Whether a plain npm range (`^`, `~`, comparators, `||`, `*`) admits a release; wildcards and tags admit everything. */
1196
- function admits(range, release) {
1197
- const version = parse(release);
1198
- if (!version) return true;
1199
- return range.split("||").some((alternative) => {
1200
- return alternative.replace(/(>=|<=|>|<|=|\^|~)\s+/g, "$1").trim().split(/\s+/).every((term) => comparator(term, version));
1201
- });
1202
- }
1203
- //#endregion
1204
1149
  //#region src/garden/checks/templates.ts
1205
1150
  const DAY = 864e5;
1206
1151
  const INTERFACES = "interfaces";
@@ -2,13 +2,13 @@
2
2
  import { c as parseCeilings, l as readCeilings, t as CEILINGS_FILE } from "../ceilings-B7KayYIG.mjs";
3
3
  import { n as renamedPaths } from "../renames-L2owF5GD.mjs";
4
4
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
5
- import { c as repositoryRoot, l as resolveRevision, s as repositoryPath, t as LINT_CONFIG } from "../files-DJ0TeaTU.mjs";
6
- import { n as ratchet, r as withPreviousTree } from "../ratchet-Q-JXuZIX.mjs";
5
+ import { c as repositoryRoot, l as resolveRevision, t as LINT_CONFIG } from "../files-DJ0TeaTU.mjs";
6
+ import { n as ratchet, r as withPreviousTree } from "../ratchet-BTiPMqam.mjs";
7
7
  import { t as lintDiagnostics } from "../oxlint-DIV-lLSS.mjs";
8
- import { d as stagedAdditions, f as stagedChanges, u as previousLine } from "../suppression-budget-C0SkPO5R.mjs";
9
- import { n as suppressionBase } from "../suppression-base-9L8dlMQK.mjs";
8
+ import { d as stagedAdditions, f as stagedChanges, u as previousLine } from "../suppression-budget-Dvb_IqBo.mjs";
9
+ import { n as suppressionBase } from "../suppression-base-Drnl6Y7F.mjs";
10
10
  import { existsSync } from "node:fs";
11
- import { join, resolve } from "node:path";
11
+ import { join } from "node:path";
12
12
  import { execFileSync, spawnSync } from "node:child_process";
13
13
  import { parseArgs } from "node:util";
14
14
  //#region src/guardrails/approved-raises.ts
@@ -44,6 +44,7 @@ function stagedNames(root, filter) {
44
44
  "diff",
45
45
  "--cached",
46
46
  "--name-only",
47
+ "--ignore-submodules=all",
47
48
  `--diff-filter=${filter}`,
48
49
  "-z"
49
50
  ], {
@@ -169,15 +170,47 @@ function hiddenTracked(root) {
169
170
  encoding: "utf8"
170
171
  }).split("\0").filter((line) => /^(S|[a-z]) /u.test(line)).map((line) => line.slice(2));
171
172
  }
172
- function approvalRefusal(root, rule, max, holds) {
173
- const unstaged = execFileSync("git", [
173
+ /** Tracked files whose working copy differs from the index, deleted ones included. */
174
+ function unstagedNames(root) {
175
+ return execFileSync("git", [
174
176
  "diff",
175
177
  "--name-only",
178
+ "--no-renames",
176
179
  "-z"
177
180
  ], {
178
181
  cwd: root,
179
182
  encoding: "utf8"
180
183
  }).split("\0").filter(Boolean);
184
+ }
185
+ /** Per file and rule, the findings of whichever run reports more of them. */
186
+ function higherPerFile(first, second) {
187
+ const key = ({ file, rule }) => `${file}\0${rule}`;
188
+ const left = Map.groupBy(first, key);
189
+ const right = Map.groupBy(second, key);
190
+ return [.../* @__PURE__ */ new Set([...left.keys(), ...right.keys()])].flatMap((group) => {
191
+ const a = left.get(group) ?? [];
192
+ const b = right.get(group) ?? [];
193
+ return a.length >= b.length ? a : b;
194
+ });
195
+ }
196
+ /**
197
+ * The findings in `targets` as the index holds them. Each file the working
198
+ * tree has is linted there, where untracked generated types resolve; a file
199
+ * whose working copy differs, is deleted, or is hidden from git (skip-worktree,
200
+ * assume-unchanged), or every file when a lint configuration does, is also
201
+ * linted in a checkout of the index, and keeps, per rule, the run that reports
202
+ * more.
203
+ */
204
+ function stagedDiagnostics(root, targets) {
205
+ const unstaged = /* @__PURE__ */ new Set([...unstagedNames(root), ...hiddenTracked(root)]);
206
+ const present = targets.filter((file) => existsSync(join(root, file)));
207
+ const inTree = present.length ? lintDiagnostics(root, void 0, present, STAGED_LINT) : [];
208
+ const inIndex = [...unstaged].some((file) => LINT_CONFIG.test(file)) ? targets : targets.filter((file) => unstaged.has(file));
209
+ if (!inIndex.length) return inTree;
210
+ return higherPerFile(inTree, withPreviousTree(root, "HEAD", [], (tree) => lintDiagnostics(tree, void 0, inIndex, STAGED_LINT), { wholeIndex: true }));
211
+ }
212
+ function approvalRefusal(root, rule, max, holds) {
213
+ const unstaged = unstagedNames(root);
181
214
  if (unstaged.length) return `${rule}: an approved raise is refused while ${unstaged.length} tracked file(s) have unstaged changes (${unstaged[0]}); stage or stash them first.`;
182
215
  const hidden = hiddenTracked(root);
183
216
  if (hidden.length) return `${rule}: an approved raise is refused while ${hidden.length} tracked file(s) are skip-worktree or assume-unchanged (${hidden[0]}); disable the sparse checkout or clear the bit first.`;
@@ -212,7 +245,8 @@ function inRanges(ranges, file, line) {
212
245
  return ranges.get(file)?.some(({ start, end }) => line >= start && line <= end) ?? false;
213
246
  }
214
247
  /**
215
- * Fails each ceilinged rule whose findings in the staged files outnumber both
248
+ * Fails each ceilinged rule whose findings in the staged files, as the index
249
+ * holds them, outnumber both
216
250
  * what the same files, rename sources and deleted files had at HEAD and the
217
251
  * staged findings that sit, on a line unchanged since the merge-base of HEAD
218
252
  * with the pull request base (`GITHUB_BASE_REF`, else `origin/HEAD`), where
@@ -225,17 +259,17 @@ function inRanges(ranges, file, line) {
225
259
  * rise above both fails, and lists the findings on the lines that differ from
226
260
  * HEAD and from the base.
227
261
  */
228
- function stagedRatchet(root, files) {
262
+ function stagedRatchet(root) {
229
263
  const approved = parseApprovedRaises();
230
264
  const raised = unlistedRaises(root, approved);
231
265
  const accepted = [];
232
- const targets = files ?? stagedNames(root, "ACMR");
266
+ const targets = stagedNames(root, "ACMR");
233
267
  if (!targets.length) return {
234
268
  failures: raised,
235
269
  accepted
236
270
  };
237
271
  const ceilings = readCeilings(root);
238
- const after = lintDiagnostics(root, void 0, targets, STAGED_LINT).filter(({ rule }) => Object.hasOwn(ceilings.rules, rule) || approved.has(rule));
272
+ const after = stagedDiagnostics(root, targets).filter(({ rule }) => Object.hasOwn(ceilings.rules, rule) || approved.has(rule));
239
273
  if (!after.length) return {
240
274
  failures: raised,
241
275
  accepted
@@ -300,8 +334,8 @@ function stagedRatchet(root, files) {
300
334
  }
301
335
  //#endregion
302
336
  //#region src/bin/ratchet.ts
303
- function stagedResult(root, files) {
304
- const staged = stagedRatchet(root, files.length ? files.map((file) => repositoryPath(root, resolve(file))) : void 0);
337
+ function stagedResult(root) {
338
+ const staged = stagedRatchet(root);
305
339
  return {
306
340
  failures: staged.failures,
307
341
  accepted: staged.accepted,
@@ -324,7 +358,7 @@ runCli(() => {
324
358
  if (values.base !== void 0 && values.staged) throw new Error("--base cannot be combined with --staged.");
325
359
  if (values.update && values.staged) throw new Error("--staged cannot be combined with --update.");
326
360
  if (positionals.length && !values.staged) throw new Error("File arguments require --staged.");
327
- const result = values.staged ? stagedResult(root, positionals) : {
361
+ const result = values.staged ? stagedResult(root) : {
328
362
  ...ratchet(root, values.update, values.base === void 0 ? void 0 : resolveRevision(root, values.base), suppressionBase(root, values.base)),
329
363
  accepted: []
330
364
  };
@@ -2,9 +2,9 @@
2
2
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
3
3
  import { c as repositoryRoot, r as changedFiles } from "../files-DJ0TeaTU.mjs";
4
4
  import { n as unusedDirectives } from "../oxlint-DIV-lLSS.mjs";
5
- import { c as stagedSuppressions, i as checkSuppressions, l as checkPolicy, s as stagedNames } from "../suppression-budget-C0SkPO5R.mjs";
6
- import { c as suppressionsIn, i as inWorktree } from "../suppressions-DM60NkvL.mjs";
7
- import { n as suppressionBase, t as raisedCeilings } from "../suppression-base-9L8dlMQK.mjs";
5
+ import { c as stagedSuppressions, i as checkSuppressions, l as checkPolicy, s as stagedNames } from "../suppression-budget-Dvb_IqBo.mjs";
6
+ import { c as suppressionsIn, i as inWorktree } from "../suppressions-BroaaGJ_.mjs";
7
+ import { n as suppressionBase, t as raisedCeilings } from "../suppression-base-Drnl6Y7F.mjs";
8
8
  import { readdirSync } from "node:fs";
9
9
  import { dirname, join } from "node:path";
10
10
  import { execFileSync, spawnSync } from "node:child_process";
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-BTiPMqam.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,7 @@ 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
+ ["`Object.assign` writes no `unknown`, `any` or mistyped value over a field", "`antelopejs/no-unsafe-object-assign`"],
70
71
  ["Every file type-aware lint reads is listed by a tsconfig", "`antelopejs/require-tsconfig-include`"],
71
72
  ["Params ≤ 5, function ≤ 120 lines, file ≤ 500 lines, depth ≤ 4, complexity ≤ 20", "`eslint/max-*`, `eslint/complexity`"],
72
73
  ["Cleanup preserves declarations, runtime exports and DMS auto-imports", "`antelopejs-api-diff <base-ref>`"],
@@ -1202,27 +1203,33 @@ const KIND_TEXT = {
1202
1203
  title: "Verify module",
1203
1204
  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
1205
  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.",
1206
+ 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
1207
  layer: `- \`services\`: image, port, readiness command and a \`reset\` command run before every journey, so each starts from a clean state.
1207
1208
  - \`moduleConfig(services)\`: the module's configuration, pointing at the run's containers.
1209
+ - \`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
1210
  - \`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
1211
  - \`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
1212
  smoke: "`module-dev` and one write read back through the native client",
1211
1213
  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
1214
  },
1213
1215
  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.",
1216
+ 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
1217
  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.",
1218
+ 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.",
1219
+ 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
1220
  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\`.`,
1221
+ - \`scaffold-checks\`: the same scaffold and install, then the project's own \`pnpm run checks\`.
1222
+ - 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\`.
1223
+
1224
+ 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
1225
  layer: `- \`template.name\`: the listing name users pass to \`--template\`.
1221
1226
  - \`template.project\`: list it under \`projectTemplates\`.
1227
+ - \`template.module\`: a module template, listed under \`templates\` and created with \`ajs module init\`; it excludes \`template.project\`.
1222
1228
  - \`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\`.
1229
+ - \`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
1230
  - \`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."]
1231
+ 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 })`",
1232
+ 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
1233
  }
1227
1234
  };
1228
1235
  //#endregion
@@ -1294,14 +1301,15 @@ Each step writes \`<run>/evidence/<feature>/<journey>/<NN-step>/\` with \`comman
1294
1301
  ${BIN} clean <run>
1295
1302
  \`\`\`
1296
1303
 
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.
1304
+ 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
1305
 
1299
1306
  ## The repository's own layer
1300
1307
 
1301
1308
  - \`verify.config.ts\` default-exports a \`VerifyConfig\` from \`@antelopejs/tooling-configs/verify\`:
1302
1309
  - \`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.
1310
+ - \`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.
1311
+
1312
+ - \`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
1313
  - \`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
1314
  ${text.layer}
1307
1315
  - \`features/README.md\`: the index of the features; \`map\` does not read it as a feature.
@@ -1472,25 +1480,48 @@ function planSharedKind(root, kind) {
1472
1480
  path,
1473
1481
  content
1474
1482
  });
1475
- const link = claudeLink(kind);
1476
- const target = claudeLinkTarget(kind);
1483
+ const link = planLink(root, claudeLink(kind), claudeLinkTarget(kind));
1484
+ return {
1485
+ actions: [...actions, ...link.actions],
1486
+ errors: [...errors, ...link.errors]
1487
+ };
1488
+ }
1489
+ function planLink(root, link, target) {
1477
1490
  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
- });
1491
+ if (stat === void 0) return {
1492
+ actions: [{
1493
+ kind: "link",
1494
+ path: link,
1495
+ target
1496
+ }],
1497
+ errors: []
1498
+ };
1499
+ if (!stat.isSymbolicLink()) return {
1500
+ actions: [],
1501
+ errors: [`${link} is not a symlink. Move it away, then rerun antelopejs-sync.`]
1502
+ };
1503
+ if (readlinkSync(join(root, link)) !== target) return {
1504
+ actions: [{
1505
+ kind: "link",
1506
+ path: link,
1507
+ target
1508
+ }],
1509
+ errors: []
1510
+ };
1489
1511
  return {
1490
- actions,
1491
- errors
1512
+ actions: [],
1513
+ errors: []
1492
1514
  };
1493
1515
  }
1516
+ /** 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. */
1517
+ function planOwnLink(root, skill) {
1518
+ const folder = skill === void 0 ? void 0 : dirname(skill);
1519
+ if (folder === void 0 || dirname(folder) !== ".agents/skills") return {
1520
+ actions: [],
1521
+ errors: []
1522
+ };
1523
+ return planLink(root, `.claude/skills/${basename(folder)}`, `../../${folder}`);
1524
+ }
1494
1525
  function planStaleKinds(root, keep) {
1495
1526
  const actions = [];
1496
1527
  const notes = [];
@@ -1525,7 +1556,8 @@ function planStaleKinds(root, keep) {
1525
1556
  function planVerify(root, options) {
1526
1557
  const { kind, errors } = resolveKind(root, options.flag, options.manifest, options.profile);
1527
1558
  const shared = kind !== void 0 && kind !== "custom" ? kind : void 0;
1528
- const wanted = shared ? planSharedKind(root, shared) : {
1559
+ const own = shared ? void 0 : ownVerificationSkill(root);
1560
+ const wanted = shared ? planSharedKind(root, shared) : kind === "custom" ? planOwnLink(root, own) : {
1529
1561
  actions: [],
1530
1562
  errors: []
1531
1563
  };
@@ -1535,7 +1567,7 @@ function planVerify(root, options) {
1535
1567
  } : planStaleKinds(root, shared);
1536
1568
  return {
1537
1569
  kind,
1538
- verificationSkill: shared ? skillPath(shared) : ownVerificationSkill(root),
1570
+ verificationSkill: shared ? skillPath(shared) : own,
1539
1571
  actions: [...wanted.actions, ...stale.actions],
1540
1572
  errors: [...errors, ...wanted.errors],
1541
1573
  notes: stale.notes
@@ -1608,7 +1640,7 @@ const MANAGED_ARTIFACTS = [
1608
1640
  path: "package.json",
1609
1641
  profiles: ["full", "template"],
1610
1642
  desired: (current, context) => ({
1611
- content: context.profile === "full" ? managedPackage(current, context.versions, context) : templatePackage(current, context),
1643
+ content: context.profile === "full" ? managedPackage(current, context.versions, context) : templatePackage(current, context.versions, context),
1612
1644
  notes: []
1613
1645
  })
1614
1646
  },
@@ -1652,7 +1684,7 @@ const MANAGED_ARTIFACTS = [
1652
1684
  },
1653
1685
  {
1654
1686
  path: SUPPRESSIONS_FILE,
1655
- profiles: ["full"],
1687
+ profiles: ["full", "template"],
1656
1688
  desired: (_current, context) => ({
1657
1689
  content: context.suppressionBudget,
1658
1690
  notes: []
@@ -1757,12 +1789,13 @@ function repositoryContext(root, current, profile, verificationSkill) {
1757
1789
  nuxt: Boolean(manifest.dependencies?.nuxt || manifest.devDependencies?.nuxt || readdirSync(root).some((name) => name.startsWith("nuxt.config."))),
1758
1790
  claude: profile === "full" ? claudeProse(root, current) : "",
1759
1791
  baseline: "",
1760
- suppressionBudget: profile === "full" ? adoptedBudget(root, current.get(SUPPRESSIONS_FILE)) : "",
1792
+ suppressionBudget: adoptedBudget(root, current.get(SUPPRESSIONS_FILE)),
1761
1793
  managesCi: current.has(".github/workflows/ci.yml") || !hasChecksWorkflow(root),
1762
1794
  verificationSkill: profile === "template" && inScaffoldExcludedPath(verificationSkill) ? void 0 : verificationSkill,
1763
1795
  glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file))),
1764
1796
  docs: profile === "full" && current.has("package.json") ? planDocs(root, manager) : void 0,
1765
- placeholderTests: current.has("package.json") && placeholderTestScript(manifest.scripts?.test)
1797
+ placeholderTests: current.has("package.json") && placeholderTestScript(manifest.scripts?.test),
1798
+ captures: existsSync(join(root, "docs/captures.ts"))
1766
1799
  };
1767
1800
  }
1768
1801
  function writeArtifacts(root, artifacts) {
@@ -1821,9 +1854,9 @@ function syncRepository(root, options = {}) {
1821
1854
  writeArtifacts(root, writes);
1822
1855
  applyVerifyActions(root, actions);
1823
1856
  }
1824
- const requiredDependencies = ["lefthook", "knip"];
1825
- if (context.typeAware) requiredDependencies.push("oxlint-tsgolint");
1826
- const dependenciesAdded = profile === "full" && requiredDependencies.some((name) => !manifest.devDependencies?.[name]);
1857
+ const templateDependencies = ["knip"];
1858
+ if (context.typeAware) templateDependencies.push("oxlint-tsgolint");
1859
+ const dependenciesAdded = profile === "full" ? addedDevDependencies(manifest, context.versions, context).length > 0 : templateDependencies.some((name) => !manifest.devDependencies?.[name]);
1827
1860
  return {
1828
1861
  artifacts: plan,
1829
1862
  paths: errors.length ? [] : [...writes, ...actions].map(({ path }) => path),