@antelopejs/tooling-configs 0.2.11 → 0.2.13

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/dist/bin/sync.mjs CHANGED
@@ -6,7 +6,8 @@ import { a as repositoryTools, i as parseManifest, n as managedPackage, o as too
6
6
  import { t as measureBaseline } from "../ratchet-DRdIYwmv.mjs";
7
7
  import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-Yyf5_J5l.mjs";
8
8
  import { a as ciWorkflow, c as ciNodeCallers, i as MUTATION_PATH, l as hasChecksWorkflow, o as mutationCaller, r as CI_PATH, s as MISSING_CHECKS_WORKFLOW } from "../ci-workflow-BDy6hQJ6.mjs";
9
- import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, statSync, unlinkSync, writeFileSync } from "node:fs";
9
+ import { a as skillFolder, i as isVerifyKind, n as claudeLink, r as claudeLinkTarget, t as VERIFY_KINDS } from "../kinds-Bzyyi9yk.mjs";
10
+ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
10
11
  import { dirname, join, resolve } from "node:path";
11
12
  import { execFileSync } from "node:child_process";
12
13
  import { parseArgs } from "node:util";
@@ -340,6 +341,354 @@ function checkEntryOnlyConfiguration(root) {
340
341
  advisories
341
342
  };
342
343
  }
344
+ /** The kind-specific text of each shared skill. */
345
+ const KIND_TEXT = {
346
+ interface: {
347
+ description: "Drive this AntelopeJS interface the way a module author does: pack it, load it in `ajs project dev` next to a stub provider wired through ImplementInterface and a consumer, call every declared function through core, and check the minor-bump rule against the published version. Use to prove a change to the interface works before merge, to verify a PR, or to check that a seeded break is caught.",
348
+ title: "Verify interface",
349
+ user: "The user of an interface is a module author: one module implements it, others import it and call its functions through core.",
350
+ launch: "`new` runs the setup (`pnpm run build` by default), then packs the interface with `pnpm pack` and extracts it, so journeys load what npm would publish, `files` and `exports` included.",
351
+ builtins: `- \`every-function\`: a fixture project loads the packed interface with a stub provider and a consumer module. The consumer walks the loaded interface, and every function the \`.d.ts\` files declare is called through core:
352
+ - an async proxy answers the stub's echo, and the stub's call log shows the same arguments (the second view);
353
+ - a registering proxy registers and unregisters, and the stub logs both;
354
+ - an event proxy delivers the emitted arguments to a registered handler;
355
+ - a plain function runs the \`interface.calls\` hook of \`verify.config.ts\` and must return its \`expect\`; one only providers call is listed in \`interface.providerSide\` with why.
356
+ A declared function with none of these fails the journey.
357
+ - \`minor-bump\`: reads the declared functions of the packed head and of the published version (\`npm pack <name>@<latest>\`). An added, changed or removed function needs a release of at least the next minor. The release is the head version when it is already bumped, otherwise what changelogen makes of the change title (\`new --title\`) or the commit subjects since the base.`,
358
+ layer: `- \`interface.provide(api)\` runs in the stub provider after the generic stubs attach, for example to hand a stub client to \`internal.SetClient\`.
359
+ - \`interface.calls["<entry>:<path>"]\` calls a plain exported function from the consumer and states the value it must return.
360
+ - \`interface.providerSide["<entry>:<path>"]\` names a function only providers call, with the reason.`,
361
+ smoke: "`every-function`",
362
+ gotchas: ["A function the consumer awaits forever, such as a getter no provider resolved, fails after 15 seconds with a `Timeout` value.", "`minor-bump` needs the npm registry. Without it the journey is not verified, never passed."]
363
+ },
364
+ module: {
365
+ description: "Drive this AntelopeJS implementation module the way an app developer does: install it as `local` in a fixture project, run its backing services in Docker on free ports, call its interfaces from a consumer module and read stored state back with the service's native client. Use to prove a change to the module works before merge, to verify a PR, or to check that a seeded break is caught.",
366
+ title: "Verify module",
367
+ 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.",
368
+ 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.",
369
+ 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.",
370
+ layer: `- \`services\`: image, port, readiness command and a \`reset\` command run before every journey, so each starts from a clean state.
371
+ - \`moduleConfig(services)\`: the module's configuration, pointing at the run's containers.
372
+ - \`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.
373
+ - \`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.`,
374
+ smoke: "`module-dev` and one write read back through the native client",
375
+ 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, which sets status `verify` to `error`."]
376
+ },
377
+ template: {
378
+ 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, to run the release canary, or to check that a seeded break is caught.",
379
+ title: "Verify template",
380
+ user: "The user of a template is someone running `ajs project init --template`: they get a copy of the whole repository and expect it to install, pass its checks and run.",
381
+ 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.",
382
+ 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.
383
+ - \`scaffold-checks\`: the same scaffold and install, then the project's own \`pnpm run checks\`.`,
384
+ layer: `- \`template.name\`: the listing name users pass to \`--template\`.
385
+ - \`template.project\`: list it under \`projectTemplates\`.
386
+ - \`template.probe\`: \`path\`, \`status\` and \`body\` for an HTTP welcome page or endpoint, or \`log\` and \`settleMs\` for a template that serves nothing.`,
387
+ smoke: "`scaffold-dev` and `scaffold-checks`",
388
+ gotchas: ["`ajs` copies the whole repository, `.agents/` and `.claude/` included, so the scaffolded project carries this skill too.", "Every file a user gets is user-facing here, tests included; only `.agents/`, `.claude/` and `.github/` are not."]
389
+ }
390
+ };
391
+ //#endregion
392
+ //#region src/verify/skills.ts
393
+ const BIN = "pnpm exec antelopejs-verify";
394
+ function bullets(lines) {
395
+ return lines.map((line) => `- ${line}`).join("\n");
396
+ }
397
+ /** The synced SKILL.md of a kind, the part of the skill `antelopejs-sync` owns. */
398
+ function skillText(kind) {
399
+ const text = KIND_TEXT[kind];
400
+ const folder = skillFolder(kind);
401
+ return `---
402
+ name: verify-${kind}
403
+ description: ${JSON.stringify(text.description)}
404
+ ---
405
+
406
+ # ${text.title}
407
+
408
+ ${text.user} Every deterministic step is an \`antelopejs-verify\` command: you choose which journeys to run and judge what they show. Never replace a command with a shell recipe. When a journey you need does not exist, add it to \`verify.config.ts\`, name it in its feature file, then run it.
409
+
410
+ \`antelopejs-sync\` writes this file and \`package.json\` here, and keeps them in sync. Everything else in \`${folder}/\` is the repository's own layer, which sync never touches.
411
+
412
+ ## Launch
413
+
414
+ \`\`\`bash
415
+ ${BIN} new --base origin/main --title "<PR title>"
416
+ \`\`\`
417
+
418
+ \`new\` prints the run folder; pass it as \`<run>\` below. ${text.launch} Every journey gets its own \`HOME\` and scratch folder, \`CI=1\`, \`AJS_NO_UPDATE_CHECK=1\`, \`NO_COLOR=1\` and a free port from the kernel, so two runs never share an instance. Run it from the repository root after installing dependencies.
419
+
420
+ ## Doctor
421
+
422
+ \`\`\`bash
423
+ ${BIN} doctor <run>
424
+ \`\`\`
425
+
426
+ Doctor checks that HEAD has not moved since \`new\`, \`ajs\` comes from the repository's \`@antelopejs/core\`, the build is newer than \`src/\`, what \`new\` prepared is there, and no process the run recorded is still alive. Do not drive a run that fails doctor.
427
+
428
+ ## Drive
429
+
430
+ \`\`\`bash
431
+ ${BIN} plan --base origin/main
432
+ ${BIN} journey <run> <feature> [journey...]
433
+ \`\`\`
434
+
435
+ \`plan\` maps the diff to features and lists unmapped surfaces. \`journey\` runs a feature's journeys, or the ones named. The pack ships these journeys for this kind; a feature file names them next to the repository's own:
436
+
437
+ ${text.builtins}
438
+
439
+ ## Evidence
440
+
441
+ Each step writes \`<run>/evidence/<feature>/<journey>/<NN-step>/\` with \`command.txt\`, \`stdout.txt\`, \`stderr.txt\`, \`exit-code.txt\`, \`pid.txt\` for background processes, \`tree.txt\`, \`http.json\` for every request, and \`checks.json\`. \`result.json\` holds a journey's result and \`feature.json\` the merged results of the feature. Read the evidence before you judge a PASS: a check proves only what it asserts.
442
+
443
+ ## Cleanup
444
+
445
+ \`\`\`bash
446
+ ${BIN} clean <run>
447
+ \`\`\`
448
+
449
+ \`clean\` stops what the run started, by recorded PID and container name, and removes everything but \`evidence/\` and \`run.json\`. Run it after every run, failed ones included.
450
+
451
+ ## The repository's own layer
452
+
453
+ - \`verify.config.ts\` default-exports a \`VerifyConfig\` from \`@antelopejs/tooling-configs/verify\`:
454
+ - \`doors\`: one entry per door kind (\`data\`, \`format\`, \`contract\`, \`outbound\`, \`exposure\`, \`publish\`), each \`null\` when it cannot apply or \`{ globs, funnels, containments, why }\`. \`containments\` names the \`feature/journey\` that contains a Data or Format door.
455
+ - \`journeys\`: the repository's journeys by id, each \`{ title, entryPoint, run(context) }\`, using the check helpers the same import exports.
456
+ - \`env\`, \`setup\` (commands replacing the build), \`userFacing\` (globs replacing the kind's default) and \`formal\` (formal checks: \`name\`, \`covers\`, \`command\`, \`violation\`, and optionally \`behaviour\` and \`baseCommand\`).
457
+ ${text.layer}
458
+ - \`features/<feature>.md\`: frontmatter lists \`covers:\` (source globs), \`docs:\` (pages a verdict judges) and \`journeys:\`, then the sections Sub-features, How to get to it (user POV), Driving it with antelopejs-verify, and Gotchas. \`features/smoke.md\` covers nothing and runs on every verdict; here it runs ${text.smoke}.
459
+ - \`seeded-breaks/<feature>.patch\`: one minimal product bug per feature that its journeys must catch.
460
+ - \`seeded-doors/<kind>.patch\`: one change per door kind that applies.
461
+
462
+ \`\`\`bash
463
+ ${BIN} map
464
+ \`\`\`
465
+
466
+ \`map\` fails on a user-facing file no feature covers, a feature without journeys, docs or seeded break, an unknown journey, an applicable door kind without its seeded door, and a Data or Format door whose \`containments\` name no journey a feature registers.
467
+
468
+ ## Verdict rules
469
+
470
+ 1. **Run every feature whose \`covers:\` globs the diff touches, plus \`smoke\`.** \`plan\` prints that list as \`run\`.
471
+ 2. **An unmapped surface fails the verdict.** A changed user-facing file no feature covers needs a feature entry, its journeys and its seeded break in the same PR.
472
+ 3. **Every registered journey of a feature in \`run\` must have run and passed.** Run whole features. A journey that could not reach the product is not verified, and so is the verdict, never PASS.
473
+ 4. **Docs.** Judge every \`docs:\` page of a touched feature against what the journeys showed. A stale page fails the verdict.
474
+ 5. **Formal checks.** \`${BIN} formal <run>\` runs every formal check of \`verify.config.ts\` that covers the diff and records it under \`evidence/formal/<name>/\`. For each one it decides, without judgement, whether the diff changed what the covered code does. \`emit\` (the default) compares the structure of the covered files' JavaScript on the base and on HEAD: node kinds, names and literal values, leaving out types, comments, formatting, parentheses and \`export\` keywords. Each use of an imported binding stands for its origin (the resolved module and the imported name), so an import retargeted to another module or alias counts as changed; side-effect imports are compared by resolved module, and re-exports of uncovered modules by origin and exported name. Each file must keep its top-level statements in order; function declarations, which are hoisted, may move between covered files with their imports. So a type-only edit, a reformat or a moved function declaration counts as unchanged, while reordering statements or moving any other statement counts as changed. \`emit\` judges behaviour, not the public surface: exports are the api-diff's job. \`probe\` runs the check's \`behaviour.command\` with a worktree of each commit and compares what it prints. Then:
475
+ - a covered check that did not run, or exits non-zero (a tool error, or a check that no longer matches its record), fails the verdict;
476
+ - recorded findings fail the verdict only when the covered behaviour changed; when it did not, the verdict reports them as known findings;
477
+ - when the covered behaviour changed, or the diff changed the check's own \`files\`, \`formal\` also runs the check on the base (\`baseCommand\` when set). A rule the base broke counts as fixed only when HEAD reports it passing (\`passing\`); a rule the base broke that HEAD does not report at all fails the verdict. A change that leaves no violated rule passes.
478
+
479
+ The decision never reads the check's output, so a model whose rule names stay the same still fails on a changed behaviour. It is conservative: a local rename or an extracted helper counts as changed, and code outside \`covers\` is invisible to it. \`--all\` also runs the checks that do not cover the diff, without gating.
480
+ 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. A Data or Format row names a \`containments\` journey that passed in this run.
481
+ 7. **Result.** FAIL if any rule fails. NOT VERIFIED when a journey could not reach the product. PASS+NOTES when something is not verified or needs the owner's attention. PASS otherwise.
482
+
483
+ Write your judgement to \`<run>/evidence/judgement.json\`:
484
+
485
+ \`\`\`json
486
+ {
487
+ "doors": {
488
+ "none": "why the diff opens no door",
489
+ "rows": [],
490
+ "falsePositives": [{ "kind": "publish", "location": "package.json", "reason": "only devDependencies changed" }]
491
+ },
492
+ "docs": [{ "page": "README.md", "matches": true, "note": "" }],
493
+ "notVerified": ["What no journey reached, and why"],
494
+ "attention": ["What the owner should look at that the journeys cannot judge"],
495
+ "verifier": "the fresh thread that judged this run, not the author"
496
+ }
497
+ \`\`\`
498
+
499
+ A door row is \`{ "kind", "location", "irreversible", "containment", "containmentJourney" }\`. Then render and publish:
500
+
501
+ \`\`\`bash
502
+ ${BIN} verdict <run> --pr <n>
503
+ ${BIN} publish <run> --pr <n>
504
+ \`\`\`
505
+
506
+ \`verdict\` writes \`evidence/verdict.md\` and exits 1 unless the result is PASS or PASS+NOTES. \`publish\` commits the evidence to the orphan branch \`verify-evidence\` under \`pr-<n>/<sha>/\` from a temporary worktree, posts the verdict as a PR comment, sets commit status \`verify\` on the head SHA (\`success\` for PASS and PASS+NOTES, \`error\` for NOT VERIFIED, \`failure\` for FAIL) and reads it back. It prints the error GitHub answers when the token cannot write statuses. A new push voids the status. Post a verdict only from a thread that did not write the change.
507
+
508
+ ## Trust
509
+
510
+ The skill is not Trusted yet. It becomes Trusted when it catches every seeded break and flags every seeded door, passes a shadow run of 10 consecutive agent PRs, and its last maintain pass is newer than the last change to the repository or its \`@antelopejs\` dependencies and at most 30 days old.
511
+
512
+ ## Seeded breaks and doors
513
+
514
+ \`\`\`bash
515
+ ${BIN} seeded <feature...>
516
+ ${BIN} seeded-doors
517
+ \`\`\`
518
+
519
+ \`seeded\` runs each feature's journeys in a scratch worktree of HEAD without the patch, as the control, and with \`seeded-breaks/<feature>.patch\` applied. It prints \`CAUGHT\` only when a journey that passes in the control fails one of its checks with the patch. Journeys failing in the control and failures without a failing check do not count. \`seeded-doors\` prints \`FLAGGED\` when the path rules flag each patch with its own kind.
520
+
521
+ ## Gotchas
522
+
523
+ ${bullets(text.gotchas)}
524
+ - Runs live under the system temp folder (\`TMPDIR\`), and the shared caches under \`~/.cache/antelopejs-verify\`.
525
+ - A repository that outgrows this skill runs \`antelopejs-sync --verify custom\` and keeps its own \`.agents/skills/verify-<repo>/\`.
526
+ `;
527
+ }
528
+ /** The skill folder's package.json: it makes verify.config.ts an ES module and keeps the folder out of published packages. */
529
+ const SKILL_PACKAGE = `${JSON.stringify({
530
+ private: true,
531
+ type: "module"
532
+ }, null, 2)}\n`;
533
+ /** Every file of a kind's synced layer, by path relative to the repository root. */
534
+ function syncedFiles(kind) {
535
+ return [{
536
+ path: `${skillFolder(kind)}/SKILL.md`,
537
+ content: skillText(kind)
538
+ }, {
539
+ path: `${skillFolder(kind)}/package.json`,
540
+ content: SKILL_PACKAGE
541
+ }];
542
+ }
543
+ //#endregion
544
+ //#region src/guardrails/verify-skill.ts
545
+ /** Whether `value` is a valid `--verify` argument. */
546
+ function isVerifyChoice(value) {
547
+ return value === "custom" || isVerifyKind(value);
548
+ }
549
+ const SKILL_DIRECTORIES = [
550
+ ".agents/skills",
551
+ ".claude/skills",
552
+ "skills"
553
+ ];
554
+ function skillPath(kind) {
555
+ return `${skillFolder(kind)}/SKILL.md`;
556
+ }
557
+ /** The repository's own verification skill: a folder named like `verif` with a SKILL.md, other than the shared kind folders. */
558
+ function ownVerificationSkill(root) {
559
+ const shared = VERIFY_KINDS.map(skillFolder);
560
+ for (const directory of SKILL_DIRECTORIES) {
561
+ if (!existsSync(join(root, directory))) continue;
562
+ for (const entry of readdirSync(join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
563
+ const folder = `${directory}/${entry.name}`;
564
+ if (entry.isDirectory() && entry.name.toLowerCase().includes("verif") && !shared.includes(folder) && existsSync(join(root, folder, "SKILL.md"))) return `${folder}/SKILL.md`;
565
+ }
566
+ }
567
+ }
568
+ function inferKind(manifest, profile) {
569
+ if (profile === "template") return "template";
570
+ const declared = manifest.antelopeJs;
571
+ if (declared?.kind === "interface" || declared?.kind === "module") return declared.kind;
572
+ if (Array.isArray(declared?.implements) && declared.implements.length > 0) return "module";
573
+ }
574
+ function resolveKind(root, flag, manifest, profile) {
575
+ const errors = [];
576
+ if (flag === "custom" && ownVerificationSkill(root) === void 0) errors.push("--verify custom needs your own verification skill: write it under .agents/skills/verify-<repo>/ first.");
577
+ if (flag !== void 0) return {
578
+ kind: flag,
579
+ errors
580
+ };
581
+ const synced = VERIFY_KINDS.filter((kind) => existsSync(join(root, skillPath(kind))));
582
+ if (synced.length > 1) return {
583
+ kind: void 0,
584
+ errors: [`Several shared verification skills exist: ${synced.map(skillPath).join(", ")}. Keep one: run antelopejs-sync --verify <kind>.`]
585
+ };
586
+ if (synced.length === 1) return {
587
+ kind: synced[0],
588
+ errors
589
+ };
590
+ if (ownVerificationSkill(root) !== void 0) return {
591
+ kind: "custom",
592
+ errors
593
+ };
594
+ return {
595
+ kind: inferKind(manifest, profile),
596
+ errors
597
+ };
598
+ }
599
+ function readIfPresent(root, path) {
600
+ const file = join(root, path);
601
+ return existsSync(file) ? readFileSync(file, "utf8") : void 0;
602
+ }
603
+ function planSharedKind(root, kind) {
604
+ const actions = [];
605
+ const errors = [];
606
+ for (const { path, content } of syncedFiles(kind)) if (lstatSync(join(root, path), { throwIfNoEntry: false })?.isDirectory()) errors.push(`${path} is a folder. Move it away, then rerun antelopejs-sync.`);
607
+ else if (readIfPresent(root, path) !== content) actions.push({
608
+ kind: "write",
609
+ path,
610
+ content
611
+ });
612
+ const link = claudeLink(kind);
613
+ const target = claudeLinkTarget(kind);
614
+ const stat = lstatSync(join(root, link), { throwIfNoEntry: false });
615
+ if (stat === void 0) actions.push({
616
+ kind: "link",
617
+ path: link,
618
+ target
619
+ });
620
+ else if (!stat.isSymbolicLink()) errors.push(`${link} is not a symlink. Move it away, then rerun antelopejs-sync.`);
621
+ else if (readlinkSync(join(root, link)) !== target) actions.push({
622
+ kind: "link",
623
+ path: link,
624
+ target
625
+ });
626
+ return {
627
+ actions,
628
+ errors
629
+ };
630
+ }
631
+ function planStaleKinds(root, keep) {
632
+ const actions = [];
633
+ const notes = [];
634
+ for (const kind of VERIFY_KINDS) {
635
+ if (kind === keep) continue;
636
+ const before = actions.length;
637
+ for (const { path } of syncedFiles(kind)) {
638
+ const synced = lstatSync(join(root, path), { throwIfNoEntry: false });
639
+ if (synced?.isFile() || synced?.isSymbolicLink()) actions.push({
640
+ kind: "remove",
641
+ path
642
+ });
643
+ }
644
+ if (lstatSync(join(root, claudeLink(kind)), { throwIfNoEntry: false })?.isSymbolicLink()) actions.push({
645
+ kind: "remove",
646
+ path: claudeLink(kind)
647
+ });
648
+ if (actions.length === before) continue;
649
+ const folder = skillFolder(kind);
650
+ if (existsSync(join(root, folder)) && readdirSync(join(root, folder)).some((name) => !syncedFiles(kind).some(({ path }) => path === `${folder}/${name}`))) notes.push(`Removed the synced files of verify-${kind} and kept its repo-owned files in ${folder}.`);
651
+ }
652
+ return {
653
+ actions,
654
+ notes
655
+ };
656
+ }
657
+ /** Resolves the repository's verification kind and plans the synced layer; the repo-owned files are never touched. */
658
+ function planVerify(root, options) {
659
+ const { kind, errors } = resolveKind(root, options.flag, options.manifest, options.profile);
660
+ const shared = kind !== void 0 && kind !== "custom" ? kind : void 0;
661
+ const wanted = shared ? planSharedKind(root, shared) : {
662
+ actions: [],
663
+ errors: []
664
+ };
665
+ const stale = kind === void 0 ? {
666
+ actions: [],
667
+ notes: []
668
+ } : planStaleKinds(root, shared);
669
+ return {
670
+ kind,
671
+ verificationSkill: shared ? skillPath(shared) : ownVerificationSkill(root),
672
+ actions: [...wanted.actions, ...stale.actions],
673
+ errors: [...errors, ...wanted.errors],
674
+ notes: stale.notes
675
+ };
676
+ }
677
+ /** Applies planned changes; a replaced symlink is unlinked first so a write never goes through it. */
678
+ function applyVerifyActions(root, actions) {
679
+ for (const action of actions) {
680
+ const path = join(root, action.path);
681
+ if (action.kind === "remove") {
682
+ unlinkSync(path);
683
+ if (readdirSync(dirname(path)).length === 0) rmdirSync(dirname(path));
684
+ continue;
685
+ }
686
+ mkdirSync(dirname(path), { recursive: true });
687
+ if (lstatSync(path, { throwIfNoEntry: false }) !== void 0) unlinkSync(path);
688
+ if (action.kind === "write") writeFileSync(path, action.content);
689
+ else symlinkSync(action.target, path);
690
+ }
691
+ }
343
692
  //#endregion
344
693
  //#region src/guardrails/sync.ts
345
694
  const LEGACY_COMMENT_INSTRUCTION = "- Explain non-obvious constraints and decisions in comments; avoid restating the code. Document public contracts with TSDoc.";
@@ -492,19 +841,6 @@ function planSync(current, modes, context) {
492
841
  }
493
842
  return plan;
494
843
  }
495
- function verificationSkill(root) {
496
- for (const directory of [
497
- ".agents/skills",
498
- ".claude/skills",
499
- "skills"
500
- ]) {
501
- if (!existsSync(join(root, directory))) continue;
502
- for (const entry of readdirSync(join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
503
- const path = `${directory}/${entry.name}/SKILL.md`;
504
- if (entry.isDirectory() && entry.name.toLowerCase().includes("verif") && existsSync(join(root, path))) return path;
505
- }
506
- }
507
- }
508
844
  function repositorySnapshot(root) {
509
845
  const current = /* @__PURE__ */ new Map();
510
846
  const modes = /* @__PURE__ */ new Map();
@@ -530,7 +866,7 @@ function claudeProse(root, current) {
530
866
  if (!claude.includes("\n") && /^(?:@?(?:\.\/)?AGENTS\.md|(?:See |Refer to )?\[AGENTS\.md\]\((?:\.\/)?AGENTS\.md\)(?: for .*)?\.?)$/i.test(claude)) return "";
531
867
  return claude;
532
868
  }
533
- function repositoryContext(root, current, profile) {
869
+ function repositoryContext(root, current, profile, verificationSkill) {
534
870
  const manifest = parseManifest(current.get("package.json") ?? "{}");
535
871
  const lint = PRESET_CONFIGS[0];
536
872
  const desiredLint = current.get(lint.path) ?? lint.content;
@@ -547,7 +883,7 @@ function repositoryContext(root, current, profile) {
547
883
  suppressionBudget: profile === "full" && !current.has("guardrails.suppressions.json") ? adoptedBudget(root) : "",
548
884
  packageName: manifest.name ?? "",
549
885
  managesCi: current.has(".github/workflows/ci.yml") || !hasChecksWorkflow(root),
550
- verificationSkill: verificationSkill(root),
886
+ verificationSkill,
551
887
  glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file)))
552
888
  };
553
889
  }
@@ -571,11 +907,16 @@ function syncRepository(root, options = {}) {
571
907
  const profile = options.profile ?? "full";
572
908
  const { current, modes } = repositorySnapshot(root);
573
909
  const manifest = parseManifest(current.get("package.json") ?? "{}");
574
- const context = repositoryContext(root, current, profile);
910
+ const verify = planVerify(root, {
911
+ flag: options.verify,
912
+ manifest,
913
+ profile
914
+ });
915
+ const context = repositoryContext(root, current, profile, verify.verificationSkill);
575
916
  let plan = planSync(current, modes, context);
576
917
  const errors = plan.filter((artifact) => artifact.kind === "error").map(({ message }) => message);
577
918
  const entryOnly = checkEntryOnlyConfiguration(root);
578
- errors.push(...entryOnly.errors);
919
+ errors.push(...entryOnly.errors, ...verify.errors);
579
920
  const notes = plan.flatMap((artifact) => artifact.kind === "migrated" ? artifact.notes : []);
580
921
  (options.check ? errors : notes).push(...repositoryNotices(root, context));
581
922
  if (!errors.length && profile === "full" && !options.check && !current.has("guardrails.ratchet.json") && manifest.scripts?.["sync:check"] === void 0) {
@@ -587,15 +928,20 @@ function syncRepository(root, options = {}) {
587
928
  plan = planSync(current, modes, context);
588
929
  }
589
930
  const writes = plan.filter((artifact) => artifact.kind === "write" || artifact.kind === "migrated");
590
- if (!options.check && !errors.length) writeArtifacts(root, writes);
931
+ if (!options.check && !errors.length) {
932
+ writeArtifacts(root, writes);
933
+ applyVerifyActions(root, verify.actions);
934
+ }
591
935
  const requiredDependencies = ["lefthook", "knip"];
592
936
  if (context.typeAware) requiredDependencies.push("oxlint-tsgolint");
593
937
  const dependenciesAdded = profile === "full" && requiredDependencies.some((name) => !manifest.devDependencies?.[name]);
594
938
  return {
595
939
  artifacts: plan,
596
- paths: errors.length ? [] : writes.map(({ path }) => path),
940
+ paths: errors.length ? [] : [...writes, ...verify.actions].map(({ path }) => path),
941
+ removed: verify.actions.filter((action) => action.kind === "remove").map(({ path }) => path),
597
942
  errors,
598
943
  notes,
944
+ verifyNotes: options.check || errors.length ? [] : verify.notes,
599
945
  advisories: entryOnly.advisories,
600
946
  dependenciesAdded
601
947
  };
@@ -608,18 +954,22 @@ runCli(() => {
608
954
  profile: {
609
955
  type: "string",
610
956
  default: "full"
611
- }
957
+ },
958
+ verify: { type: "string" }
612
959
  } });
613
960
  if (values.profile !== "full" && values.profile !== "template") throw new Error("--profile must be full or template.");
961
+ if (values.verify !== void 0 && !isVerifyChoice(values.verify)) throw new Error("--verify must be interface, module, template, or custom.");
614
962
  const result = syncRepository(repositoryRoot(), {
615
963
  check: values.check,
616
- profile: values.profile
964
+ profile: values.profile,
965
+ verify: values.verify
617
966
  });
618
967
  for (const note of result.notes) process.stdout.write(`Note: ${values.check || result.errors.length ? "Planned migration. " : ""}${note}\n`);
968
+ for (const note of result.verifyNotes) process.stdout.write(`Note: ${note}\n`);
619
969
  for (const advisory of result.advisories) process.stdout.write(`${advisory}\n`);
620
970
  for (const error of result.errors) process.stderr.write(`${error}\n`);
621
971
  if (result.errors.length) return 1;
622
- for (const path of result.paths) process.stdout.write(`${values.check ? "Drift" : "Updated"}: ${path}${values.check ? "; run antelopejs-sync" : ""}\n`);
972
+ for (const path of result.paths) process.stdout.write(values.check ? `Drift: ${path}; run antelopejs-sync\n` : `${result.removed.includes(path) ? "Removed" : "Updated"}: ${path}\n`);
623
973
  if (!result.paths.length) process.stdout.write("Guardrails are in sync.\n");
624
974
  if (!values.check && result.dependenciesAdded) process.stdout.write("Added devDependencies. Run install with your package manager before using the hooks or checks.\n");
625
975
  return values.check && result.paths.length ? 1 : 0;
@@ -0,0 +1 @@
1
+ export {}