@vaubaan/harness 1.3.2 → 2.0.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.
- package/README.md +303 -167
- package/dist/cli/index.js +908 -1781
- package/dist/cli/index.js.map +1 -1
- package/dist/index.d.ts +4 -2
- package/dist/index.js +380 -1063
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +29 -20
- package/dist/init.js +531 -655
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +687 -31
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +1 -26
- package/dist/parser/index.js +1 -17
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-B9_kNtQc.d.ts → render-C-FWmUfX.d.ts} +8 -15
- package/dist/render.d.ts +1 -1
- package/dist/render.js +16 -278
- package/dist/render.js.map +1 -1
- package/dist/skills/decision-record-writer.skill.md +3 -4
- package/dist/skills/doc-audit.skill.md +7 -7
- package/dist/skills/drift-detector.skill.md +1 -1
- package/dist/skills/handbook-writer.skill.md +2 -2
- package/dist/skills/readme-writer.skill.md +3 -3
- package/dist/skills/spec-writer.skill.md +89 -71
- package/dist/skills/test-plan-writer.skill.md +3 -3
- package/dist/skills/workflow-writer.skill.md +20 -3
- package/dist/templates/code-quality.md.tmpl +2 -2
- package/dist/templates/coding-workflow.md.tmpl +10 -0
- package/package.json +1 -1
- package/dist/agents/coding.agent.md +0 -182
- package/dist/agents/merge.agent.md +0 -139
- package/dist/agents/planning.agent.md +0 -194
- package/dist/agents/review.agent.md +0 -176
- package/dist/commands/clean-code.cmd.md +0 -26
- package/dist/skills/clean-code-guardian.skill.md +0 -391
package/dist/cli/index.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
|
|
3
3
|
// src/cli/index.ts
|
|
4
|
-
import { dirname as
|
|
4
|
+
import { dirname as dirname9, resolve as resolve9 } from "path";
|
|
5
5
|
import { fileURLToPath as fileURLToPath2 } from "url";
|
|
6
6
|
import { Command } from "commander";
|
|
7
7
|
|
|
@@ -41,9 +41,9 @@ function gitLastCommitForPath(repoRoot, relativePath) {
|
|
|
41
41
|
if (!out) return void 0;
|
|
42
42
|
const idx = out.indexOf(":");
|
|
43
43
|
if (idx < 0) return void 0;
|
|
44
|
-
const
|
|
44
|
+
const hash = out.slice(0, idx);
|
|
45
45
|
const ts = Number.parseInt(out.slice(idx + 1), 10);
|
|
46
|
-
return { hash
|
|
46
|
+
return { hash, timestamp: ts };
|
|
47
47
|
} catch {
|
|
48
48
|
return void 0;
|
|
49
49
|
}
|
|
@@ -356,437 +356,134 @@ var frontmatterTracks = {
|
|
|
356
356
|
}
|
|
357
357
|
};
|
|
358
358
|
|
|
359
|
-
// src/linters/
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
".harness-manifest.json",
|
|
363
|
-
".harness/",
|
|
364
|
-
".claude/",
|
|
365
|
-
".codex/",
|
|
366
|
-
".opencode/",
|
|
367
|
-
".agents/",
|
|
368
|
-
".vaubaan/",
|
|
369
|
-
"AGENTS.md",
|
|
370
|
-
"CLAUDE.md",
|
|
371
|
-
".mcp.json"
|
|
372
|
-
];
|
|
373
|
-
var gitignoreHarness = {
|
|
374
|
-
id: "lint:gitignore-harness",
|
|
375
|
-
pillars: ["repo-root"],
|
|
376
|
-
defaultSeverity: "error",
|
|
377
|
-
run(repoRoot) {
|
|
378
|
-
const issues = [];
|
|
379
|
-
if (!fileExists(repoRoot, ".gitignore")) {
|
|
380
|
-
issues.push({
|
|
381
|
-
linter: this.id,
|
|
382
|
-
severity: "error",
|
|
383
|
-
file: ".gitignore",
|
|
384
|
-
message: ".gitignore is missing at repo root"
|
|
385
|
-
});
|
|
386
|
-
return issues;
|
|
387
|
-
}
|
|
388
|
-
const text = readText(repoRoot, ".gitignore");
|
|
389
|
-
const lines = new Set(
|
|
390
|
-
text.split("\n").map((l) => l.trim()).filter(Boolean)
|
|
391
|
-
);
|
|
392
|
-
for (const entry of REQUIRED_GITIGNORE_ENTRIES) {
|
|
393
|
-
const variants = [entry, entry.replace(/\/$/, "")];
|
|
394
|
-
if (!variants.some((v) => lines.has(v))) {
|
|
395
|
-
issues.push({
|
|
396
|
-
linter: this.id,
|
|
397
|
-
severity: "error",
|
|
398
|
-
file: ".gitignore",
|
|
399
|
-
message: `.gitignore must contain "${entry}"`
|
|
400
|
-
});
|
|
401
|
-
}
|
|
402
|
-
}
|
|
403
|
-
return issues;
|
|
404
|
-
}
|
|
405
|
-
};
|
|
406
|
-
|
|
407
|
-
// src/linters/orphan-decisions.ts
|
|
408
|
-
import { basename } from "path";
|
|
409
|
-
import fg4 from "fast-glob";
|
|
410
|
-
var orphanDecisions = {
|
|
411
|
-
id: "lint:orphan-decisions",
|
|
412
|
-
pillars: ["decisions"],
|
|
413
|
-
defaultSeverity: "warning",
|
|
414
|
-
suggestedSkills: ["/handbook"],
|
|
415
|
-
run(repoRoot, ctx) {
|
|
416
|
-
const extra = ctx?.config.ignore ?? [];
|
|
417
|
-
const issues = [];
|
|
418
|
-
const adrs = listMarkdown(repoRoot, "docs/decisions");
|
|
419
|
-
if (adrs.length === 0) return issues;
|
|
420
|
-
const otherDocs = fg4.sync("**/*.md", {
|
|
421
|
-
cwd: repoRoot,
|
|
422
|
-
absolute: false,
|
|
423
|
-
ignore: [
|
|
424
|
-
"**/node_modules/**",
|
|
425
|
-
"**/dist/**",
|
|
426
|
-
".harness-overrides/**",
|
|
427
|
-
"docs/decisions/**",
|
|
428
|
-
"skills/**",
|
|
429
|
-
"agents/**",
|
|
430
|
-
"commands/**",
|
|
431
|
-
"templates/**",
|
|
432
|
-
...extra
|
|
433
|
-
]
|
|
434
|
-
});
|
|
435
|
-
const referenceCorpus = otherDocs.map((f) => readText(repoRoot, f)).join("\n");
|
|
436
|
-
for (const adr of adrs) {
|
|
437
|
-
const filename = basename(adr);
|
|
438
|
-
const stem = filename.replace(/\.md$/, "");
|
|
439
|
-
const referenced = referenceCorpus.includes(filename) || referenceCorpus.includes(stem);
|
|
440
|
-
if (!referenced) {
|
|
441
|
-
issues.push({
|
|
442
|
-
linter: this.id,
|
|
443
|
-
severity: "warning",
|
|
444
|
-
file: adr,
|
|
445
|
-
message: "ADR is not referenced by any other doc file (orphan)"
|
|
446
|
-
});
|
|
447
|
-
}
|
|
448
|
-
}
|
|
449
|
-
return issues;
|
|
450
|
-
}
|
|
451
|
-
};
|
|
452
|
-
|
|
453
|
-
// src/linters/quality-schema.ts
|
|
454
|
-
var QUALITY_DIR = "docs/quality";
|
|
455
|
-
var CARDINAL_FILE = `${QUALITY_DIR}/code-quality.md`;
|
|
456
|
-
var REQUIRED_SECTIONS2 = [
|
|
457
|
-
{
|
|
458
|
-
label: "Mechanical checks",
|
|
459
|
-
pattern: /^##\s+(Mechanical\s+checks|V[ée]rifications\s+m[ée]caniques)\s*$/im
|
|
460
|
-
},
|
|
461
|
-
{ label: "Project rules", pattern: /^##\s+(Project\s+rules|R[èe]gles\s+du\s+projet)\s*$/im },
|
|
462
|
-
{
|
|
463
|
-
label: "Accepted deviations",
|
|
464
|
-
pattern: /^##\s+(Accepted\s+deviations|[ÉE]carts\s+assum[ée]s)\s*$/im
|
|
465
|
-
}
|
|
466
|
-
];
|
|
467
|
-
var qualitySchema = {
|
|
468
|
-
id: "lint:quality-schema",
|
|
469
|
-
pillars: ["quality"],
|
|
470
|
-
defaultSeverity: "error",
|
|
471
|
-
run(repoRoot) {
|
|
472
|
-
if (!dirExists(repoRoot, QUALITY_DIR)) return [];
|
|
473
|
-
if (!fileExists(repoRoot, CARDINAL_FILE)) {
|
|
474
|
-
return [
|
|
475
|
-
{
|
|
476
|
-
linter: this.id,
|
|
477
|
-
severity: "error",
|
|
478
|
-
file: CARDINAL_FILE,
|
|
479
|
-
message: `missing required cardinal file: ${CARDINAL_FILE}`
|
|
480
|
-
}
|
|
481
|
-
];
|
|
482
|
-
}
|
|
483
|
-
const text = readText(repoRoot, CARDINAL_FILE);
|
|
484
|
-
return REQUIRED_SECTIONS2.filter(({ pattern }) => !pattern.test(text)).map(({ label }) => ({
|
|
485
|
-
linter: this.id,
|
|
486
|
-
severity: "error",
|
|
487
|
-
file: CARDINAL_FILE,
|
|
488
|
-
message: `missing required section: "${label}"`
|
|
489
|
-
}));
|
|
490
|
-
}
|
|
491
|
-
};
|
|
492
|
-
|
|
493
|
-
// src/linters/readme-presence.ts
|
|
494
|
-
var readmePresence = {
|
|
495
|
-
id: "lint:readme-presence",
|
|
496
|
-
pillars: ["readme"],
|
|
497
|
-
defaultSeverity: "error",
|
|
498
|
-
suggestedSkills: ["/readme"],
|
|
499
|
-
run(repoRoot) {
|
|
500
|
-
if (fileExists(repoRoot, "README.md")) return [];
|
|
501
|
-
return [
|
|
502
|
-
{
|
|
503
|
-
linter: this.id,
|
|
504
|
-
severity: "error",
|
|
505
|
-
file: "README.md",
|
|
506
|
-
message: "README.md is missing at repo root"
|
|
507
|
-
}
|
|
508
|
-
];
|
|
509
|
-
}
|
|
510
|
-
};
|
|
511
|
-
|
|
512
|
-
// src/linters/readme-sections.ts
|
|
513
|
-
var REQUIRED_SECTIONS3 = [
|
|
514
|
-
/^#\s+\S/m,
|
|
515
|
-
/^##?\s+(What is this|Quick start)/im,
|
|
516
|
-
/^##?\s+(Quick start|Install|Getting started)/im
|
|
517
|
-
];
|
|
518
|
-
var REQUIRED_LABELS = ["title (# H1)", "What is this / intro", "Quick start / Install"];
|
|
519
|
-
var readmeSections = {
|
|
520
|
-
id: "lint:readme-sections",
|
|
521
|
-
pillars: ["readme"],
|
|
522
|
-
defaultSeverity: "error",
|
|
523
|
-
suggestedSkills: ["/readme"],
|
|
524
|
-
run(repoRoot) {
|
|
525
|
-
if (!fileExists(repoRoot, "README.md")) return [];
|
|
526
|
-
const text = readText(repoRoot, "README.md");
|
|
527
|
-
const issues = [];
|
|
528
|
-
for (let i = 0; i < REQUIRED_SECTIONS3.length; i++) {
|
|
529
|
-
const pattern = REQUIRED_SECTIONS3[i];
|
|
530
|
-
const label = REQUIRED_LABELS[i];
|
|
531
|
-
if (pattern && !pattern.test(text)) {
|
|
532
|
-
issues.push({
|
|
533
|
-
linter: this.id,
|
|
534
|
-
severity: "error",
|
|
535
|
-
file: "README.md",
|
|
536
|
-
message: `missing required section: ${label}`
|
|
537
|
-
});
|
|
538
|
-
}
|
|
539
|
-
}
|
|
540
|
-
return issues;
|
|
541
|
-
}
|
|
542
|
-
};
|
|
543
|
-
|
|
544
|
-
// src/linters/spec-has-content.ts
|
|
545
|
-
var specHasContent = {
|
|
546
|
-
id: "lint:spec-has-content",
|
|
547
|
-
pillars: ["spec"],
|
|
548
|
-
defaultSeverity: "warning",
|
|
549
|
-
suggestedSkills: ["/spec"],
|
|
550
|
-
run(repoRoot) {
|
|
551
|
-
if (!dirExists(repoRoot, "docs/spec")) return [];
|
|
552
|
-
const files = listMarkdown(repoRoot, "docs/spec");
|
|
553
|
-
if (files.length > 0) return [];
|
|
554
|
-
return [
|
|
555
|
-
{
|
|
556
|
-
linter: this.id,
|
|
557
|
-
severity: "warning",
|
|
558
|
-
file: "docs/spec",
|
|
559
|
-
message: "docs/spec/ has no markdown files \u2014 write at least one spec document"
|
|
560
|
-
}
|
|
561
|
-
];
|
|
562
|
-
}
|
|
563
|
-
};
|
|
564
|
-
|
|
565
|
-
// src/linters/spec-tech-agnostic.ts
|
|
566
|
-
function maskFencedBlocks(text) {
|
|
567
|
-
return text.replace(/```[\s\S]*?```/g, (m) => m.replace(/[^\n]/g, " "));
|
|
568
|
-
}
|
|
569
|
-
var TECH_BLOCKLIST = [
|
|
570
|
-
{ pattern: /\bNext\.?js\b/i, keyword: "Next.js" },
|
|
571
|
-
{ pattern: /\bSupabase\b/i, keyword: "Supabase" },
|
|
572
|
-
{ pattern: /\bVercel\b/i, keyword: "Vercel" },
|
|
573
|
-
{ pattern: /\bReact\b/, keyword: "React" },
|
|
574
|
-
{ pattern: /\bTypeScript\b/, keyword: "TypeScript" },
|
|
575
|
-
{ pattern: /\bDocker\b/, keyword: "Docker" },
|
|
576
|
-
{ pattern: /\bKubernetes\b/i, keyword: "Kubernetes" },
|
|
577
|
-
{ pattern: /\bPostgres(QL)?\b/i, keyword: "Postgres" },
|
|
578
|
-
{ pattern: /\bMySQL\b/i, keyword: "MySQL" },
|
|
579
|
-
{ pattern: /\bRedis\b/i, keyword: "Redis" },
|
|
580
|
-
{ pattern: /\bnpm\b/, keyword: "npm" },
|
|
581
|
-
{ pattern: /\bpnpm\b/, keyword: "pnpm" },
|
|
582
|
-
{ pattern: /\byarn\b/, keyword: "yarn" }
|
|
583
|
-
];
|
|
584
|
-
var specTechAgnostic = {
|
|
585
|
-
id: "lint:spec-tech-agnostic",
|
|
586
|
-
pillars: ["spec"],
|
|
587
|
-
defaultSeverity: "error",
|
|
588
|
-
suggestedSkills: ["/spec"],
|
|
589
|
-
run(repoRoot) {
|
|
590
|
-
const issues = [];
|
|
591
|
-
const files = listMarkdown(repoRoot, "docs/spec");
|
|
592
|
-
for (const f of files) {
|
|
593
|
-
const text = maskFencedBlocks(readText(repoRoot, f));
|
|
594
|
-
for (const { pattern, keyword } of TECH_BLOCKLIST) {
|
|
595
|
-
if (pattern.test(text)) {
|
|
596
|
-
const issue = {
|
|
597
|
-
linter: this.id,
|
|
598
|
-
severity: "error",
|
|
599
|
-
file: f,
|
|
600
|
-
message: `forbidden tech keyword "${keyword}" \u2014 should be in handbook/ or decisions/`
|
|
601
|
-
};
|
|
602
|
-
const line = findLineNumber(text, pattern);
|
|
603
|
-
if (line !== void 0) issue.line = line;
|
|
604
|
-
issues.push(issue);
|
|
605
|
-
}
|
|
606
|
-
}
|
|
607
|
-
}
|
|
608
|
-
return issues;
|
|
609
|
-
}
|
|
610
|
-
};
|
|
611
|
-
|
|
612
|
-
// src/linters/tracks-drift.ts
|
|
613
|
-
import fg5 from "fast-glob";
|
|
614
|
-
var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
|
|
615
|
-
var DEFAULT_DRIFT_THRESHOLD = 10;
|
|
616
|
-
function expandGlob(repoRoot, pattern) {
|
|
617
|
-
if (pattern.includes("*")) {
|
|
618
|
-
return fg5.sync(pattern, { cwd: repoRoot, absolute: false });
|
|
619
|
-
}
|
|
620
|
-
return [pattern];
|
|
621
|
-
}
|
|
622
|
-
var tracksDrift = {
|
|
623
|
-
id: "lint:tracks-drift",
|
|
624
|
-
pillars: ["handbook", "tests", "workflow"],
|
|
625
|
-
defaultSeverity: "warning",
|
|
626
|
-
suggestedSkills: ["/drift", "/handbook"],
|
|
627
|
-
run(repoRoot) {
|
|
628
|
-
const issues = [];
|
|
629
|
-
for (const dir of TRACKED_DIRS2) {
|
|
630
|
-
const files = listMarkdown(repoRoot, dir);
|
|
631
|
-
for (const f of files) {
|
|
632
|
-
const text = readText(repoRoot, f);
|
|
633
|
-
const { data } = parseFrontmatter(text);
|
|
634
|
-
if (!Array.isArray(data.tracks)) continue;
|
|
635
|
-
const docCommit = gitLastCommitForPath(repoRoot, f);
|
|
636
|
-
if (!docCommit) continue;
|
|
637
|
-
const threshold = typeof data.driftThreshold === "number" && data.driftThreshold > 0 ? data.driftThreshold : DEFAULT_DRIFT_THRESHOLD;
|
|
638
|
-
let driftCount = 0;
|
|
639
|
-
for (const tracked of data.tracks) {
|
|
640
|
-
if (typeof tracked !== "string") continue;
|
|
641
|
-
const targets = expandGlob(repoRoot, tracked);
|
|
642
|
-
for (const t of targets.length > 0 ? targets : [tracked]) {
|
|
643
|
-
driftCount += gitCommitsSince(repoRoot, t, docCommit.hash);
|
|
644
|
-
}
|
|
645
|
-
}
|
|
646
|
-
if (driftCount > threshold) {
|
|
647
|
-
issues.push({
|
|
648
|
-
linter: this.id,
|
|
649
|
-
severity: "warning",
|
|
650
|
-
file: f,
|
|
651
|
-
message: `tracked files changed in ${driftCount} commits since doc last edit (threshold ${threshold})`
|
|
652
|
-
});
|
|
653
|
-
}
|
|
654
|
-
}
|
|
655
|
-
}
|
|
656
|
-
return issues;
|
|
657
|
-
}
|
|
658
|
-
};
|
|
359
|
+
// src/linters/generated-fresh.ts
|
|
360
|
+
import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
|
|
361
|
+
import { join as join8, resolve as resolve4 } from "path";
|
|
659
362
|
|
|
660
|
-
// src/
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
specHasContent,
|
|
672
|
-
crossLinks,
|
|
673
|
-
orphanDecisions,
|
|
674
|
-
gitignoreHarness,
|
|
675
|
-
qualitySchema
|
|
363
|
+
// src/cli/managed-paths.ts
|
|
364
|
+
import { lstatSync, realpathSync, statSync as statSync2 } from "fs";
|
|
365
|
+
import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join4, resolve as resolve2, win32 } from "path";
|
|
366
|
+
var MANAGED_FILES = /* @__PURE__ */ new Set(["AGENTS.md", "CLAUDE.md", ".harness-manifest.json"]);
|
|
367
|
+
var RELEASED_PATHS = [
|
|
368
|
+
".mcp.json",
|
|
369
|
+
".codex/config.toml",
|
|
370
|
+
".opencode/opencode.json",
|
|
371
|
+
".opencode/mcp.json",
|
|
372
|
+
".claude/settings.json",
|
|
373
|
+
".codex/hooks.json"
|
|
676
374
|
];
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
}
|
|
375
|
+
var MANAGED_DIRECTORIES = [
|
|
376
|
+
".claude/agents/",
|
|
377
|
+
".claude/commands/",
|
|
378
|
+
".claude/skills/",
|
|
379
|
+
".codex/agents/",
|
|
380
|
+
".codex/commands/",
|
|
381
|
+
".codex/skills/",
|
|
382
|
+
".agents/skills/",
|
|
383
|
+
".opencode/agents/",
|
|
384
|
+
".opencode/commands/",
|
|
385
|
+
".opencode/skills/",
|
|
386
|
+
".opencode/plugins/"
|
|
387
|
+
];
|
|
388
|
+
function canonicalTargetRoot(root) {
|
|
389
|
+
let ancestor = resolve2(root);
|
|
390
|
+
const missing = [];
|
|
391
|
+
while (!lstatSync(ancestor, { throwIfNoEntry: false })) {
|
|
392
|
+
missing.unshift(basename(ancestor));
|
|
393
|
+
ancestor = dirname2(ancestor);
|
|
697
394
|
}
|
|
698
|
-
const
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
issues
|
|
704
|
-
};
|
|
395
|
+
const canonical = realpathSync(ancestor);
|
|
396
|
+
if (!statSync2(canonical).isDirectory()) {
|
|
397
|
+
throw new Error(`harness target is not a directory: ${root}`);
|
|
398
|
+
}
|
|
399
|
+
return join4(canonical, ...missing);
|
|
705
400
|
}
|
|
706
|
-
function
|
|
707
|
-
const
|
|
708
|
-
|
|
401
|
+
function assertManagedLocation(path) {
|
|
402
|
+
const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
|
|
403
|
+
if (isAbsolute2(path) || win32.isAbsolute(path) || path.includes("\\") || path.includes("\0") || invalidSegment) {
|
|
404
|
+
throw new Error(`unsafe harness path: ${path}`);
|
|
405
|
+
}
|
|
406
|
+
if (!MANAGED_FILES.has(path) && !MANAGED_DIRECTORIES.some((prefix) => path.startsWith(prefix))) {
|
|
407
|
+
throw new Error(`path is outside harness-managed locations: ${path}`);
|
|
408
|
+
}
|
|
709
409
|
}
|
|
710
|
-
function
|
|
711
|
-
const
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
if (
|
|
718
|
-
|
|
410
|
+
function assertNoSymbolicComponents(root, path) {
|
|
411
|
+
const parts = path.split("/");
|
|
412
|
+
let current = root;
|
|
413
|
+
for (const [index, part] of parts.entries()) {
|
|
414
|
+
current = join4(current, part);
|
|
415
|
+
const info = lstatSync(current, { throwIfNoEntry: false });
|
|
416
|
+
if (!info) return;
|
|
417
|
+
if (info.isSymbolicLink()) {
|
|
418
|
+
throw new Error(`symbolic link in harness path: ${path}`);
|
|
419
|
+
}
|
|
420
|
+
const isLeaf = index === parts.length - 1;
|
|
421
|
+
if (isLeaf ? !info.isFile() : !info.isDirectory()) {
|
|
422
|
+
throw new Error(`unexpected file type in harness path: ${path}`);
|
|
719
423
|
}
|
|
720
424
|
}
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
);
|
|
726
|
-
return lines.join("\n");
|
|
425
|
+
}
|
|
426
|
+
function assertManagedPaths(root, files) {
|
|
427
|
+
for (const path of files) assertManagedLocation(path);
|
|
428
|
+
const canonicalRoot2 = canonicalTargetRoot(root);
|
|
429
|
+
for (const path of files) assertNoSymbolicComponents(canonicalRoot2, path);
|
|
727
430
|
}
|
|
728
431
|
|
|
432
|
+
// src/cli/manifest.ts
|
|
433
|
+
import { createHash } from "crypto";
|
|
434
|
+
import { chmodSync, existsSync as existsSync4, readFileSync as readFileSync2, writeFileSync } from "fs";
|
|
435
|
+
import { join as join5 } from "path";
|
|
436
|
+
import { z } from "zod";
|
|
437
|
+
|
|
729
438
|
// src/version.ts
|
|
730
|
-
var VERSION = "
|
|
439
|
+
var VERSION = "2.0.0";
|
|
731
440
|
|
|
732
|
-
// src/cli/
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
var
|
|
736
|
-
"
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
const lines = new Set(
|
|
758
|
-
text.split("\n").map((l) => l.trim()).filter(Boolean)
|
|
759
|
-
);
|
|
760
|
-
for (const entry of REQUIRED_GITIGNORE_ENTRIES) {
|
|
761
|
-
const variants = [entry, entry.replace(/\/$/, "")];
|
|
762
|
-
if (!variants.some((v) => lines.has(v))) {
|
|
763
|
-
issues.push(`.gitignore missing entry: ${entry}`);
|
|
764
|
-
}
|
|
765
|
-
}
|
|
766
|
-
}
|
|
767
|
-
return { pass: issues.length === 0, issues };
|
|
441
|
+
// src/cli/manifest.ts
|
|
442
|
+
var MANIFEST_FILENAME = ".harness-manifest.json";
|
|
443
|
+
var MANIFEST_VERSION = "6";
|
|
444
|
+
var ManifestSchema = z.object({
|
|
445
|
+
version: z.enum(["4", "5", MANIFEST_VERSION]),
|
|
446
|
+
engines: z.array(z.string()),
|
|
447
|
+
renderedAt: z.string(),
|
|
448
|
+
files: z.array(z.string()),
|
|
449
|
+
harnessVersion: z.string().optional(),
|
|
450
|
+
overridesDir: z.string().optional(),
|
|
451
|
+
fileHashes: z.record(z.string().regex(/^[a-f0-9]{64}$/)).optional(),
|
|
452
|
+
preservedFiles: z.array(z.string()).optional()
|
|
453
|
+
});
|
|
454
|
+
function manifestPath(targetDir) {
|
|
455
|
+
return join5(targetDir, MANIFEST_FILENAME);
|
|
456
|
+
}
|
|
457
|
+
function hashContent(content) {
|
|
458
|
+
return createHash("sha256").update(content).digest("hex");
|
|
459
|
+
}
|
|
460
|
+
function readManifest(targetDir) {
|
|
461
|
+
assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
|
|
462
|
+
const path = manifestPath(targetDir);
|
|
463
|
+
if (!existsSync4(path)) return null;
|
|
464
|
+
const raw = JSON.parse(readFileSync2(path, "utf8"));
|
|
465
|
+
return ManifestSchema.parse(raw);
|
|
768
466
|
}
|
|
769
467
|
|
|
770
|
-
// src/cli/
|
|
771
|
-
import { existsSync as
|
|
772
|
-
import { dirname as
|
|
468
|
+
// src/cli/plan-render.ts
|
|
469
|
+
import { existsSync as existsSync6 } from "fs";
|
|
470
|
+
import { dirname as dirname3, join as join7, resolve as resolve3 } from "path";
|
|
773
471
|
import { fileURLToPath } from "url";
|
|
774
472
|
|
|
775
473
|
// src/loader.ts
|
|
776
474
|
import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
|
|
777
|
-
import { join as
|
|
778
|
-
import
|
|
779
|
-
import { z as
|
|
475
|
+
import { join as join6 } from "path";
|
|
476
|
+
import fg4 from "fast-glob";
|
|
477
|
+
import { z as z3 } from "zod";
|
|
780
478
|
|
|
781
479
|
// src/parser/common.ts
|
|
782
480
|
import { readFileSync as readFileSync3 } from "fs";
|
|
783
481
|
import matter2 from "gray-matter";
|
|
784
482
|
|
|
785
483
|
// src/parser/schemas.ts
|
|
786
|
-
import { z } from "zod";
|
|
484
|
+
import { z as z2 } from "zod";
|
|
787
485
|
|
|
788
486
|
// src/types.ts
|
|
789
|
-
var AGENT_IDS = ["coding", "review", "merge", "planning"];
|
|
790
487
|
var ENGINES = ["claude-code", "codex-cli", "opencode"];
|
|
791
488
|
var CAPABILITIES = ["multi-step", "slash-command", "inline-exec"];
|
|
792
489
|
var CAPABILITIES_MATRIX = {
|
|
@@ -799,41 +496,36 @@ var DEGRADED_CAPABILITIES = {
|
|
|
799
496
|
};
|
|
800
497
|
|
|
801
498
|
// src/parser/schemas.ts
|
|
802
|
-
var IdSchema =
|
|
803
|
-
var SkillFrontmatterSchema =
|
|
499
|
+
var IdSchema = z2.string().min(1).regex(/^[a-z][a-z0-9-]*$/, "id must be kebab-case (lowercase + digits + hyphens)");
|
|
500
|
+
var SkillFrontmatterSchema = z2.object({
|
|
804
501
|
id: IdSchema,
|
|
805
|
-
description:
|
|
806
|
-
engines:
|
|
807
|
-
requires:
|
|
808
|
-
tags:
|
|
502
|
+
description: z2.string().min(1),
|
|
503
|
+
engines: z2.array(z2.enum(ENGINES)).min(1).optional(),
|
|
504
|
+
requires: z2.array(z2.enum(CAPABILITIES)).optional(),
|
|
505
|
+
tags: z2.array(z2.string()).optional()
|
|
809
506
|
}).strict();
|
|
810
|
-
var CmdArgEnumSchema =
|
|
811
|
-
name:
|
|
812
|
-
type:
|
|
813
|
-
values:
|
|
814
|
-
default:
|
|
507
|
+
var CmdArgEnumSchema = z2.object({
|
|
508
|
+
name: z2.string().min(1),
|
|
509
|
+
type: z2.literal("enum"),
|
|
510
|
+
values: z2.array(z2.string()).min(1),
|
|
511
|
+
default: z2.string().optional()
|
|
815
512
|
}).strict();
|
|
816
|
-
var CmdArgStringSchema =
|
|
817
|
-
name:
|
|
818
|
-
type:
|
|
819
|
-
default:
|
|
513
|
+
var CmdArgStringSchema = z2.object({
|
|
514
|
+
name: z2.string().min(1),
|
|
515
|
+
type: z2.literal("string"),
|
|
516
|
+
default: z2.string().optional()
|
|
820
517
|
}).strict();
|
|
821
|
-
var CmdArgSchema =
|
|
822
|
-
var CmdFrontmatterSchema =
|
|
518
|
+
var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
|
|
519
|
+
var CmdFrontmatterSchema = z2.object({
|
|
823
520
|
id: IdSchema,
|
|
824
|
-
trigger:
|
|
521
|
+
trigger: z2.string().regex(/^\/[a-z][a-z0-9-]*$/, "trigger must be /kebab-case"),
|
|
825
522
|
invokes_skill: IdSchema,
|
|
826
|
-
args:
|
|
827
|
-
description:
|
|
828
|
-
}).strict();
|
|
829
|
-
var AgentFrontmatterSchema = z.object({
|
|
830
|
-
id: z.enum(AGENT_IDS),
|
|
831
|
-
description: z.string().min(1)
|
|
523
|
+
args: z2.array(CmdArgSchema).optional(),
|
|
524
|
+
description: z2.string().min(1)
|
|
832
525
|
}).strict();
|
|
833
526
|
var Schemas = {
|
|
834
527
|
Skill: SkillFrontmatterSchema,
|
|
835
|
-
Cmd: CmdFrontmatterSchema
|
|
836
|
-
Agent: AgentFrontmatterSchema
|
|
528
|
+
Cmd: CmdFrontmatterSchema
|
|
837
529
|
};
|
|
838
530
|
var ParseError = class extends Error {
|
|
839
531
|
constructor(file, issues) {
|
|
@@ -862,11 +554,6 @@ function parseWithSchema(filePath, source, schema) {
|
|
|
862
554
|
};
|
|
863
555
|
}
|
|
864
556
|
|
|
865
|
-
// src/parser/agent.ts
|
|
866
|
-
function parseAgent(filePath, source) {
|
|
867
|
-
return parseWithSchema(filePath, source, Schemas.Agent);
|
|
868
|
-
}
|
|
869
|
-
|
|
870
557
|
// src/parser/cmd.ts
|
|
871
558
|
function parseCmd(filePath, source) {
|
|
872
559
|
return parseWithSchema(filePath, source, Schemas.Cmd);
|
|
@@ -884,35 +571,31 @@ function parseYAML(source) {
|
|
|
884
571
|
}
|
|
885
572
|
|
|
886
573
|
// src/loader.ts
|
|
887
|
-
var DisableYamlSchema =
|
|
574
|
+
var DisableYamlSchema = z3.object({ disable: z3.array(z3.string()).optional() }).passthrough();
|
|
888
575
|
function loadHarness(packageDir, opts = {}) {
|
|
889
|
-
const
|
|
890
|
-
const
|
|
891
|
-
const
|
|
892
|
-
const
|
|
893
|
-
const skillFiles = fg6.sync("*.skill.md", { cwd: skillsDir, absolute: true });
|
|
894
|
-
const cmdFiles = fg6.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
|
|
576
|
+
const skillsDir = opts.skillsDir ?? join6(packageDir, "skills");
|
|
577
|
+
const commandsDir = opts.commandsDir ?? join6(packageDir, "commands");
|
|
578
|
+
const skillFiles = fg4.sync("*.skill.md", { cwd: skillsDir, absolute: true });
|
|
579
|
+
const cmdFiles = fg4.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
|
|
895
580
|
return {
|
|
896
|
-
agents: agentFiles.map((f) => parseAgent(f, readFileSync4(f, "utf8"))),
|
|
897
581
|
skills: skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8"))),
|
|
898
582
|
cmds: cmdFiles.map((f) => parseCmd(f, readFileSync4(f, "utf8")))
|
|
899
583
|
};
|
|
900
584
|
}
|
|
901
585
|
function loadProjectSkills(targetDir) {
|
|
902
|
-
const skillsDir =
|
|
586
|
+
const skillsDir = join6(targetDir, "docs", "skills");
|
|
903
587
|
if (!existsSync5(skillsDir)) return [];
|
|
904
|
-
const skillFiles =
|
|
588
|
+
const skillFiles = fg4.sync("*.skill.md", { cwd: skillsDir, absolute: true });
|
|
905
589
|
return skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8")));
|
|
906
590
|
}
|
|
907
591
|
function loadOverrides(worktreeDir) {
|
|
908
|
-
const overridesDir =
|
|
592
|
+
const overridesDir = join6(worktreeDir, ".harness-overrides");
|
|
909
593
|
if (!existsSync5(overridesDir)) return void 0;
|
|
910
594
|
const added = loadHarness(overridesDir, {
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
commandsDir: join5(overridesDir, "commands")
|
|
595
|
+
skillsDir: join6(overridesDir, "skills"),
|
|
596
|
+
commandsDir: join6(overridesDir, "commands")
|
|
914
597
|
});
|
|
915
|
-
const disablePath =
|
|
598
|
+
const disablePath = join6(overridesDir, "disable.yaml");
|
|
916
599
|
let disable = [];
|
|
917
600
|
if (existsSync5(disablePath)) {
|
|
918
601
|
try {
|
|
@@ -926,28 +609,8 @@ function loadOverrides(worktreeDir) {
|
|
|
926
609
|
return { add: added, disable };
|
|
927
610
|
}
|
|
928
611
|
|
|
929
|
-
// src/mcp.ts
|
|
930
|
-
var MCP_SERVER_IDS = ["context7"];
|
|
931
|
-
var MCP_SERVERS = {
|
|
932
|
-
context7: {
|
|
933
|
-
id: "context7",
|
|
934
|
-
description: "Upstash Context7 \u2014 fetches up-to-date library docs via resolve-library-id + get-library-docs.",
|
|
935
|
-
command: "npx",
|
|
936
|
-
args: ["-y", "@upstash/context7-mcp"]
|
|
937
|
-
}
|
|
938
|
-
};
|
|
939
|
-
function resolveMcpIds(requested) {
|
|
940
|
-
return requested.map((id) => {
|
|
941
|
-
if (!MCP_SERVER_IDS.includes(id)) {
|
|
942
|
-
throw new Error(`unknown MCP server: ${id} (expected one of ${MCP_SERVER_IDS.join(", ")})`);
|
|
943
|
-
}
|
|
944
|
-
return id;
|
|
945
|
-
});
|
|
946
|
-
}
|
|
947
|
-
|
|
948
612
|
// src/renderers/common.ts
|
|
949
613
|
import { stringify as yamlStringify } from "yaml";
|
|
950
|
-
var STOP_HOOK_PACKAGE = "@vaubaan/harness";
|
|
951
614
|
function checkSkillCapabilities(skill, engine) {
|
|
952
615
|
const blockingWarnings = [];
|
|
953
616
|
const degradedWarnings = [];
|
|
@@ -978,39 +641,6 @@ ${rendered}
|
|
|
978
641
|
---
|
|
979
642
|
`;
|
|
980
643
|
}
|
|
981
|
-
var SCALAR_NEEDS_QUOTE = /[^a-zA-Z0-9_./-]/;
|
|
982
|
-
function tomlEscapeString(s) {
|
|
983
|
-
return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`;
|
|
984
|
-
}
|
|
985
|
-
function tomlValue(v) {
|
|
986
|
-
if (Array.isArray(v)) {
|
|
987
|
-
return `[${v.map((x) => tomlValue(x)).join(", ")}]`;
|
|
988
|
-
}
|
|
989
|
-
if (typeof v === "string") {
|
|
990
|
-
if (v.includes("\n")) return tomlEscapeString(v);
|
|
991
|
-
return SCALAR_NEEDS_QUOTE.test(v) ? tomlEscapeString(v) : `"${v}"`;
|
|
992
|
-
}
|
|
993
|
-
if (typeof v === "boolean" || typeof v === "number") {
|
|
994
|
-
return String(v);
|
|
995
|
-
}
|
|
996
|
-
return tomlEscapeString(String(v));
|
|
997
|
-
}
|
|
998
|
-
function tomlMultilineString(s) {
|
|
999
|
-
const escaped = s.replace(/\\/g, "\\\\").replace(/"""/g, '""\\"');
|
|
1000
|
-
return `"""
|
|
1001
|
-
${escaped}
|
|
1002
|
-
"""`;
|
|
1003
|
-
}
|
|
1004
|
-
function tomlQuoteString(s) {
|
|
1005
|
-
return tomlValue(s);
|
|
1006
|
-
}
|
|
1007
|
-
function tomlInlineArray(items) {
|
|
1008
|
-
return tomlValue([...items]);
|
|
1009
|
-
}
|
|
1010
|
-
function tomlInlineTable(table) {
|
|
1011
|
-
const entries = Object.entries(table).map(([k, v]) => `${k} = ${tomlValue(v)}`);
|
|
1012
|
-
return `{ ${entries.join(", ")} }`;
|
|
1013
|
-
}
|
|
1014
644
|
function frontmatterDataForSkill(skill) {
|
|
1015
645
|
const data = {
|
|
1016
646
|
name: skill.meta.id,
|
|
@@ -1035,11 +665,7 @@ function frontmatterDataForCmd(cmd) {
|
|
|
1035
665
|
}
|
|
1036
666
|
return data;
|
|
1037
667
|
}
|
|
1038
|
-
function
|
|
1039
|
-
return `${agent.body.trim()}
|
|
1040
|
-
`;
|
|
1041
|
-
}
|
|
1042
|
-
function buildUmbrellaBody(_agents, extras) {
|
|
668
|
+
function buildUmbrellaBody(extras) {
|
|
1043
669
|
const triggerBySkill = new Map(
|
|
1044
670
|
extras.availableCommands.map((c) => [c.meta.invokes_skill, c.meta.trigger])
|
|
1045
671
|
);
|
|
@@ -1060,7 +686,7 @@ function buildUmbrellaBody(_agents, extras) {
|
|
|
1060
686
|
"- `docs/handbook/<feature>.md` \u2014 *how it actually works* today.",
|
|
1061
687
|
"- `docs/decisions/<slug>.md` \u2014 ADRs: structural choices and rejected alternatives.",
|
|
1062
688
|
"- `docs/tests/integration-tests.md` & `e2e-tests.md` \u2014 core scenarios.",
|
|
1063
|
-
"- `docs/workflow/coding-workflow.md` \u2014 CI, branches, PR, release.",
|
|
689
|
+
"- `docs/workflow/coding-workflow.md` \u2014 CI, branches, PR, release. How this team works: follow it.",
|
|
1064
690
|
...extras.hasProjectSkills ? ["- `docs/skills/*.skill.md` \u2014 the project's domain skills."] : [],
|
|
1065
691
|
...extras.hasQualityDoc ? [
|
|
1066
692
|
"- `docs/quality/code-quality.md` \u2014 the project's code-quality rules: mechanical checks, judgment rules, accepted deviations. Read it before writing or auditing code."
|
|
@@ -1073,7 +699,13 @@ function buildUmbrellaBody(_agents, extras) {
|
|
|
1073
699
|
"- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
|
|
1074
700
|
"- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
|
|
1075
701
|
"- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
|
|
1076
|
-
"- Suspected code \u2194 doc drift \u2192 `/drift` before moving on."
|
|
702
|
+
"- Suspected code \u2194 doc drift \u2192 `/drift` before moving on.",
|
|
703
|
+
"",
|
|
704
|
+
"## Checks",
|
|
705
|
+
"",
|
|
706
|
+
"Run `npx @vaubaan/harness lint` before you commit; CI runs the same linters on every pull request. Fix what it reports with the skill it suggests.",
|
|
707
|
+
"",
|
|
708
|
+
"The files the harness generates (`AGENTS.md`, `CLAUDE.md`, the `.claude/`, `.agents/` and `.opencode/` folders, `.harness-manifest.json`) are committed. Never edit them by hand: change their source in `docs/` or `.harness-overrides/`, run `npx @vaubaan/harness update .`, and commit the result. The linter fails when a generated file no longer matches its render."
|
|
1077
709
|
];
|
|
1078
710
|
if (skillLines.length > 0) {
|
|
1079
711
|
sections.push("", "## Doc-skills", "", skillLines.join("\n"));
|
|
@@ -1114,60 +746,11 @@ ${cmd.body}
|
|
|
1114
746
|
files: [{ path: `${BASE}/commands/${cmd.meta.id}.md`, content }],
|
|
1115
747
|
warnings: []
|
|
1116
748
|
};
|
|
1117
|
-
},
|
|
1118
|
-
renderAgents(agents) {
|
|
1119
|
-
const files = [];
|
|
1120
|
-
for (const agent of agents) {
|
|
1121
|
-
const subagentFrontmatter = yamlFrontmatter({
|
|
1122
|
-
name: agent.meta.id,
|
|
1123
|
-
description: agent.meta.description
|
|
1124
|
-
});
|
|
1125
|
-
const body = buildAgentBody(agent);
|
|
1126
|
-
const content = `${subagentFrontmatter}
|
|
1127
|
-
${body}`;
|
|
1128
|
-
files.push({ path: `${BASE}/agents/${agent.meta.id}.md`, content });
|
|
1129
|
-
}
|
|
1130
|
-
return { files, warnings: [] };
|
|
1131
|
-
},
|
|
1132
|
-
renderMcp(servers) {
|
|
1133
|
-
if (servers.length === 0) return { files: [], warnings: [] };
|
|
1134
|
-
const mcpServers = {};
|
|
1135
|
-
for (const s of servers) {
|
|
1136
|
-
const entry = { command: s.command, args: [...s.args] };
|
|
1137
|
-
if (s.env) entry.env = s.env;
|
|
1138
|
-
mcpServers[s.id] = entry;
|
|
1139
|
-
}
|
|
1140
|
-
const content = `${JSON.stringify({ mcpServers }, null, 2)}
|
|
1141
|
-
`;
|
|
1142
|
-
return { files: [{ path: ".mcp.json", content }], warnings: [] };
|
|
1143
|
-
},
|
|
1144
|
-
renderStopHook() {
|
|
1145
|
-
const settings = {
|
|
1146
|
-
hooks: {
|
|
1147
|
-
Stop: [
|
|
1148
|
-
{
|
|
1149
|
-
matcher: "",
|
|
1150
|
-
hooks: [
|
|
1151
|
-
{
|
|
1152
|
-
type: "command",
|
|
1153
|
-
command: `npx -y ${STOP_HOOK_PACKAGE} stop-hook --engine claude`
|
|
1154
|
-
}
|
|
1155
|
-
]
|
|
1156
|
-
}
|
|
1157
|
-
]
|
|
1158
|
-
}
|
|
1159
|
-
};
|
|
1160
|
-
return {
|
|
1161
|
-
files: [{ path: `${BASE}/settings.json`, content: `${JSON.stringify(settings, null, 2)}
|
|
1162
|
-
` }],
|
|
1163
|
-
warnings: []
|
|
1164
|
-
};
|
|
1165
749
|
}
|
|
1166
750
|
};
|
|
1167
751
|
|
|
1168
752
|
// src/renderers/codex-cli.ts
|
|
1169
753
|
var ENGINE2 = "codex-cli";
|
|
1170
|
-
var BASE2 = ".codex";
|
|
1171
754
|
var SKILLS_BASE = ".agents/skills";
|
|
1172
755
|
var codexCliRenderer = {
|
|
1173
756
|
engine: ENGINE2,
|
|
@@ -1193,62 +776,12 @@ ${skill.body}
|
|
|
1193
776
|
// Codex custom prompts are deprecated in favour of skills: nothing to render.
|
|
1194
777
|
renderCmd(_cmd) {
|
|
1195
778
|
return { files: [], warnings: [] };
|
|
1196
|
-
},
|
|
1197
|
-
renderAgents(agents) {
|
|
1198
|
-
const files = [];
|
|
1199
|
-
for (const agent of agents) {
|
|
1200
|
-
const content = [
|
|
1201
|
-
`name = ${tomlQuoteString(agent.meta.id)}`,
|
|
1202
|
-
`description = ${tomlQuoteString(agent.meta.description)}`,
|
|
1203
|
-
`developer_instructions = ${tomlMultilineString(buildAgentBody(agent).trimEnd())}`,
|
|
1204
|
-
""
|
|
1205
|
-
].join("\n");
|
|
1206
|
-
files.push({ path: `${BASE2}/agents/${agent.meta.id}.toml`, content });
|
|
1207
|
-
}
|
|
1208
|
-
return { files, warnings: [] };
|
|
1209
|
-
},
|
|
1210
|
-
renderMcp(servers) {
|
|
1211
|
-
if (servers.length === 0) return { files: [], warnings: [] };
|
|
1212
|
-
const blocks = [];
|
|
1213
|
-
for (const s of servers) {
|
|
1214
|
-
const lines = [
|
|
1215
|
-
`[mcp_servers.${s.id}]`,
|
|
1216
|
-
`command = ${tomlQuoteString(s.command)}`,
|
|
1217
|
-
`args = ${tomlInlineArray([...s.args])}`
|
|
1218
|
-
];
|
|
1219
|
-
if (s.env) lines.push(`env = ${tomlInlineTable(s.env)}`);
|
|
1220
|
-
blocks.push(lines.join("\n"));
|
|
1221
|
-
}
|
|
1222
|
-
const content = `${blocks.join("\n\n")}
|
|
1223
|
-
`;
|
|
1224
|
-
return { files: [{ path: `${BASE2}/config.toml`, content }], warnings: [] };
|
|
1225
|
-
},
|
|
1226
|
-
renderStopHook() {
|
|
1227
|
-
const hooks = {
|
|
1228
|
-
hooks: {
|
|
1229
|
-
Stop: [
|
|
1230
|
-
{
|
|
1231
|
-
hooks: [
|
|
1232
|
-
{
|
|
1233
|
-
type: "command",
|
|
1234
|
-
command: `npx -y ${STOP_HOOK_PACKAGE} stop-hook --engine codex`
|
|
1235
|
-
}
|
|
1236
|
-
]
|
|
1237
|
-
}
|
|
1238
|
-
]
|
|
1239
|
-
}
|
|
1240
|
-
};
|
|
1241
|
-
return {
|
|
1242
|
-
files: [{ path: `${BASE2}/hooks.json`, content: `${JSON.stringify(hooks, null, 2)}
|
|
1243
|
-
` }],
|
|
1244
|
-
warnings: []
|
|
1245
|
-
};
|
|
1246
779
|
}
|
|
1247
780
|
};
|
|
1248
781
|
|
|
1249
782
|
// src/renderers/opencode.ts
|
|
1250
783
|
var ENGINE3 = "opencode";
|
|
1251
|
-
var
|
|
784
|
+
var BASE2 = ".opencode";
|
|
1252
785
|
var opencodeRenderer = {
|
|
1253
786
|
engine: ENGINE3,
|
|
1254
787
|
renderSkill(skill) {
|
|
@@ -1266,7 +799,7 @@ var opencodeRenderer = {
|
|
|
1266
799
|
${skill.body}
|
|
1267
800
|
`;
|
|
1268
801
|
return {
|
|
1269
|
-
files: [{ path: `${
|
|
802
|
+
files: [{ path: `${BASE2}/skills/${skill.meta.id}/SKILL.md`, content }],
|
|
1270
803
|
warnings: check.degradedWarnings
|
|
1271
804
|
};
|
|
1272
805
|
},
|
|
@@ -1275,106 +808,7 @@ ${skill.body}
|
|
|
1275
808
|
${cmd.body}
|
|
1276
809
|
`;
|
|
1277
810
|
return {
|
|
1278
|
-
files: [{ path: `${
|
|
1279
|
-
warnings: []
|
|
1280
|
-
};
|
|
1281
|
-
},
|
|
1282
|
-
renderAgents(agents) {
|
|
1283
|
-
const files = [];
|
|
1284
|
-
for (const agent of agents) {
|
|
1285
|
-
const fm = yamlFrontmatter({
|
|
1286
|
-
description: agent.meta.description,
|
|
1287
|
-
mode: "all"
|
|
1288
|
-
});
|
|
1289
|
-
const body = buildAgentBody(agent);
|
|
1290
|
-
files.push({ path: `${BASE3}/agents/${agent.meta.id}.md`, content: `${fm}
|
|
1291
|
-
${body}` });
|
|
1292
|
-
}
|
|
1293
|
-
return { files, warnings: [] };
|
|
1294
|
-
},
|
|
1295
|
-
renderMcp(servers) {
|
|
1296
|
-
if (servers.length === 0) return { files: [], warnings: [] };
|
|
1297
|
-
const mcp = {};
|
|
1298
|
-
for (const s of servers) {
|
|
1299
|
-
const entry = {
|
|
1300
|
-
type: "local",
|
|
1301
|
-
command: [s.command, ...s.args],
|
|
1302
|
-
enabled: true
|
|
1303
|
-
};
|
|
1304
|
-
if (s.env) entry.environment = s.env;
|
|
1305
|
-
mcp[s.id] = entry;
|
|
1306
|
-
}
|
|
1307
|
-
const config = { $schema: "https://opencode.ai/config.json", mcp };
|
|
1308
|
-
const content = `${JSON.stringify(config, null, 2)}
|
|
1309
|
-
`;
|
|
1310
|
-
return { files: [{ path: `${BASE3}/opencode.json`, content }], warnings: [] };
|
|
1311
|
-
},
|
|
1312
|
-
renderStopHook() {
|
|
1313
|
-
const content = `import { spawnSync } from "node:child_process";
|
|
1314
|
-
|
|
1315
|
-
// Runs the harness lint and returns the report to inject, or "" when the
|
|
1316
|
-
// turn may end.
|
|
1317
|
-
const lintReport = (directory, sessionID) => {
|
|
1318
|
-
const r = spawnSync(
|
|
1319
|
-
"npx",
|
|
1320
|
-
["-y", "${STOP_HOOK_PACKAGE}", "stop-hook", "--engine", "opencode", "--cwd", directory],
|
|
1321
|
-
{ input: JSON.stringify({ sessionID }), encoding: "utf-8" },
|
|
1322
|
-
);
|
|
1323
|
-
const report = (r.stderr ?? "").trim();
|
|
1324
|
-
return r.status === 2 ? report : "";
|
|
1325
|
-
};
|
|
1326
|
-
|
|
1327
|
-
// OpenCode 1.x entry point, exposed as server() below.
|
|
1328
|
-
const HarnessStopHook = async ({ client, directory }) => ({
|
|
1329
|
-
event: async ({ event }) => {
|
|
1330
|
-
if (event.type !== "session.idle") return;
|
|
1331
|
-
const sessionID = event.properties?.sessionID;
|
|
1332
|
-
if (!sessionID) return;
|
|
1333
|
-
const report = lintReport(directory, sessionID);
|
|
1334
|
-
if (report === "") return;
|
|
1335
|
-
// OpenCode defaults to its build agent when a prompt omits agent.
|
|
1336
|
-
// Preserve the last conversation persona, excluding compaction summaries.
|
|
1337
|
-
const history = await client.session.messages({ path: { id: sessionID } }).catch(() => undefined);
|
|
1338
|
-
if (history?.error || !Array.isArray(history?.data)) return;
|
|
1339
|
-
const current = history.data.findLast(({ info }) =>
|
|
1340
|
-
(info.role === "user" || (info.role === "assistant" && !info.summary)) &&
|
|
1341
|
-
typeof info.agent === "string" && info.agent.trim() !== "",
|
|
1342
|
-
);
|
|
1343
|
-
if (!current) return;
|
|
1344
|
-
await client.session.prompt({
|
|
1345
|
-
path: { id: sessionID },
|
|
1346
|
-
body: { agent: current.info.agent, parts: [{ type: "text", text: report }] },
|
|
1347
|
-
});
|
|
1348
|
-
},
|
|
1349
|
-
});
|
|
1350
|
-
|
|
1351
|
-
// One default export for both majors: OpenCode 1.x calls server(),
|
|
1352
|
-
// OpenCode 2.x calls setup(). A V2 session keeps its agent, so the report
|
|
1353
|
-
// is sent without naming the persona.
|
|
1354
|
-
export default {
|
|
1355
|
-
id: "vaubaan-harness-stop-hook",
|
|
1356
|
-
server: HarnessStopHook,
|
|
1357
|
-
setup(context) {
|
|
1358
|
-
const directory = context.location.directory;
|
|
1359
|
-
const controller = new AbortController();
|
|
1360
|
-
const listen = async () => {
|
|
1361
|
-
for await (const event of context.event.subscribe({ signal: controller.signal })) {
|
|
1362
|
-
if (event.type !== "session.idle") continue;
|
|
1363
|
-
if (event.location?.directory && event.location.directory !== directory) continue;
|
|
1364
|
-
const sessionID = event.data?.sessionID;
|
|
1365
|
-
if (!sessionID) continue;
|
|
1366
|
-
const report = lintReport(directory, sessionID);
|
|
1367
|
-
if (report === "") continue;
|
|
1368
|
-
await context.session.prompt({ sessionID, text: report }).catch(() => undefined);
|
|
1369
|
-
}
|
|
1370
|
-
};
|
|
1371
|
-
listen().catch(() => undefined);
|
|
1372
|
-
return () => controller.abort();
|
|
1373
|
-
},
|
|
1374
|
-
};
|
|
1375
|
-
`;
|
|
1376
|
-
return {
|
|
1377
|
-
files: [{ path: `${BASE3}/plugins/harness-stop-hook.ts`, content }],
|
|
811
|
+
files: [{ path: `${BASE2}/commands/${cmd.meta.id}.md`, content }],
|
|
1378
812
|
warnings: []
|
|
1379
813
|
};
|
|
1380
814
|
}
|
|
@@ -1413,7 +847,6 @@ function removeByIds(items, disabled) {
|
|
|
1413
847
|
function applyOverrides(harness, overrides) {
|
|
1414
848
|
const disabled = overrides?.disable ?? [];
|
|
1415
849
|
return {
|
|
1416
|
-
agents: removeByIds(mergeById(harness.agents, overrides?.add?.agents), disabled),
|
|
1417
850
|
skills: removeByIds(mergeById(harness.skills, overrides?.add?.skills), disabled),
|
|
1418
851
|
cmds: removeByIds(mergeById(harness.cmds, overrides?.add?.cmds), disabled)
|
|
1419
852
|
};
|
|
@@ -1429,58 +862,37 @@ function render(input) {
|
|
|
1429
862
|
}
|
|
1430
863
|
const base = input.projectSkills?.length ? { ...input.harness, skills: mergeById(input.harness.skills, input.projectSkills) } : input.harness;
|
|
1431
864
|
const harness = applyOverrides(base, input.overrides);
|
|
1432
|
-
if (harness.agents.length === 0) {
|
|
1433
|
-
throw new RenderError("No agents found in harness");
|
|
1434
|
-
}
|
|
1435
865
|
const files = [];
|
|
1436
866
|
const warnings = [];
|
|
1437
867
|
const exposedSkills = /* @__PURE__ */ new Map();
|
|
1438
868
|
const exposedCmds = /* @__PURE__ */ new Map();
|
|
1439
869
|
for (const engine of opencodeLast(engines)) {
|
|
1440
870
|
const renderer = getRenderer(engine);
|
|
1441
|
-
const
|
|
871
|
+
const renderedSkillIds = /* @__PURE__ */ new Set();
|
|
1442
872
|
for (const skill of harness.skills) {
|
|
1443
873
|
const result = renderer.renderSkill(skill);
|
|
1444
874
|
warnings.push(...result.warnings);
|
|
1445
875
|
if (result.files.length > 0) {
|
|
1446
876
|
const alreadyVisible = engine === "opencode" && exposedSkills.has(skill.meta.id);
|
|
1447
877
|
if (!alreadyVisible) files.push(...result.files);
|
|
1448
|
-
|
|
878
|
+
renderedSkillIds.add(skill.meta.id);
|
|
1449
879
|
exposedSkills.set(skill.meta.id, skill);
|
|
1450
880
|
}
|
|
1451
881
|
}
|
|
1452
|
-
const renderedSkillIds = new Set(renderedSkills.map((s) => s.meta.id));
|
|
1453
|
-
const renderedCmds = [];
|
|
1454
882
|
for (const cmd of harness.cmds) {
|
|
1455
883
|
if (!renderedSkillIds.has(cmd.meta.invokes_skill)) continue;
|
|
1456
884
|
const result = renderer.renderCmd(cmd);
|
|
1457
885
|
warnings.push(...result.warnings);
|
|
1458
886
|
if (result.files.length > 0) {
|
|
1459
887
|
files.push(...result.files);
|
|
1460
|
-
renderedCmds.push(cmd);
|
|
1461
888
|
exposedCmds.set(cmd.meta.id, cmd);
|
|
1462
889
|
}
|
|
1463
890
|
}
|
|
1464
|
-
const agentsResult = renderer.renderAgents(harness.agents);
|
|
1465
|
-
warnings.push(...agentsResult.warnings);
|
|
1466
|
-
files.push(...agentsResult.files);
|
|
1467
|
-
if (input.mcpServers && input.mcpServers.length > 0) {
|
|
1468
|
-
const specs = input.mcpServers.map((id) => MCP_SERVERS[id]);
|
|
1469
|
-
const mcpResult = renderer.renderMcp(specs);
|
|
1470
|
-
warnings.push(...mcpResult.warnings);
|
|
1471
|
-
files.push(...mcpResult.files);
|
|
1472
|
-
}
|
|
1473
|
-
if (input.withStopHook !== false) {
|
|
1474
|
-
const hookResult = renderer.renderStopHook();
|
|
1475
|
-
warnings.push(...hookResult.warnings);
|
|
1476
|
-
files.push(...hookResult.files);
|
|
1477
|
-
}
|
|
1478
891
|
}
|
|
1479
|
-
const
|
|
1480
|
-
const umbrellaContent = buildUmbrellaBody(harness.agents, {
|
|
892
|
+
const umbrellaContent = buildUmbrellaBody({
|
|
1481
893
|
availableSkills: Array.from(exposedSkills.values()),
|
|
1482
894
|
availableCommands: Array.from(exposedCmds.values()),
|
|
1483
|
-
hasProjectSkills,
|
|
895
|
+
hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
|
|
1484
896
|
hasQualityDoc: input.hasQualityDoc === true
|
|
1485
897
|
});
|
|
1486
898
|
files.push({ path: "AGENTS.md", content: umbrellaContent });
|
|
@@ -1490,479 +902,538 @@ function render(input) {
|
|
|
1490
902
|
return { files, warnings };
|
|
1491
903
|
}
|
|
1492
904
|
|
|
1493
|
-
// src/cli/
|
|
1494
|
-
|
|
1495
|
-
|
|
1496
|
-
|
|
905
|
+
// src/cli/plan-render.ts
|
|
906
|
+
var QUALITY_DOC_PATH = "docs/quality/code-quality.md";
|
|
907
|
+
function resolveEngineList(requested) {
|
|
908
|
+
if (!requested || requested.length === 0) {
|
|
909
|
+
throw new Error(
|
|
910
|
+
`no engine selected: pass --engines=<list> with one or more of ${ENGINES.join(", ")}`
|
|
911
|
+
);
|
|
912
|
+
}
|
|
913
|
+
const engines = requested.map((e) => {
|
|
914
|
+
if (!ENGINES.includes(e)) {
|
|
915
|
+
throw new Error(`unknown engine: ${e} (expected one of ${ENGINES.join(", ")})`);
|
|
916
|
+
}
|
|
917
|
+
return e;
|
|
918
|
+
});
|
|
919
|
+
return [...new Set(engines)];
|
|
920
|
+
}
|
|
921
|
+
function defaultPackageDir() {
|
|
922
|
+
const here = dirname3(fileURLToPath(import.meta.url));
|
|
923
|
+
if (existsSync6(join7(here, "skills"))) return here;
|
|
924
|
+
return resolve3(here, "..");
|
|
925
|
+
}
|
|
926
|
+
function planInit(args) {
|
|
927
|
+
const engines = resolveEngineList(args.engines);
|
|
928
|
+
const packageDir = args.packageDir ?? defaultPackageDir();
|
|
929
|
+
const harness = loadHarness(packageDir);
|
|
930
|
+
const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
|
|
931
|
+
const projectSkills = loadProjectSkills(args.targetDir);
|
|
932
|
+
const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
|
|
933
|
+
const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc });
|
|
934
|
+
return { engines, output };
|
|
935
|
+
}
|
|
936
|
+
|
|
937
|
+
// src/linters/generated-fresh.ts
|
|
938
|
+
var FIX = "run `npx @vaubaan/harness update .` and commit the result";
|
|
939
|
+
var generatedFresh = {
|
|
940
|
+
id: "lint:generated-fresh",
|
|
941
|
+
pillars: ["repo-root"],
|
|
942
|
+
defaultSeverity: "error",
|
|
943
|
+
run(repoRoot) {
|
|
944
|
+
const issue = (file, message) => ({
|
|
945
|
+
linter: this.id,
|
|
946
|
+
severity: "error",
|
|
947
|
+
file,
|
|
948
|
+
message
|
|
949
|
+
});
|
|
950
|
+
let manifest;
|
|
951
|
+
try {
|
|
952
|
+
manifest = readManifest(repoRoot);
|
|
953
|
+
} catch (error) {
|
|
954
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
955
|
+
return [issue(".harness-manifest.json", `invalid harness manifest: ${reason}`)];
|
|
956
|
+
}
|
|
957
|
+
if (!manifest) return [];
|
|
958
|
+
const overridesParent = manifest.overridesDir ? resolve4(repoRoot, manifest.overridesDir) : repoRoot;
|
|
959
|
+
const hasOverrides = existsSync7(join8(overridesParent, ".harness-overrides"));
|
|
960
|
+
let rendered;
|
|
961
|
+
try {
|
|
962
|
+
rendered = planInit({
|
|
963
|
+
targetDir: repoRoot,
|
|
964
|
+
engines: manifest.engines,
|
|
965
|
+
overridesDir: hasOverrides ? overridesParent : void 0
|
|
966
|
+
});
|
|
967
|
+
} catch (error) {
|
|
968
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
969
|
+
return [issue(".harness-manifest.json", `cannot render the harness: ${reason}`)];
|
|
970
|
+
}
|
|
971
|
+
const preserved = new Set(manifest.preservedFiles ?? []);
|
|
972
|
+
const issues = [];
|
|
973
|
+
const renderedPaths = /* @__PURE__ */ new Set();
|
|
974
|
+
for (const file of rendered.output.files) {
|
|
975
|
+
if (preserved.has(file.path)) continue;
|
|
976
|
+
renderedPaths.add(file.path);
|
|
977
|
+
const full = join8(repoRoot, file.path);
|
|
978
|
+
if (!existsSync7(full)) {
|
|
979
|
+
issues.push(issue(file.path, `generated file is missing; ${FIX}`));
|
|
980
|
+
} else if (readFileSync5(full, "utf8") !== file.content) {
|
|
981
|
+
issues.push(
|
|
982
|
+
issue(
|
|
983
|
+
file.path,
|
|
984
|
+
`generated file differs from the current render; edit its source in docs/ or .harness-overrides/, then ${FIX}`
|
|
985
|
+
)
|
|
986
|
+
);
|
|
987
|
+
}
|
|
988
|
+
}
|
|
989
|
+
for (const path of manifest.files) {
|
|
990
|
+
if (renderedPaths.has(path) || preserved.has(path) || RELEASED_PATHS.includes(path)) continue;
|
|
991
|
+
if (existsSync7(join8(repoRoot, path))) {
|
|
992
|
+
issues.push(issue(path, `stale generated file, no longer rendered; ${FIX}`));
|
|
993
|
+
}
|
|
994
|
+
}
|
|
995
|
+
return issues;
|
|
996
|
+
}
|
|
997
|
+
};
|
|
998
|
+
|
|
999
|
+
// src/linters/gitignore-harness.ts
|
|
1000
|
+
var REQUIRED_GITIGNORE_ENTRIES = [
|
|
1001
|
+
".harness-overrides/",
|
|
1002
|
+
".vaubaan/"
|
|
1003
|
+
];
|
|
1004
|
+
var FORBIDDEN_GITIGNORE_ENTRIES = [
|
|
1497
1005
|
"AGENTS.md",
|
|
1498
1006
|
"CLAUDE.md",
|
|
1499
|
-
".
|
|
1500
|
-
".
|
|
1501
|
-
".
|
|
1502
|
-
".
|
|
1503
|
-
".
|
|
1504
|
-
".opencode/opencode.json",
|
|
1505
|
-
".opencode/mcp.json"
|
|
1506
|
-
]);
|
|
1507
|
-
var MANAGED_DIRECTORIES = [
|
|
1508
|
-
".claude/agents/",
|
|
1509
|
-
".claude/commands/",
|
|
1510
|
-
".claude/skills/",
|
|
1511
|
-
".codex/agents/",
|
|
1512
|
-
".codex/commands/",
|
|
1513
|
-
".codex/skills/",
|
|
1514
|
-
".agents/skills/",
|
|
1515
|
-
".opencode/agents/",
|
|
1516
|
-
".opencode/commands/",
|
|
1517
|
-
".opencode/skills/",
|
|
1518
|
-
".opencode/plugins/"
|
|
1007
|
+
".claude/",
|
|
1008
|
+
".codex/",
|
|
1009
|
+
".agents/",
|
|
1010
|
+
".opencode/",
|
|
1011
|
+
".harness-manifest.json"
|
|
1519
1012
|
];
|
|
1520
|
-
function
|
|
1521
|
-
|
|
1522
|
-
const
|
|
1523
|
-
|
|
1524
|
-
|
|
1525
|
-
|
|
1526
|
-
}
|
|
1527
|
-
const canonical = realpathSync(ancestor);
|
|
1528
|
-
if (!statSync2(canonical).isDirectory()) {
|
|
1529
|
-
throw new Error(`harness target is not a directory: ${root}`);
|
|
1013
|
+
function gitignoreEntries(text) {
|
|
1014
|
+
const entries = /* @__PURE__ */ new Set();
|
|
1015
|
+
for (const raw of text.split("\n")) {
|
|
1016
|
+
const line = raw.trim();
|
|
1017
|
+
if (!line || line.startsWith("#")) continue;
|
|
1018
|
+
entries.add(line.replace(/^\//, "").replace(/\/$/, ""));
|
|
1530
1019
|
}
|
|
1531
|
-
return
|
|
1020
|
+
return entries;
|
|
1532
1021
|
}
|
|
1533
|
-
function
|
|
1534
|
-
|
|
1535
|
-
|
|
1536
|
-
|
|
1022
|
+
function normalize(entry) {
|
|
1023
|
+
return entry.replace(/\/$/, "");
|
|
1024
|
+
}
|
|
1025
|
+
function missingGitignoreEntries(text) {
|
|
1026
|
+
const lines = gitignoreEntries(text);
|
|
1027
|
+
return REQUIRED_GITIGNORE_ENTRIES.filter((entry) => !lines.has(normalize(entry)));
|
|
1028
|
+
}
|
|
1029
|
+
function forbiddenGitignoreEntries(text) {
|
|
1030
|
+
const lines = gitignoreEntries(text);
|
|
1031
|
+
return FORBIDDEN_GITIGNORE_ENTRIES.filter((entry) => lines.has(normalize(entry)));
|
|
1032
|
+
}
|
|
1033
|
+
var gitignoreHarness = {
|
|
1034
|
+
id: "lint:gitignore-harness",
|
|
1035
|
+
pillars: ["repo-root"],
|
|
1036
|
+
defaultSeverity: "error",
|
|
1037
|
+
run(repoRoot) {
|
|
1038
|
+
if (!fileExists(repoRoot, ".gitignore")) {
|
|
1039
|
+
return [
|
|
1040
|
+
{
|
|
1041
|
+
linter: this.id,
|
|
1042
|
+
severity: "error",
|
|
1043
|
+
file: ".gitignore",
|
|
1044
|
+
message: ".gitignore is missing at repo root"
|
|
1045
|
+
}
|
|
1046
|
+
];
|
|
1047
|
+
}
|
|
1048
|
+
const text = readText(repoRoot, ".gitignore");
|
|
1049
|
+
const issues = [];
|
|
1050
|
+
for (const entry of missingGitignoreEntries(text)) {
|
|
1051
|
+
issues.push({
|
|
1052
|
+
linter: this.id,
|
|
1053
|
+
severity: "error",
|
|
1054
|
+
file: ".gitignore",
|
|
1055
|
+
message: `.gitignore must contain "${entry}"`
|
|
1056
|
+
});
|
|
1057
|
+
}
|
|
1058
|
+
for (const entry of forbiddenGitignoreEntries(text)) {
|
|
1059
|
+
issues.push({
|
|
1060
|
+
linter: this.id,
|
|
1061
|
+
severity: "error",
|
|
1062
|
+
file: ".gitignore",
|
|
1063
|
+
message: `.gitignore must not contain "${entry}": files the harness generates are committed`
|
|
1064
|
+
});
|
|
1065
|
+
}
|
|
1066
|
+
return issues;
|
|
1537
1067
|
}
|
|
1538
|
-
|
|
1539
|
-
|
|
1068
|
+
};
|
|
1069
|
+
|
|
1070
|
+
// src/linters/orphan-decisions.ts
|
|
1071
|
+
import { basename as basename2 } from "path";
|
|
1072
|
+
import fg5 from "fast-glob";
|
|
1073
|
+
var orphanDecisions = {
|
|
1074
|
+
id: "lint:orphan-decisions",
|
|
1075
|
+
pillars: ["decisions"],
|
|
1076
|
+
defaultSeverity: "warning",
|
|
1077
|
+
suggestedSkills: ["/handbook"],
|
|
1078
|
+
run(repoRoot, ctx) {
|
|
1079
|
+
const extra = ctx?.config.ignore ?? [];
|
|
1080
|
+
const issues = [];
|
|
1081
|
+
const adrs = listMarkdown(repoRoot, "docs/decisions");
|
|
1082
|
+
if (adrs.length === 0) return issues;
|
|
1083
|
+
const otherDocs = fg5.sync("**/*.md", {
|
|
1084
|
+
cwd: repoRoot,
|
|
1085
|
+
absolute: false,
|
|
1086
|
+
ignore: [
|
|
1087
|
+
"**/node_modules/**",
|
|
1088
|
+
"**/dist/**",
|
|
1089
|
+
".harness-overrides/**",
|
|
1090
|
+
"docs/decisions/**",
|
|
1091
|
+
"skills/**",
|
|
1092
|
+
"agents/**",
|
|
1093
|
+
"commands/**",
|
|
1094
|
+
"templates/**",
|
|
1095
|
+
...extra
|
|
1096
|
+
]
|
|
1097
|
+
});
|
|
1098
|
+
const referenceCorpus = otherDocs.map((f) => readText(repoRoot, f)).join("\n");
|
|
1099
|
+
for (const adr of adrs) {
|
|
1100
|
+
const filename = basename2(adr);
|
|
1101
|
+
const stem = filename.replace(/\.md$/, "");
|
|
1102
|
+
const referenced = referenceCorpus.includes(filename) || referenceCorpus.includes(stem);
|
|
1103
|
+
if (!referenced) {
|
|
1104
|
+
issues.push({
|
|
1105
|
+
linter: this.id,
|
|
1106
|
+
severity: "warning",
|
|
1107
|
+
file: adr,
|
|
1108
|
+
message: "ADR is not referenced by any other doc file (orphan)"
|
|
1109
|
+
});
|
|
1110
|
+
}
|
|
1111
|
+
}
|
|
1112
|
+
return issues;
|
|
1113
|
+
}
|
|
1114
|
+
};
|
|
1115
|
+
|
|
1116
|
+
// src/linters/quality-schema.ts
|
|
1117
|
+
var QUALITY_DIR = "docs/quality";
|
|
1118
|
+
var CARDINAL_FILE = `${QUALITY_DIR}/code-quality.md`;
|
|
1119
|
+
var REQUIRED_SECTIONS2 = [
|
|
1120
|
+
{
|
|
1121
|
+
label: "Mechanical checks",
|
|
1122
|
+
pattern: /^##\s+(Mechanical\s+checks|V[ée]rifications\s+m[ée]caniques)\s*$/im
|
|
1123
|
+
},
|
|
1124
|
+
{ label: "Project rules", pattern: /^##\s+(Project\s+rules|R[èe]gles\s+du\s+projet)\s*$/im },
|
|
1125
|
+
{
|
|
1126
|
+
label: "Accepted deviations",
|
|
1127
|
+
pattern: /^##\s+(Accepted\s+deviations|[ÉE]carts\s+assum[ée]s)\s*$/im
|
|
1128
|
+
}
|
|
1129
|
+
];
|
|
1130
|
+
var qualitySchema = {
|
|
1131
|
+
id: "lint:quality-schema",
|
|
1132
|
+
pillars: ["quality"],
|
|
1133
|
+
defaultSeverity: "error",
|
|
1134
|
+
run(repoRoot) {
|
|
1135
|
+
if (!dirExists(repoRoot, QUALITY_DIR)) return [];
|
|
1136
|
+
if (!fileExists(repoRoot, CARDINAL_FILE)) {
|
|
1137
|
+
return [
|
|
1138
|
+
{
|
|
1139
|
+
linter: this.id,
|
|
1140
|
+
severity: "error",
|
|
1141
|
+
file: CARDINAL_FILE,
|
|
1142
|
+
message: `missing required cardinal file: ${CARDINAL_FILE}`
|
|
1143
|
+
}
|
|
1144
|
+
];
|
|
1145
|
+
}
|
|
1146
|
+
const text = readText(repoRoot, CARDINAL_FILE);
|
|
1147
|
+
return REQUIRED_SECTIONS2.filter(({ pattern }) => !pattern.test(text)).map(({ label }) => ({
|
|
1148
|
+
linter: this.id,
|
|
1149
|
+
severity: "error",
|
|
1150
|
+
file: CARDINAL_FILE,
|
|
1151
|
+
message: `missing required section: "${label}"`
|
|
1152
|
+
}));
|
|
1153
|
+
}
|
|
1154
|
+
};
|
|
1155
|
+
|
|
1156
|
+
// src/linters/readme-presence.ts
|
|
1157
|
+
var readmePresence = {
|
|
1158
|
+
id: "lint:readme-presence",
|
|
1159
|
+
pillars: ["readme"],
|
|
1160
|
+
defaultSeverity: "error",
|
|
1161
|
+
suggestedSkills: ["/readme"],
|
|
1162
|
+
run(repoRoot) {
|
|
1163
|
+
if (fileExists(repoRoot, "README.md")) return [];
|
|
1164
|
+
return [
|
|
1165
|
+
{
|
|
1166
|
+
linter: this.id,
|
|
1167
|
+
severity: "error",
|
|
1168
|
+
file: "README.md",
|
|
1169
|
+
message: "README.md is missing at repo root"
|
|
1170
|
+
}
|
|
1171
|
+
];
|
|
1172
|
+
}
|
|
1173
|
+
};
|
|
1174
|
+
|
|
1175
|
+
// src/linters/readme-sections.ts
|
|
1176
|
+
var REQUIRED_SECTIONS3 = [
|
|
1177
|
+
/^#\s+\S/m,
|
|
1178
|
+
/^##?\s+(What is this|Quick start)/im,
|
|
1179
|
+
/^##?\s+(Quick start|Install|Getting started)/im
|
|
1180
|
+
];
|
|
1181
|
+
var REQUIRED_LABELS = ["title (# H1)", "What is this / intro", "Quick start / Install"];
|
|
1182
|
+
var readmeSections = {
|
|
1183
|
+
id: "lint:readme-sections",
|
|
1184
|
+
pillars: ["readme"],
|
|
1185
|
+
defaultSeverity: "error",
|
|
1186
|
+
suggestedSkills: ["/readme"],
|
|
1187
|
+
run(repoRoot) {
|
|
1188
|
+
if (!fileExists(repoRoot, "README.md")) return [];
|
|
1189
|
+
const text = readText(repoRoot, "README.md");
|
|
1190
|
+
const issues = [];
|
|
1191
|
+
for (let i = 0; i < REQUIRED_SECTIONS3.length; i++) {
|
|
1192
|
+
const pattern = REQUIRED_SECTIONS3[i];
|
|
1193
|
+
const label = REQUIRED_LABELS[i];
|
|
1194
|
+
if (pattern && !pattern.test(text)) {
|
|
1195
|
+
issues.push({
|
|
1196
|
+
linter: this.id,
|
|
1197
|
+
severity: "error",
|
|
1198
|
+
file: "README.md",
|
|
1199
|
+
message: `missing required section: ${label}`
|
|
1200
|
+
});
|
|
1201
|
+
}
|
|
1202
|
+
}
|
|
1203
|
+
return issues;
|
|
1204
|
+
}
|
|
1205
|
+
};
|
|
1206
|
+
|
|
1207
|
+
// src/linters/spec-has-content.ts
|
|
1208
|
+
var specHasContent = {
|
|
1209
|
+
id: "lint:spec-has-content",
|
|
1210
|
+
pillars: ["spec"],
|
|
1211
|
+
defaultSeverity: "warning",
|
|
1212
|
+
suggestedSkills: ["/spec"],
|
|
1213
|
+
run(repoRoot) {
|
|
1214
|
+
if (!dirExists(repoRoot, "docs/spec")) return [];
|
|
1215
|
+
const files = listMarkdown(repoRoot, "docs/spec");
|
|
1216
|
+
if (files.length > 0) return [];
|
|
1217
|
+
return [
|
|
1218
|
+
{
|
|
1219
|
+
linter: this.id,
|
|
1220
|
+
severity: "warning",
|
|
1221
|
+
file: "docs/spec",
|
|
1222
|
+
message: "docs/spec/ has no markdown files \u2014 write at least one spec document"
|
|
1223
|
+
}
|
|
1224
|
+
];
|
|
1540
1225
|
}
|
|
1226
|
+
};
|
|
1227
|
+
|
|
1228
|
+
// src/linters/spec-tech-agnostic.ts
|
|
1229
|
+
function maskFencedBlocks(text) {
|
|
1230
|
+
return text.replace(/```[\s\S]*?```/g, (m) => m.replace(/[^\n]/g, " "));
|
|
1541
1231
|
}
|
|
1542
|
-
|
|
1543
|
-
|
|
1544
|
-
|
|
1545
|
-
|
|
1546
|
-
|
|
1547
|
-
|
|
1548
|
-
|
|
1549
|
-
|
|
1550
|
-
|
|
1551
|
-
|
|
1552
|
-
|
|
1553
|
-
|
|
1554
|
-
|
|
1232
|
+
var TECH_BLOCKLIST = [
|
|
1233
|
+
{ pattern: /\bNext\.?js\b/i, keyword: "Next.js" },
|
|
1234
|
+
{ pattern: /\bSupabase\b/i, keyword: "Supabase" },
|
|
1235
|
+
{ pattern: /\bVercel\b/i, keyword: "Vercel" },
|
|
1236
|
+
{ pattern: /\bReact\b/, keyword: "React" },
|
|
1237
|
+
{ pattern: /\bTypeScript\b/, keyword: "TypeScript" },
|
|
1238
|
+
{ pattern: /\bDocker\b/, keyword: "Docker" },
|
|
1239
|
+
{ pattern: /\bKubernetes\b/i, keyword: "Kubernetes" },
|
|
1240
|
+
{ pattern: /\bPostgres(QL)?\b/i, keyword: "Postgres" },
|
|
1241
|
+
{ pattern: /\bMySQL\b/i, keyword: "MySQL" },
|
|
1242
|
+
{ pattern: /\bRedis\b/i, keyword: "Redis" },
|
|
1243
|
+
{ pattern: /\bnpm\b/, keyword: "npm" },
|
|
1244
|
+
{ pattern: /\bpnpm\b/, keyword: "pnpm" },
|
|
1245
|
+
{ pattern: /\byarn\b/, keyword: "yarn" }
|
|
1246
|
+
];
|
|
1247
|
+
var specTechAgnostic = {
|
|
1248
|
+
id: "lint:spec-tech-agnostic",
|
|
1249
|
+
pillars: ["spec"],
|
|
1250
|
+
defaultSeverity: "error",
|
|
1251
|
+
suggestedSkills: ["/spec"],
|
|
1252
|
+
run(repoRoot) {
|
|
1253
|
+
const issues = [];
|
|
1254
|
+
const files = listMarkdown(repoRoot, "docs/spec");
|
|
1255
|
+
for (const f of files) {
|
|
1256
|
+
const text = maskFencedBlocks(readText(repoRoot, f));
|
|
1257
|
+
for (const { pattern, keyword } of TECH_BLOCKLIST) {
|
|
1258
|
+
if (pattern.test(text)) {
|
|
1259
|
+
const issue = {
|
|
1260
|
+
linter: this.id,
|
|
1261
|
+
severity: "error",
|
|
1262
|
+
file: f,
|
|
1263
|
+
message: `forbidden tech keyword "${keyword}" \u2014 should be in handbook/ or decisions/`
|
|
1264
|
+
};
|
|
1265
|
+
const line = findLineNumber(text, pattern);
|
|
1266
|
+
if (line !== void 0) issue.line = line;
|
|
1267
|
+
issues.push(issue);
|
|
1268
|
+
}
|
|
1269
|
+
}
|
|
1555
1270
|
}
|
|
1271
|
+
return issues;
|
|
1556
1272
|
}
|
|
1557
|
-
}
|
|
1558
|
-
function assertManagedPaths(root, files) {
|
|
1559
|
-
for (const path of files) assertManagedLocation(path);
|
|
1560
|
-
const canonicalRoot2 = canonicalTargetRoot(root);
|
|
1561
|
-
for (const path of files) assertNoSymbolicComponents(canonicalRoot2, path);
|
|
1562
|
-
}
|
|
1563
|
-
|
|
1564
|
-
// src/cli/manifest.ts
|
|
1565
|
-
import { createHash } from "crypto";
|
|
1566
|
-
import { chmodSync, existsSync as existsSync8, readFileSync as readFileSync7, writeFileSync } from "fs";
|
|
1567
|
-
import { join as join9 } from "path";
|
|
1568
|
-
import { z as z5 } from "zod";
|
|
1273
|
+
};
|
|
1569
1274
|
|
|
1570
|
-
// src/
|
|
1571
|
-
import
|
|
1572
|
-
|
|
1573
|
-
|
|
1574
|
-
|
|
1575
|
-
|
|
1576
|
-
|
|
1577
|
-
var ObjectSchema = z3.record(z3.unknown());
|
|
1578
|
-
var OpenCodeConfigOwnershipSchema = z3.object({
|
|
1579
|
-
createdFile: z3.boolean(),
|
|
1580
|
-
addedMcp: z3.boolean(),
|
|
1581
|
-
addedSchema: z3.boolean(),
|
|
1582
|
-
entries: z3.record(ObjectSchema)
|
|
1583
|
-
});
|
|
1584
|
-
function parseConfig(content) {
|
|
1585
|
-
try {
|
|
1586
|
-
const config = ObjectSchema.parse(JSON.parse(content));
|
|
1587
|
-
if (Object.hasOwn(config, "mcp")) ObjectSchema.parse(config.mcp);
|
|
1588
|
-
return config;
|
|
1589
|
-
} catch {
|
|
1590
|
-
throw new Error(`invalid ${OPENCODE_CONFIG_PATH}: expected a JSON object with an MCP object`);
|
|
1275
|
+
// src/linters/tracks-drift.ts
|
|
1276
|
+
import fg6 from "fast-glob";
|
|
1277
|
+
var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
|
|
1278
|
+
var DEFAULT_DRIFT_THRESHOLD = 10;
|
|
1279
|
+
function expandGlob(repoRoot, pattern) {
|
|
1280
|
+
if (pattern.includes("*")) {
|
|
1281
|
+
return fg6.sync(pattern, { cwd: repoRoot, absolute: false });
|
|
1591
1282
|
}
|
|
1283
|
+
return [pattern];
|
|
1592
1284
|
}
|
|
1593
|
-
|
|
1594
|
-
|
|
1595
|
-
|
|
1596
|
-
|
|
1597
|
-
|
|
1598
|
-
|
|
1599
|
-
|
|
1600
|
-
|
|
1601
|
-
|
|
1602
|
-
|
|
1603
|
-
|
|
1604
|
-
|
|
1605
|
-
|
|
1606
|
-
|
|
1607
|
-
|
|
1608
|
-
|
|
1609
|
-
|
|
1610
|
-
|
|
1611
|
-
|
|
1612
|
-
|
|
1613
|
-
|
|
1614
|
-
|
|
1285
|
+
var tracksDrift = {
|
|
1286
|
+
id: "lint:tracks-drift",
|
|
1287
|
+
pillars: ["handbook", "tests", "workflow"],
|
|
1288
|
+
defaultSeverity: "warning",
|
|
1289
|
+
suggestedSkills: ["/drift", "/handbook"],
|
|
1290
|
+
run(repoRoot) {
|
|
1291
|
+
const issues = [];
|
|
1292
|
+
for (const dir of TRACKED_DIRS2) {
|
|
1293
|
+
const files = listMarkdown(repoRoot, dir);
|
|
1294
|
+
for (const f of files) {
|
|
1295
|
+
const text = readText(repoRoot, f);
|
|
1296
|
+
const { data } = parseFrontmatter(text);
|
|
1297
|
+
if (!Array.isArray(data.tracks)) continue;
|
|
1298
|
+
const docCommit = gitLastCommitForPath(repoRoot, f);
|
|
1299
|
+
if (!docCommit) continue;
|
|
1300
|
+
const threshold = typeof data.driftThreshold === "number" && data.driftThreshold > 0 ? data.driftThreshold : DEFAULT_DRIFT_THRESHOLD;
|
|
1301
|
+
let driftCount = 0;
|
|
1302
|
+
for (const tracked of data.tracks) {
|
|
1303
|
+
if (typeof tracked !== "string") continue;
|
|
1304
|
+
const targets = expandGlob(repoRoot, tracked);
|
|
1305
|
+
for (const t of targets.length > 0 ? targets : [tracked]) {
|
|
1306
|
+
driftCount += gitCommitsSince(repoRoot, t, docCommit.hash);
|
|
1307
|
+
}
|
|
1308
|
+
}
|
|
1309
|
+
if (driftCount > threshold) {
|
|
1310
|
+
issues.push({
|
|
1311
|
+
linter: this.id,
|
|
1312
|
+
severity: "warning",
|
|
1313
|
+
file: f,
|
|
1314
|
+
message: `tracked files changed in ${driftCount} commits since doc last edit (threshold ${threshold})`
|
|
1315
|
+
});
|
|
1316
|
+
}
|
|
1615
1317
|
}
|
|
1616
|
-
continue;
|
|
1617
1318
|
}
|
|
1618
|
-
|
|
1619
|
-
mcp[id] = entry;
|
|
1620
|
-
}
|
|
1621
|
-
if (Object.keys(entries).length === 0) return void 0;
|
|
1622
|
-
const ownership = {
|
|
1623
|
-
createdFile,
|
|
1624
|
-
addedMcp: !Object.hasOwn(config, "mcp"),
|
|
1625
|
-
addedSchema: !Object.hasOwn(config, "$schema"),
|
|
1626
|
-
entries
|
|
1627
|
-
};
|
|
1628
|
-
config.mcp = mcp;
|
|
1629
|
-
if (ownership.addedSchema) config.$schema = OPENCODE_SCHEMA;
|
|
1630
|
-
return ownership;
|
|
1631
|
-
}
|
|
1632
|
-
function planOpenCodeConfig(root, desired, previous) {
|
|
1633
|
-
const warnings = [];
|
|
1634
|
-
if (!desired && !previous) return { remove: false, warnings };
|
|
1635
|
-
const path = join7(root, OPENCODE_CONFIG_PATH);
|
|
1636
|
-
const existed = existsSync6(path);
|
|
1637
|
-
if (!existed && !desired) return { remove: false, warnings };
|
|
1638
|
-
const original = existed ? readFileSync5(path, "utf8") : void 0;
|
|
1639
|
-
const config = original === void 0 ? {} : parseConfig(original);
|
|
1640
|
-
const before = structuredClone(config);
|
|
1641
|
-
if (previous) removeOwnedEntries(config, previous, warnings);
|
|
1642
|
-
const createdFile = !existed || previous?.createdFile === true;
|
|
1643
|
-
const ownership = desired ? addMissingEntries(config, desired, createdFile, warnings) : void 0;
|
|
1644
|
-
if (!ownership && createdFile && Object.keys(config).length === 0) {
|
|
1645
|
-
return { remove: existed, warnings };
|
|
1319
|
+
return issues;
|
|
1646
1320
|
}
|
|
1647
|
-
|
|
1648
|
-
remove: false,
|
|
1649
|
-
ownership,
|
|
1650
|
-
warnings,
|
|
1651
|
-
...!existed || !isDeepStrictEqual(before, config) ? { write: { path: OPENCODE_CONFIG_PATH, content: `${JSON.stringify(config, null, 2)}
|
|
1652
|
-
` } } : {}
|
|
1653
|
-
};
|
|
1654
|
-
}
|
|
1321
|
+
};
|
|
1655
1322
|
|
|
1656
|
-
// src/
|
|
1657
|
-
|
|
1658
|
-
|
|
1659
|
-
|
|
1660
|
-
|
|
1661
|
-
|
|
1662
|
-
|
|
1663
|
-
|
|
1664
|
-
|
|
1665
|
-
|
|
1666
|
-
|
|
1667
|
-
|
|
1668
|
-
|
|
1323
|
+
// src/linters/index.ts
|
|
1324
|
+
var ALL_LINTERS = [
|
|
1325
|
+
readmePresence,
|
|
1326
|
+
readmeSections,
|
|
1327
|
+
docLayout,
|
|
1328
|
+
cardinalFiles,
|
|
1329
|
+
decisionSchema,
|
|
1330
|
+
adrNoTracks,
|
|
1331
|
+
frontmatterTracks,
|
|
1332
|
+
tracksDrift,
|
|
1333
|
+
specTechAgnostic,
|
|
1334
|
+
specHasContent,
|
|
1335
|
+
crossLinks,
|
|
1336
|
+
orphanDecisions,
|
|
1337
|
+
gitignoreHarness,
|
|
1338
|
+
qualitySchema,
|
|
1339
|
+
generatedFresh
|
|
1669
1340
|
];
|
|
1670
|
-
|
|
1671
|
-
|
|
1672
|
-
|
|
1673
|
-
|
|
1674
|
-
|
|
1675
|
-
|
|
1676
|
-
|
|
1677
|
-
});
|
|
1678
|
-
var HookConfigsOwnershipSchema = z4.object({
|
|
1679
|
-
".claude/settings.json": HookConfigOwnershipSchema.optional(),
|
|
1680
|
-
".codex/hooks.json": HookConfigOwnershipSchema.optional()
|
|
1681
|
-
}).strict();
|
|
1682
|
-
var HOOK_ENGINES = {
|
|
1683
|
-
".claude/settings.json": "claude-code",
|
|
1684
|
-
".codex/hooks.json": "codex-cli"
|
|
1685
|
-
};
|
|
1686
|
-
function parseObject(content, path) {
|
|
1687
|
-
try {
|
|
1688
|
-
return ObjectSchema2.parse(JSON.parse(content));
|
|
1689
|
-
} catch {
|
|
1690
|
-
throw new Error(`invalid shared configuration ${path}: expected a JSON object`);
|
|
1691
|
-
}
|
|
1692
|
-
}
|
|
1693
|
-
function asObject(value) {
|
|
1694
|
-
const parsed = ObjectSchema2.safeParse(value);
|
|
1695
|
-
return parsed.success ? parsed.data : void 0;
|
|
1696
|
-
}
|
|
1697
|
-
function stopHooks(config, path) {
|
|
1698
|
-
if (!Object.hasOwn(config, "hooks")) return [];
|
|
1699
|
-
const hooks = asObject(config.hooks);
|
|
1700
|
-
if (!hooks || Object.hasOwn(hooks, "Stop") && !Array.isArray(hooks.Stop)) {
|
|
1701
|
-
throw new Error(`invalid shared configuration ${path}: expected hooks.Stop to be an array`);
|
|
1702
|
-
}
|
|
1703
|
-
return Array.isArray(hooks.Stop) ? hooks.Stop : [];
|
|
1704
|
-
}
|
|
1705
|
-
function groupMetadata(group) {
|
|
1706
|
-
return Object.fromEntries(Object.entries(group).filter(([key]) => key !== "hooks"));
|
|
1707
|
-
}
|
|
1708
|
-
function sameEntry(left, right) {
|
|
1709
|
-
return isDeepStrictEqual2(left.group, right.group) && isDeepStrictEqual2(left.hook, right.hook);
|
|
1710
|
-
}
|
|
1711
|
-
function appendEntry(entries, entry) {
|
|
1712
|
-
if (!entries.some((existing) => sameEntry(existing, entry))) entries.push(entry);
|
|
1713
|
-
}
|
|
1714
|
-
function defaultStopGroup(engine) {
|
|
1715
|
-
const file = getRenderer(engine).renderStopHook().files[0];
|
|
1716
|
-
if (!file) throw new Error(`missing Stop hook renderer for ${engine}`);
|
|
1717
|
-
const group = asObject(stopHooks(parseObject(file.content, file.path), file.path)[0]);
|
|
1718
|
-
if (!group || !Array.isArray(group.hooks) || !asObject(group.hooks[0])) {
|
|
1719
|
-
throw new Error(`invalid Stop hook renderer for ${engine}`);
|
|
1720
|
-
}
|
|
1721
|
-
return group;
|
|
1722
|
-
}
|
|
1723
|
-
function normalizeHarnessHooks(groups, expected, previous, claimExisting, warnings, path) {
|
|
1724
|
-
const defaultHook = ObjectSchema2.parse(expected.hooks[0]);
|
|
1725
|
-
const entries = [...previous?.entries ?? []];
|
|
1726
|
-
let found = false;
|
|
1727
|
-
const normalized = groups.map((value) => {
|
|
1728
|
-
const group = asObject(value);
|
|
1729
|
-
if (!group) return value;
|
|
1730
|
-
const flat = group.type === "command" && group.command === defaultHook.command;
|
|
1731
|
-
const hooks = flat ? [group] : Array.isArray(group.hooks) ? group.hooks : [];
|
|
1732
|
-
const metadata = flat ? groupMetadata(expected) : groupMetadata(group);
|
|
1733
|
-
for (const value2 of hooks) {
|
|
1734
|
-
const hook = asObject(value2);
|
|
1735
|
-
if (!hook || hook.type !== "command" || hook.command !== defaultHook.command) continue;
|
|
1736
|
-
found = true;
|
|
1737
|
-
const entry = { group: metadata, hook };
|
|
1738
|
-
if (!claimExisting) continue;
|
|
1739
|
-
if (previous && !previous.entries.some((old) => sameEntry(old, entry))) {
|
|
1740
|
-
warnings.push(`preserved modified harness Stop hook: ${path}`);
|
|
1741
|
-
} else {
|
|
1742
|
-
appendEntry(entries, entry);
|
|
1743
|
-
}
|
|
1744
|
-
}
|
|
1745
|
-
return flat && claimExisting ? { ...metadata, hooks: [group] } : value;
|
|
1341
|
+
function runLinters(repoRoot, opts = {}) {
|
|
1342
|
+
const config = loadLintConfig(repoRoot);
|
|
1343
|
+
const ctx = { repoRoot, config };
|
|
1344
|
+
const filtered = ALL_LINTERS.filter((l) => {
|
|
1345
|
+
if (opts.only && !opts.only.includes(l.id)) return false;
|
|
1346
|
+
if (opts.pillar && !l.pillars.includes(opts.pillar) && !l.pillars.includes("all")) return false;
|
|
1347
|
+
return true;
|
|
1746
1348
|
});
|
|
1747
|
-
|
|
1748
|
-
|
|
1749
|
-
|
|
1750
|
-
|
|
1751
|
-
|
|
1752
|
-
|
|
1753
|
-
|
|
1754
|
-
|
|
1755
|
-
|
|
1756
|
-
|
|
1757
|
-
|
|
1758
|
-
const matched = /* @__PURE__ */ new Set();
|
|
1759
|
-
for (const value of groups) {
|
|
1760
|
-
const group = asObject(value);
|
|
1761
|
-
if (!group || !Array.isArray(group.hooks)) {
|
|
1762
|
-
remaining.push(value);
|
|
1763
|
-
continue;
|
|
1764
|
-
}
|
|
1765
|
-
const metadata = groupMetadata(group);
|
|
1766
|
-
const hooks2 = group.hooks.filter((value2) => {
|
|
1767
|
-
const hook = asObject(value2);
|
|
1768
|
-
const entry = hook && ownership.entries.find((old) => sameEntry(old, { group: metadata, hook }));
|
|
1769
|
-
if (entry) matched.add(entry);
|
|
1770
|
-
return !entry;
|
|
1771
|
-
});
|
|
1772
|
-
if (hooks2.length > 0 || hooks2.length === group.hooks.length) {
|
|
1773
|
-
remaining.push({ ...group, hooks: hooks2 });
|
|
1349
|
+
const issues = [];
|
|
1350
|
+
for (const linter of filtered) {
|
|
1351
|
+
try {
|
|
1352
|
+
issues.push(...linter.run(repoRoot, ctx));
|
|
1353
|
+
} catch (err) {
|
|
1354
|
+
issues.push({
|
|
1355
|
+
linter: linter.id,
|
|
1356
|
+
severity: "error",
|
|
1357
|
+
file: "<internal>",
|
|
1358
|
+
message: `linter crashed: ${err instanceof Error ? err.message : String(err)}`
|
|
1359
|
+
});
|
|
1774
1360
|
}
|
|
1775
1361
|
}
|
|
1776
|
-
|
|
1777
|
-
|
|
1778
|
-
|
|
1779
|
-
|
|
1780
|
-
|
|
1781
|
-
|
|
1782
|
-
else if (Object.hasOwn(hooks, "Stop")) hooks.Stop = remaining;
|
|
1783
|
-
if (ownership.addedHooks && Object.keys(hooks).length === 0)
|
|
1784
|
-
Reflect.deleteProperty(config, "hooks");
|
|
1785
|
-
else config.hooks = hooks;
|
|
1786
|
-
}
|
|
1787
|
-
function recordMutation(plan, path, before, after, createdFile) {
|
|
1788
|
-
if (createdFile && Object.keys(after).length === 0) {
|
|
1789
|
-
if (before) plan.removals.push(path);
|
|
1790
|
-
} else if (!isDeepStrictEqual2(before, after)) {
|
|
1791
|
-
plan.writes.push({ path, content: `${JSON.stringify(after, null, 2)}
|
|
1792
|
-
` });
|
|
1793
|
-
}
|
|
1794
|
-
}
|
|
1795
|
-
function planHookConfigCleanup(root, ownership) {
|
|
1796
|
-
const plan = { writes: [], removals: [], warnings: [] };
|
|
1797
|
-
if (!ownership) return plan;
|
|
1798
|
-
const validated = HookConfigsOwnershipSchema.parse(ownership);
|
|
1799
|
-
assertManagedPaths(root, Object.keys(validated));
|
|
1800
|
-
for (const path of Object.keys(HOOK_ENGINES)) {
|
|
1801
|
-
const owned = validated[path];
|
|
1802
|
-
if (!owned || !existsSync7(join8(root, path))) continue;
|
|
1803
|
-
const before = parseObject(readFileSync6(join8(root, path), "utf8"), path);
|
|
1804
|
-
const config = structuredClone(before);
|
|
1805
|
-
removeOwnedHooks(config, owned, path, plan.warnings);
|
|
1806
|
-
recordMutation(plan, path, before, config, owned.createdFile);
|
|
1807
|
-
}
|
|
1808
|
-
return plan;
|
|
1809
|
-
}
|
|
1810
|
-
function planActiveHook(root, path, previous, claimExisting, plan) {
|
|
1811
|
-
assertManagedPaths(root, [path]);
|
|
1812
|
-
const existed = existsSync7(join8(root, path));
|
|
1813
|
-
if (!existed && previous?.entries.length) {
|
|
1814
|
-
plan.warnings.push(`preserved removed harness Stop hook configuration: ${path}`);
|
|
1815
|
-
return previous;
|
|
1816
|
-
}
|
|
1817
|
-
const before = existed ? parseObject(readFileSync6(join8(root, path), "utf8"), path) : void 0;
|
|
1818
|
-
const config = structuredClone(before ?? {});
|
|
1819
|
-
const groups = stopHooks(config, path);
|
|
1820
|
-
const hooks = asObject(config.hooks) ?? {};
|
|
1821
|
-
const normalized = normalizeHarnessHooks(
|
|
1822
|
-
groups,
|
|
1823
|
-
defaultStopGroup(HOOK_ENGINES[path]),
|
|
1824
|
-
previous,
|
|
1825
|
-
claimExisting,
|
|
1826
|
-
plan.warnings,
|
|
1827
|
-
path
|
|
1828
|
-
);
|
|
1829
|
-
const ownership = {
|
|
1830
|
-
createdFile: !existed || previous?.createdFile === true,
|
|
1831
|
-
addedHooks: previous?.addedHooks ?? !Object.hasOwn(config, "hooks"),
|
|
1832
|
-
addedStop: previous?.addedStop ?? !Object.hasOwn(hooks, "Stop"),
|
|
1833
|
-
entries: normalized.entries
|
|
1362
|
+
const errors = issues.filter((i) => i.severity === "error").length;
|
|
1363
|
+
const warnings = issues.filter((i) => i.severity === "warning").length;
|
|
1364
|
+
return {
|
|
1365
|
+
version: 1,
|
|
1366
|
+
summary: { errors, warnings, pass: errors === 0 },
|
|
1367
|
+
issues
|
|
1834
1368
|
};
|
|
1835
|
-
if (!isDeepStrictEqual2(groups, normalized.groups)) {
|
|
1836
|
-
config.hooks = { ...hooks, Stop: normalized.groups };
|
|
1837
|
-
}
|
|
1838
|
-
recordMutation(plan, path, before, config, ownership.createdFile);
|
|
1839
|
-
return ownership.entries.length > 0 ? ownership : void 0;
|
|
1840
|
-
}
|
|
1841
|
-
function planLegacyOpenCode(root, previous, plan) {
|
|
1842
|
-
if (!previous.files.includes(LEGACY_OPENCODE_CONFIG)) return;
|
|
1843
|
-
const legacyPath = join8(root, LEGACY_OPENCODE_CONFIG);
|
|
1844
|
-
if (!existsSync7(legacyPath)) return;
|
|
1845
|
-
assertManagedPaths(root, [LEGACY_OPENCODE_CONFIG, OPENCODE_CONFIG_PATH]);
|
|
1846
|
-
const legacy = parseObject(readFileSync6(legacyPath, "utf8"), LEGACY_OPENCODE_CONFIG);
|
|
1847
|
-
if (!asObject(legacy.mcp)) {
|
|
1848
|
-
throw new Error(
|
|
1849
|
-
`invalid shared configuration ${LEGACY_OPENCODE_CONFIG}: expected an MCP object`
|
|
1850
|
-
);
|
|
1851
|
-
}
|
|
1852
|
-
const merged = planOpenCodeConfig(
|
|
1853
|
-
root,
|
|
1854
|
-
{ path: OPENCODE_CONFIG_PATH, content: JSON.stringify(legacy) },
|
|
1855
|
-
void 0
|
|
1856
|
-
);
|
|
1857
|
-
if (merged.write) plan.writes.push(merged.write);
|
|
1858
|
-
plan.warnings.push(...merged.warnings);
|
|
1859
|
-
if (merged.ownership) {
|
|
1860
|
-
const old = previous.opencodeConfig;
|
|
1861
|
-
plan.opencodeConfig = {
|
|
1862
|
-
createdFile: merged.ownership.createdFile || old?.createdFile === true,
|
|
1863
|
-
addedMcp: merged.ownership.addedMcp || old?.addedMcp === true,
|
|
1864
|
-
addedSchema: merged.ownership.addedSchema || old?.addedSchema === true,
|
|
1865
|
-
entries: { ...old?.entries, ...merged.ownership.entries }
|
|
1866
|
-
};
|
|
1867
|
-
}
|
|
1868
|
-
plan.removals.push(LEGACY_OPENCODE_CONFIG);
|
|
1869
1369
|
}
|
|
1870
|
-
function
|
|
1871
|
-
const
|
|
1872
|
-
|
|
1873
|
-
|
|
1874
|
-
|
|
1875
|
-
|
|
1876
|
-
|
|
1877
|
-
|
|
1878
|
-
|
|
1879
|
-
|
|
1880
|
-
|
|
1881
|
-
|
|
1882
|
-
|
|
1883
|
-
hookConfigs[path] = planActiveHook(
|
|
1884
|
-
root,
|
|
1885
|
-
path,
|
|
1886
|
-
owned,
|
|
1887
|
-
previous.files.includes(path) || Boolean(owned),
|
|
1888
|
-
plan
|
|
1889
|
-
);
|
|
1890
|
-
} else if (owned) {
|
|
1891
|
-
const cleanup = planHookConfigCleanup(root, { [path]: owned });
|
|
1892
|
-
plan.writes.push(...cleanup.writes);
|
|
1893
|
-
plan.removals.push(...cleanup.removals);
|
|
1894
|
-
plan.warnings.push(...cleanup.warnings);
|
|
1370
|
+
function suggestedSkillsFor(linterId) {
|
|
1371
|
+
const linter = ALL_LINTERS.find((l) => l.id === linterId);
|
|
1372
|
+
return linter?.suggestedSkills ?? [];
|
|
1373
|
+
}
|
|
1374
|
+
function formatReportText(report) {
|
|
1375
|
+
const lines = [];
|
|
1376
|
+
for (const issue of report.issues) {
|
|
1377
|
+
const location = issue.line !== void 0 ? `:${issue.line}` : "";
|
|
1378
|
+
lines.push(`${issue.file}${location}: ${issue.severity}[${issue.linter}]
|
|
1379
|
+
${issue.message}`);
|
|
1380
|
+
const hints = suggestedSkillsFor(issue.linter);
|
|
1381
|
+
if (hints.length > 0) {
|
|
1382
|
+
lines.push(` \u2192 Try: ${hints.join(", ")}`);
|
|
1895
1383
|
}
|
|
1896
1384
|
}
|
|
1897
|
-
|
|
1898
|
-
|
|
1899
|
-
|
|
1900
|
-
|
|
1901
|
-
|
|
1902
|
-
|
|
1903
|
-
}
|
|
1904
|
-
return plan;
|
|
1385
|
+
const { errors, warnings, pass } = report.summary;
|
|
1386
|
+
lines.push("");
|
|
1387
|
+
lines.push(
|
|
1388
|
+
`${errors} ${errors === 1 ? "error" : "errors"}, ${warnings} ${warnings === 1 ? "warning" : "warnings"}. ${pass ? "\u2714 CI passes." : "\u2718 CI fails."}`
|
|
1389
|
+
);
|
|
1390
|
+
return lines.join("\n");
|
|
1905
1391
|
}
|
|
1906
1392
|
|
|
1907
|
-
// src/cli/
|
|
1908
|
-
|
|
1909
|
-
|
|
1910
|
-
var
|
|
1911
|
-
|
|
1912
|
-
|
|
1913
|
-
|
|
1914
|
-
|
|
1915
|
-
|
|
1916
|
-
|
|
1917
|
-
|
|
1918
|
-
|
|
1919
|
-
|
|
1920
|
-
|
|
1921
|
-
|
|
1922
|
-
|
|
1923
|
-
|
|
1924
|
-
|
|
1925
|
-
|
|
1926
|
-
}
|
|
1927
|
-
|
|
1928
|
-
|
|
1929
|
-
|
|
1930
|
-
|
|
1931
|
-
|
|
1932
|
-
|
|
1933
|
-
|
|
1934
|
-
|
|
1935
|
-
|
|
1936
|
-
|
|
1937
|
-
|
|
1938
|
-
|
|
1939
|
-
|
|
1940
|
-
...extras.hookConfigs ? { hookConfigs: extras.hookConfigs } : {},
|
|
1941
|
-
...extras.opencodeConfig ? { opencodeConfig: extras.opencodeConfig } : {},
|
|
1942
|
-
...extras.stopHookInstalled !== void 0 ? { stopHookInstalled: extras.stopHookInstalled } : {},
|
|
1943
|
-
...extras.stopHookEngines !== void 0 ? { stopHookEngines: [...extras.stopHookEngines].sort() } : {}
|
|
1944
|
-
};
|
|
1945
|
-
const path = manifestPath(targetDir);
|
|
1946
|
-
if (existsSync8(path)) chmodSync(path, 384);
|
|
1947
|
-
writeFileSync(path, `${JSON.stringify(manifest, null, 2)}
|
|
1948
|
-
`, { mode: 384 });
|
|
1949
|
-
}
|
|
1950
|
-
function hashContent(content) {
|
|
1951
|
-
return createHash("sha256").update(content).digest("hex");
|
|
1952
|
-
}
|
|
1953
|
-
function readManifest(targetDir) {
|
|
1954
|
-
assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
|
|
1955
|
-
const path = manifestPath(targetDir);
|
|
1956
|
-
if (!existsSync8(path)) return null;
|
|
1957
|
-
const raw = JSON.parse(readFileSync7(path, "utf8"));
|
|
1958
|
-
return ManifestSchema.parse(raw);
|
|
1393
|
+
// src/cli/check.ts
|
|
1394
|
+
import { existsSync as existsSync8, readFileSync as readFileSync6 } from "fs";
|
|
1395
|
+
import { join as join9 } from "path";
|
|
1396
|
+
var REQUIRED_DIRS2 = [
|
|
1397
|
+
"docs/spec",
|
|
1398
|
+
"docs/decisions",
|
|
1399
|
+
"docs/handbook",
|
|
1400
|
+
"docs/tests",
|
|
1401
|
+
"docs/workflow"
|
|
1402
|
+
];
|
|
1403
|
+
function checkCommand(repoRoot) {
|
|
1404
|
+
const issues = [];
|
|
1405
|
+
if (!existsSync8(join9(repoRoot, "README.md"))) {
|
|
1406
|
+
issues.push("README.md missing at repo root");
|
|
1407
|
+
}
|
|
1408
|
+
for (const d of REQUIRED_DIRS2) {
|
|
1409
|
+
if (!existsSync8(join9(repoRoot, d))) {
|
|
1410
|
+
issues.push(`missing directory: ${d}/`);
|
|
1411
|
+
}
|
|
1412
|
+
}
|
|
1413
|
+
const gitignorePath = join9(repoRoot, ".gitignore");
|
|
1414
|
+
if (!existsSync8(gitignorePath)) {
|
|
1415
|
+
issues.push(".gitignore missing at repo root");
|
|
1416
|
+
} else {
|
|
1417
|
+
const text = readFileSync6(gitignorePath, "utf8");
|
|
1418
|
+
for (const entry of missingGitignoreEntries(text)) {
|
|
1419
|
+
issues.push(`.gitignore missing entry: ${entry}`);
|
|
1420
|
+
}
|
|
1421
|
+
for (const entry of forbiddenGitignoreEntries(text)) {
|
|
1422
|
+
issues.push(`.gitignore must not ignore generated file: ${entry}`);
|
|
1423
|
+
}
|
|
1424
|
+
}
|
|
1425
|
+
return { pass: issues.length === 0, issues };
|
|
1959
1426
|
}
|
|
1960
1427
|
|
|
1428
|
+
// src/cli/init.ts
|
|
1429
|
+
import { existsSync as existsSync12, mkdirSync as mkdirSync2, rmSync, writeFileSync as writeFileSync3 } from "fs";
|
|
1430
|
+
import { dirname as dirname7, join as join14, resolve as resolve8 } from "path";
|
|
1431
|
+
|
|
1961
1432
|
// src/cli/uninstall.ts
|
|
1962
|
-
import { existsSync as existsSync9, readdirSync, rmdirSync, unlinkSync
|
|
1963
|
-
import { dirname as
|
|
1433
|
+
import { existsSync as existsSync9, readFileSync as readFileSync7, readdirSync, rmdirSync, unlinkSync } from "fs";
|
|
1434
|
+
import { dirname as dirname4, join as join10, relative as relative2, resolve as resolve5 } from "path";
|
|
1964
1435
|
function uninstallCommand(args) {
|
|
1965
|
-
const root =
|
|
1436
|
+
const root = resolve5(args.targetDir);
|
|
1966
1437
|
const warnings = [];
|
|
1967
1438
|
assertManagedPaths(root, [MANIFEST_FILENAME]);
|
|
1968
1439
|
const manifest = readManifest(root);
|
|
@@ -1970,26 +1441,20 @@ function uninstallCommand(args) {
|
|
|
1970
1441
|
warnings.push(`no manifest found at ${manifestPath(root)} \u2014 nothing to uninstall`);
|
|
1971
1442
|
return { filesRemoved: [], dirsPruned: [], warnings };
|
|
1972
1443
|
}
|
|
1973
|
-
|
|
1974
|
-
|
|
1975
|
-
|
|
1976
|
-
|
|
1977
|
-
|
|
1978
|
-
|
|
1979
|
-
|
|
1980
|
-
|
|
1981
|
-
const ownedFiles =
|
|
1982
|
-
(file) => file !== OPENCODE_CONFIG_PATH && !sharedHooks.has(file)
|
|
1983
|
-
);
|
|
1984
|
-
if (config.remove) ownedFiles.push(OPENCODE_CONFIG_PATH);
|
|
1985
|
-
ownedFiles.push(...hooks.removals);
|
|
1444
|
+
const released = manifest.files.filter((file) => RELEASED_PATHS.includes(file));
|
|
1445
|
+
const files = manifest.files.filter((file) => !released.includes(file));
|
|
1446
|
+
assertManagedPaths(root, files);
|
|
1447
|
+
const modified = files.filter((file) => {
|
|
1448
|
+
const hash = manifest.fileHashes?.[file];
|
|
1449
|
+
const full = join10(root, file);
|
|
1450
|
+
return hash !== void 0 && existsSync9(full) && hashContent(readFileSync7(full)) !== hash;
|
|
1451
|
+
});
|
|
1452
|
+
const ownedFiles = files.filter((file) => !modified.includes(file));
|
|
1986
1453
|
const { filesRemoved, dirsPruned, missing } = removeRenderedFiles(root, ownedFiles);
|
|
1987
|
-
|
|
1988
|
-
|
|
1989
|
-
warnings.push(...config.warnings, ...hooks.warnings);
|
|
1990
|
-
if (manifest.files.includes(OPENCODE_CONFIG_PATH) && !manifest.opencodeConfig) {
|
|
1991
|
-
warnings.push(`preserved legacy shared configuration: ${OPENCODE_CONFIG_PATH}`);
|
|
1454
|
+
for (const file of released) {
|
|
1455
|
+
warnings.push(`no longer managed by the harness, left in place: ${file}`);
|
|
1992
1456
|
}
|
|
1457
|
+
for (const file of modified) warnings.push(`kept modified harness file: ${file}`);
|
|
1993
1458
|
for (const rel of missing) warnings.push(`file in manifest is already missing: ${rel}`);
|
|
1994
1459
|
unlinkSync(manifestPath(root));
|
|
1995
1460
|
return { filesRemoved, dirsPruned, warnings };
|
|
@@ -2004,7 +1469,7 @@ function removeRenderedFiles(root, files) {
|
|
|
2004
1469
|
if (existsSync9(full)) {
|
|
2005
1470
|
unlinkSync(full);
|
|
2006
1471
|
filesRemoved.push(rel);
|
|
2007
|
-
dirsToConsider.add(
|
|
1472
|
+
dirsToConsider.add(dirname4(full));
|
|
2008
1473
|
} else {
|
|
2009
1474
|
missing.push(rel);
|
|
2010
1475
|
}
|
|
@@ -2017,7 +1482,7 @@ function pruneEmptyDirs(root, leaves) {
|
|
|
2017
1482
|
let cur = leaf;
|
|
2018
1483
|
while (cur !== root && cur.startsWith(`${root}/`)) {
|
|
2019
1484
|
candidates.add(cur);
|
|
2020
|
-
cur =
|
|
1485
|
+
cur = dirname4(cur);
|
|
2021
1486
|
}
|
|
2022
1487
|
}
|
|
2023
1488
|
const pruned = [];
|
|
@@ -2031,451 +1496,34 @@ function pruneEmptyDirs(root, leaves) {
|
|
|
2031
1496
|
return pruned;
|
|
2032
1497
|
}
|
|
2033
1498
|
|
|
2034
|
-
// src/cli/init.ts
|
|
2035
|
-
var QUALITY_DOC_PATH = "docs/quality/code-quality.md";
|
|
2036
|
-
function resolveEngineList(requested) {
|
|
2037
|
-
if (!requested || requested.length === 0) return [...ENGINES];
|
|
2038
|
-
return requested.map((e) => {
|
|
2039
|
-
if (!ENGINES.includes(e)) {
|
|
2040
|
-
throw new Error(`unknown engine: ${e} (expected one of ${ENGINES.join(", ")})`);
|
|
2041
|
-
}
|
|
2042
|
-
return e;
|
|
2043
|
-
});
|
|
2044
|
-
}
|
|
2045
|
-
function defaultPackageDir() {
|
|
2046
|
-
const here = dirname4(fileURLToPath(import.meta.url));
|
|
2047
|
-
if (existsSync10(join11(here, "agents"))) return here;
|
|
2048
|
-
return resolve4(here, "..");
|
|
2049
|
-
}
|
|
2050
|
-
function planInit(args) {
|
|
2051
|
-
const engines = resolveEngineList(args.engines);
|
|
2052
|
-
const packageDir = args.packageDir ?? defaultPackageDir();
|
|
2053
|
-
const harness = loadHarness(packageDir);
|
|
2054
|
-
const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
|
|
2055
|
-
const projectSkills = loadProjectSkills(args.targetDir);
|
|
2056
|
-
const hasQualityDoc = existsSync10(join11(args.targetDir, QUALITY_DOC_PATH));
|
|
2057
|
-
const mcpServers = args.mcpServers ? resolveMcpIds(args.mcpServers) : void 0;
|
|
2058
|
-
const stopHookInstalled = args.withStopHook !== false;
|
|
2059
|
-
const output = render({
|
|
2060
|
-
harness,
|
|
2061
|
-
engines,
|
|
2062
|
-
overrides,
|
|
2063
|
-
projectSkills,
|
|
2064
|
-
hasQualityDoc,
|
|
2065
|
-
mcpServers,
|
|
2066
|
-
withStopHook: stopHookInstalled
|
|
2067
|
-
});
|
|
2068
|
-
return { engines, output, stopHookInstalled };
|
|
2069
|
-
}
|
|
2070
|
-
function writeFilesToTarget(files, targetDir) {
|
|
2071
|
-
assertManagedPaths(
|
|
2072
|
-
targetDir,
|
|
2073
|
-
files.map((file) => file.path)
|
|
2074
|
-
);
|
|
2075
|
-
const written = [];
|
|
2076
|
-
for (const f of files) {
|
|
2077
|
-
const full = join11(targetDir, f.path);
|
|
2078
|
-
mkdirSync(dirname4(full), { recursive: true });
|
|
2079
|
-
writeFileSync3(full, f.content);
|
|
2080
|
-
written.push(f.path);
|
|
2081
|
-
}
|
|
2082
|
-
return written;
|
|
2083
|
-
}
|
|
2084
|
-
function initCommand(args) {
|
|
2085
|
-
const { engines, output, stopHookInstalled } = planInit(args);
|
|
2086
|
-
const previous = readManifest(args.targetDir);
|
|
2087
|
-
assertManagedPaths(args.targetDir, [
|
|
2088
|
-
MANIFEST_FILENAME,
|
|
2089
|
-
...previous?.files ?? [],
|
|
2090
|
-
...output.files.map((file) => file.path),
|
|
2091
|
-
...previous?.opencodeConfig ? [OPENCODE_CONFIG_PATH] : []
|
|
2092
|
-
]);
|
|
2093
|
-
const desiredConfig = output.files.find((file) => file.path === OPENCODE_CONFIG_PATH);
|
|
2094
|
-
const config = planOpenCodeConfig(args.targetDir, desiredConfig, previous?.opencodeConfig);
|
|
2095
|
-
const next = new Set(output.files.map((f) => f.path));
|
|
2096
|
-
const stale = (previous?.files ?? []).filter((f) => !next.has(f) && f !== OPENCODE_CONFIG_PATH);
|
|
2097
|
-
if (config.remove) stale.push(OPENCODE_CONFIG_PATH);
|
|
2098
|
-
const staleFilesRemoved = removeRenderedFiles(resolve4(args.targetDir), stale).filesRemoved;
|
|
2099
|
-
const ownedFiles = output.files.filter((file) => file.path !== OPENCODE_CONFIG_PATH);
|
|
2100
|
-
const filesWritten = writeFilesToTarget(ownedFiles, args.targetDir);
|
|
2101
|
-
if (config.write) writeFilesToTarget([config.write], args.targetDir);
|
|
2102
|
-
writeManifest(args.targetDir, engines, filesWritten, {
|
|
2103
|
-
stopHookInstalled,
|
|
2104
|
-
stopHookEngines: stopHookInstalled ? engines : void 0,
|
|
2105
|
-
opencodeConfig: config.ownership,
|
|
2106
|
-
overridesDir: args.overridesDir ? resolve4(args.overridesDir) === resolve4(args.targetDir) ? "." : resolve4(args.overridesDir) : void 0
|
|
2107
|
-
});
|
|
2108
|
-
if (config.write) filesWritten.push(OPENCODE_CONFIG_PATH);
|
|
2109
|
-
const warnings = [...output.warnings, ...config.warnings];
|
|
2110
|
-
if (previous?.files.includes(OPENCODE_CONFIG_PATH) && !previous.opencodeConfig) {
|
|
2111
|
-
warnings.push(`preserved legacy shared configuration: ${OPENCODE_CONFIG_PATH}`);
|
|
2112
|
-
}
|
|
2113
|
-
return { filesWritten, staleFilesRemoved, warnings, stopHookInstalled };
|
|
2114
|
-
}
|
|
2115
|
-
|
|
2116
|
-
// src/cli/render.ts
|
|
2117
|
-
import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
|
|
2118
|
-
import { dirname as dirname5, join as join12 } from "path";
|
|
2119
|
-
function renderCommand(args) {
|
|
2120
|
-
const engineList = args.engines && args.engines.length > 0 ? args.engines.map((e) => {
|
|
2121
|
-
if (!ENGINES.includes(e)) {
|
|
2122
|
-
throw new Error(`unknown engine: ${e}`);
|
|
2123
|
-
}
|
|
2124
|
-
return e;
|
|
2125
|
-
}) : [...ENGINES];
|
|
2126
|
-
const harness = loadHarness(args.packageDir);
|
|
2127
|
-
const mcpServers = args.mcpServers ? resolveMcpIds(args.mcpServers) : void 0;
|
|
2128
|
-
const output = render({
|
|
2129
|
-
harness,
|
|
2130
|
-
engines: engineList,
|
|
2131
|
-
mcpServers,
|
|
2132
|
-
withStopHook: args.withStopHook !== false
|
|
2133
|
-
});
|
|
2134
|
-
const filesWritten = [];
|
|
2135
|
-
for (const f of output.files) {
|
|
2136
|
-
const full = join12(args.outDir, f.path);
|
|
2137
|
-
mkdirSync2(dirname5(full), { recursive: true });
|
|
2138
|
-
writeFileSync4(full, f.content);
|
|
2139
|
-
filesWritten.push(f.path);
|
|
2140
|
-
}
|
|
2141
|
-
return { filesWritten, warnings: output.warnings };
|
|
2142
|
-
}
|
|
2143
|
-
|
|
2144
|
-
// src/cli/stop-hook.ts
|
|
2145
|
-
import { readFileSync as readFileSync9 } from "fs";
|
|
2146
|
-
import { resolve as resolve5 } from "path";
|
|
2147
|
-
|
|
2148
|
-
// src/stop-hook/adapters/claude.ts
|
|
2149
|
-
var claudeAdapter = {
|
|
2150
|
-
parseInput(stdin) {
|
|
2151
|
-
const parsed = stdin.trim() === "" ? {} : JSON.parse(stdin);
|
|
2152
|
-
return {
|
|
2153
|
-
sessionId: typeof parsed.session_id === "string" ? parsed.session_id : "default",
|
|
2154
|
-
stopHookActive: parsed.stop_hook_active === true
|
|
2155
|
-
};
|
|
2156
|
-
},
|
|
2157
|
-
respond(decision) {
|
|
2158
|
-
if (decision.kind === "inject") {
|
|
2159
|
-
return {
|
|
2160
|
-
stdout: `${JSON.stringify({ decision: "block", reason: decision.reason ?? "" })}
|
|
2161
|
-
`,
|
|
2162
|
-
stderr: "",
|
|
2163
|
-
exitCode: 0
|
|
2164
|
-
};
|
|
2165
|
-
}
|
|
2166
|
-
if (decision.kind === "terminate") {
|
|
2167
|
-
return {
|
|
2168
|
-
stdout: "",
|
|
2169
|
-
stderr: `${decision.reason ?? ""}
|
|
2170
|
-
`,
|
|
2171
|
-
exitCode: 0
|
|
2172
|
-
};
|
|
2173
|
-
}
|
|
2174
|
-
return { stdout: "", stderr: "", exitCode: 0 };
|
|
2175
|
-
}
|
|
2176
|
-
};
|
|
2177
|
-
|
|
2178
|
-
// src/stop-hook/adapters/codex.ts
|
|
2179
|
-
var codexAdapter = {
|
|
2180
|
-
parseInput(stdin) {
|
|
2181
|
-
const parsed = stdin.trim() === "" ? {} : JSON.parse(stdin);
|
|
2182
|
-
return {
|
|
2183
|
-
sessionId: typeof parsed.session_id === "string" ? parsed.session_id : "default",
|
|
2184
|
-
stopHookActive: parsed.stop_hook_active === true
|
|
2185
|
-
};
|
|
2186
|
-
},
|
|
2187
|
-
respond(decision) {
|
|
2188
|
-
if (decision.kind === "inject") {
|
|
2189
|
-
return {
|
|
2190
|
-
stdout: `${JSON.stringify({ decision: "block", reason: decision.reason ?? "" })}
|
|
2191
|
-
`,
|
|
2192
|
-
stderr: "",
|
|
2193
|
-
exitCode: 0
|
|
2194
|
-
};
|
|
2195
|
-
}
|
|
2196
|
-
if (decision.kind === "terminate") {
|
|
2197
|
-
return {
|
|
2198
|
-
stdout: "",
|
|
2199
|
-
stderr: `${decision.reason ?? ""}
|
|
2200
|
-
`,
|
|
2201
|
-
exitCode: 0
|
|
2202
|
-
};
|
|
2203
|
-
}
|
|
2204
|
-
return { stdout: "", stderr: "", exitCode: 0 };
|
|
2205
|
-
}
|
|
2206
|
-
};
|
|
2207
|
-
|
|
2208
|
-
// src/stop-hook/adapters/opencode.ts
|
|
2209
|
-
var opencodeAdapter = {
|
|
2210
|
-
parseInput(stdin) {
|
|
2211
|
-
const parsed = stdin.trim() === "" ? {} : JSON.parse(stdin);
|
|
2212
|
-
const sessionId = typeof parsed.sessionID === "string" ? parsed.sessionID : typeof parsed.session_id === "string" ? parsed.session_id : "default";
|
|
2213
|
-
return { sessionId, stopHookActive: false };
|
|
2214
|
-
},
|
|
2215
|
-
respond(decision) {
|
|
2216
|
-
if (decision.kind === "inject") {
|
|
2217
|
-
return { stdout: "", stderr: `${decision.reason ?? ""}
|
|
2218
|
-
`, exitCode: 2 };
|
|
2219
|
-
}
|
|
2220
|
-
if (decision.kind === "terminate") {
|
|
2221
|
-
return { stdout: "", stderr: `${decision.reason ?? ""}
|
|
2222
|
-
`, exitCode: 0 };
|
|
2223
|
-
}
|
|
2224
|
-
return { stdout: "", stderr: "", exitCode: 0 };
|
|
2225
|
-
}
|
|
2226
|
-
};
|
|
2227
|
-
|
|
2228
|
-
// src/stop-hook/adapters/index.ts
|
|
2229
|
-
var ADAPTERS = {
|
|
2230
|
-
claude: claudeAdapter,
|
|
2231
|
-
codex: codexAdapter,
|
|
2232
|
-
opencode: opencodeAdapter
|
|
2233
|
-
};
|
|
2234
|
-
function getAdapter(engine) {
|
|
2235
|
-
return ADAPTERS[engine];
|
|
2236
|
-
}
|
|
2237
|
-
|
|
2238
|
-
// src/stop-hook/core.ts
|
|
2239
|
-
import { execFileSync as execFileSync2 } from "child_process";
|
|
2240
|
-
import { createHash as createHash2 } from "crypto";
|
|
2241
|
-
|
|
2242
|
-
// src/stop-hook/state.ts
|
|
2243
|
-
import { existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync8, rmSync, writeFileSync as writeFileSync5 } from "fs";
|
|
2244
|
-
import { dirname as dirname6, join as join13 } from "path";
|
|
2245
|
-
import { z as z6 } from "zod";
|
|
2246
|
-
var LintStateSchema = z6.object({
|
|
2247
|
-
attempts: z6.number().int().nonnegative(),
|
|
2248
|
-
lastLintHash: z6.string(),
|
|
2249
|
-
updatedAt: z6.string()
|
|
2250
|
-
});
|
|
2251
|
-
var STATE_DIR = ".harness/state";
|
|
2252
|
-
function safeSessionId(sessionId) {
|
|
2253
|
-
return sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80) || "default";
|
|
2254
|
-
}
|
|
2255
|
-
function statePath(cwd, sessionId) {
|
|
2256
|
-
return join13(cwd, STATE_DIR, `lint-${safeSessionId(sessionId)}.json`);
|
|
2257
|
-
}
|
|
2258
|
-
function readState(cwd, sessionId) {
|
|
2259
|
-
const path = statePath(cwd, sessionId);
|
|
2260
|
-
if (!existsSync11(path)) return null;
|
|
2261
|
-
try {
|
|
2262
|
-
const raw = JSON.parse(readFileSync8(path, "utf8"));
|
|
2263
|
-
return LintStateSchema.parse(raw);
|
|
2264
|
-
} catch {
|
|
2265
|
-
return null;
|
|
2266
|
-
}
|
|
2267
|
-
}
|
|
2268
|
-
function writeState(cwd, sessionId, state) {
|
|
2269
|
-
const path = statePath(cwd, sessionId);
|
|
2270
|
-
mkdirSync3(dirname6(path), { recursive: true });
|
|
2271
|
-
writeFileSync5(path, `${JSON.stringify(state, null, 2)}
|
|
2272
|
-
`);
|
|
2273
|
-
}
|
|
2274
|
-
function resetState(cwd, sessionId) {
|
|
2275
|
-
const path = statePath(cwd, sessionId);
|
|
2276
|
-
if (existsSync11(path)) rmSync(path, { force: true });
|
|
2277
|
-
}
|
|
2278
|
-
|
|
2279
|
-
// src/stop-hook/types.ts
|
|
2280
|
-
var STOP_HOOK_ENGINES = ["claude", "codex", "opencode"];
|
|
2281
|
-
var DEFAULT_MAX_ATTEMPTS = 3;
|
|
2282
|
-
|
|
2283
|
-
// src/stop-hook/core.ts
|
|
2284
|
-
function exhaustedReason(attempts, lintOutput) {
|
|
2285
|
-
return `Harness lint: still failing after ${attempts} attempts.
|
|
2286
|
-
|
|
2287
|
-
${lintOutput}`;
|
|
2288
|
-
}
|
|
2289
|
-
function noProgressReason(lintOutput) {
|
|
2290
|
-
return `Harness lint: no progress between attempts.
|
|
2291
|
-
|
|
2292
|
-
${lintOutput}`;
|
|
2293
|
-
}
|
|
2294
|
-
function hash(s) {
|
|
2295
|
-
return createHash2("sha256").update(s).digest("hex").slice(0, 16);
|
|
2296
|
-
}
|
|
2297
|
-
function maxAttempts(env) {
|
|
2298
|
-
const raw = env.HARNESS_LINT_MAX_ATTEMPTS;
|
|
2299
|
-
if (!raw) return DEFAULT_MAX_ATTEMPTS;
|
|
2300
|
-
const n = Number.parseInt(raw, 10);
|
|
2301
|
-
return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_ATTEMPTS;
|
|
2302
|
-
}
|
|
2303
|
-
function defaultGitStatus(cwd) {
|
|
2304
|
-
try {
|
|
2305
|
-
return execFileSync2("git", ["status", "--porcelain"], {
|
|
2306
|
-
cwd,
|
|
2307
|
-
encoding: "utf8",
|
|
2308
|
-
stdio: ["ignore", "pipe", "ignore"]
|
|
2309
|
-
});
|
|
2310
|
-
} catch {
|
|
2311
|
-
return "";
|
|
2312
|
-
}
|
|
2313
|
-
}
|
|
2314
|
-
function defaultRunLint(cwd) {
|
|
2315
|
-
const report = runLinters(cwd);
|
|
2316
|
-
return { pass: report.summary.pass, output: formatReportText(report) };
|
|
2317
|
-
}
|
|
2318
|
-
function decide(payload, coreEnv) {
|
|
2319
|
-
if (coreEnv.env.HARNESS_LINT_DISABLE === "1") {
|
|
2320
|
-
return { kind: "passthrough" };
|
|
2321
|
-
}
|
|
2322
|
-
if (payload.stopHookActive) {
|
|
2323
|
-
return { kind: "passthrough" };
|
|
2324
|
-
}
|
|
2325
|
-
const dirty = coreEnv.gitStatus(coreEnv.cwd);
|
|
2326
|
-
if (dirty.trim() === "") {
|
|
2327
|
-
resetState(coreEnv.cwd, payload.sessionId);
|
|
2328
|
-
return { kind: "passthrough" };
|
|
2329
|
-
}
|
|
2330
|
-
const lintResult = coreEnv.runLint(coreEnv.cwd);
|
|
2331
|
-
if (lintResult.pass) {
|
|
2332
|
-
resetState(coreEnv.cwd, payload.sessionId);
|
|
2333
|
-
return { kind: "passthrough" };
|
|
2334
|
-
}
|
|
2335
|
-
const lintHash = hash(lintResult.output);
|
|
2336
|
-
const prev = readState(coreEnv.cwd, payload.sessionId);
|
|
2337
|
-
if (prev && prev.attempts > 0 && prev.lastLintHash === lintHash) {
|
|
2338
|
-
resetState(coreEnv.cwd, payload.sessionId);
|
|
2339
|
-
return { kind: "terminate", reason: noProgressReason(lintResult.output) };
|
|
2340
|
-
}
|
|
2341
|
-
const nextAttempts = (prev?.attempts ?? 0) + 1;
|
|
2342
|
-
const limit = maxAttempts(coreEnv.env);
|
|
2343
|
-
if (nextAttempts > limit) {
|
|
2344
|
-
resetState(coreEnv.cwd, payload.sessionId);
|
|
2345
|
-
return { kind: "terminate", reason: exhaustedReason(limit, lintResult.output) };
|
|
2346
|
-
}
|
|
2347
|
-
writeState(coreEnv.cwd, payload.sessionId, {
|
|
2348
|
-
attempts: nextAttempts,
|
|
2349
|
-
lastLintHash: lintHash,
|
|
2350
|
-
updatedAt: (/* @__PURE__ */ new Date()).toISOString()
|
|
2351
|
-
});
|
|
2352
|
-
return { kind: "inject", reason: lintResult.output };
|
|
2353
|
-
}
|
|
2354
|
-
|
|
2355
|
-
// src/cli/stop-hook.ts
|
|
2356
|
-
function readStdinSync() {
|
|
2357
|
-
try {
|
|
2358
|
-
return readFileSync9(0, "utf8");
|
|
2359
|
-
} catch {
|
|
2360
|
-
return "";
|
|
2361
|
-
}
|
|
2362
|
-
}
|
|
2363
|
-
function assertEngine(engine) {
|
|
2364
|
-
if (!STOP_HOOK_ENGINES.includes(engine)) {
|
|
2365
|
-
throw new Error(`unknown engine: ${engine} (expected one of ${STOP_HOOK_ENGINES.join(", ")})`);
|
|
2366
|
-
}
|
|
2367
|
-
return engine;
|
|
2368
|
-
}
|
|
2369
|
-
function stopHookCommand(args, stdin) {
|
|
2370
|
-
const engine = assertEngine(args.engine);
|
|
2371
|
-
const cwd = resolve5(args.cwd ?? ".");
|
|
2372
|
-
const adapter = getAdapter(engine);
|
|
2373
|
-
const payload = adapter.parseInput(stdin, process.env);
|
|
2374
|
-
const decision = decide(payload, {
|
|
2375
|
-
cwd,
|
|
2376
|
-
env: process.env,
|
|
2377
|
-
gitStatus: defaultGitStatus,
|
|
2378
|
-
runLint: defaultRunLint
|
|
2379
|
-
});
|
|
2380
|
-
return adapter.respond(decision);
|
|
2381
|
-
}
|
|
2382
|
-
function stopHookCommandFromStdin(args) {
|
|
2383
|
-
return stopHookCommand(args, readStdinSync());
|
|
2384
|
-
}
|
|
2385
|
-
|
|
2386
|
-
// src/cli/update.ts
|
|
2387
|
-
import { existsSync as existsSync13, readFileSync as readFileSync12 } from "fs";
|
|
2388
|
-
import { join as join16, resolve as resolve7 } from "path";
|
|
2389
|
-
import { isDeepStrictEqual as isDeepStrictEqual3 } from "util";
|
|
2390
|
-
|
|
2391
|
-
// src/cli/update-manifest.ts
|
|
2392
|
-
import { existsSync as existsSync12, readFileSync as readFileSync10 } from "fs";
|
|
2393
|
-
import { join as join14 } from "path";
|
|
2394
|
-
import { z as z7 } from "zod";
|
|
2395
|
-
var EngineSchema = z7.enum(ENGINES);
|
|
2396
|
-
var LegacySchema = z7.object({
|
|
2397
|
-
version: z7.enum(["1", "2", "3"]),
|
|
2398
|
-
engine: EngineSchema.optional(),
|
|
2399
|
-
engines: z7.array(EngineSchema).nonempty().optional(),
|
|
2400
|
-
renderedAt: z7.string(),
|
|
2401
|
-
files: z7.array(z7.string())
|
|
2402
|
-
});
|
|
2403
|
-
var HOOK_PATHS = {
|
|
2404
|
-
"claude-code": [".claude/settings.json"],
|
|
2405
|
-
"codex-cli": [".codex/hooks.json"],
|
|
2406
|
-
opencode: [
|
|
2407
|
-
".opencode/plugins/harness-stop-hook/index.ts",
|
|
2408
|
-
".opencode/plugins/harness-stop-hook.ts"
|
|
2409
|
-
]
|
|
2410
|
-
};
|
|
2411
|
-
function readUpdateInstallation(root) {
|
|
2412
|
-
assertManagedPaths(root, [MANIFEST_FILENAME]);
|
|
2413
|
-
if (!existsSync12(join14(root, MANIFEST_FILENAME))) {
|
|
2414
|
-
throw new Error("no harness manifest found; use init for a new installation");
|
|
2415
|
-
}
|
|
2416
|
-
const raw = JSON.parse(readFileSync10(join14(root, MANIFEST_FILENAME), "utf8"));
|
|
2417
|
-
const sourceVersion = String(raw?.version);
|
|
2418
|
-
let manifest;
|
|
2419
|
-
if (["1", "2", "3"].includes(sourceVersion)) {
|
|
2420
|
-
const legacy = LegacySchema.parse(raw);
|
|
2421
|
-
const engines2 = legacy.version === "1" ? [EngineSchema.parse(legacy.engine)] : legacy.engines;
|
|
2422
|
-
manifest = {
|
|
2423
|
-
version: "4",
|
|
2424
|
-
engines: z7.array(EngineSchema).nonempty().parse(engines2),
|
|
2425
|
-
files: legacy.files,
|
|
2426
|
-
renderedAt: legacy.renderedAt
|
|
2427
|
-
};
|
|
2428
|
-
} else {
|
|
2429
|
-
const current = readManifest(root);
|
|
2430
|
-
if (!current) throw new Error("harness manifest disappeared during planning");
|
|
2431
|
-
manifest = current;
|
|
2432
|
-
}
|
|
2433
|
-
const engines = [...new Set(z7.array(EngineSchema).nonempty().parse(manifest.engines))];
|
|
2434
|
-
const hookEngines = manifest.stopHookInstalled === false ? [] : manifest.stopHookEngines !== void 0 ? z7.array(EngineSchema).parse(manifest.stopHookEngines) : manifest.stopHookInstalled === true ? engines : engines.filter(
|
|
2435
|
-
(engine) => HOOK_PATHS[engine].some((path) => manifest.files.includes(path))
|
|
2436
|
-
);
|
|
2437
|
-
if (hookEngines.some((engine) => !engines.includes(engine))) {
|
|
2438
|
-
throw new Error("manifest stopHookEngines must be a subset of installed engines");
|
|
2439
|
-
}
|
|
2440
|
-
return { manifest, sourceVersion, engines, hookEngines: [...new Set(hookEngines)] };
|
|
2441
|
-
}
|
|
2442
|
-
|
|
2443
1499
|
// src/cli/update-transaction.ts
|
|
2444
|
-
import { createHash as
|
|
1500
|
+
import { createHash as createHash2, randomUUID } from "crypto";
|
|
2445
1501
|
import {
|
|
2446
1502
|
chmodSync as chmodSync2,
|
|
2447
1503
|
closeSync,
|
|
2448
1504
|
fsyncSync,
|
|
2449
1505
|
lstatSync as lstatSync2,
|
|
2450
|
-
mkdirSync
|
|
1506
|
+
mkdirSync,
|
|
2451
1507
|
openSync,
|
|
2452
|
-
readFileSync as
|
|
1508
|
+
readFileSync as readFileSync8,
|
|
2453
1509
|
readdirSync as readdirSync2,
|
|
2454
1510
|
realpathSync as realpathSync2,
|
|
2455
1511
|
rmdirSync as rmdirSync2,
|
|
2456
1512
|
unlinkSync as unlinkSync2,
|
|
2457
|
-
writeFileSync as
|
|
1513
|
+
writeFileSync as writeFileSync2
|
|
2458
1514
|
} from "fs";
|
|
2459
1515
|
import { homedir } from "os";
|
|
2460
|
-
import { basename as basename3, dirname as
|
|
1516
|
+
import { basename as basename3, dirname as dirname5, isAbsolute as isAbsolute3, join as join11, relative as relative3, resolve as resolve6, sep } from "path";
|
|
2461
1517
|
var MANIFEST_PATH = ".harness-manifest.json";
|
|
2462
|
-
var PRIVATE_FILES = /* @__PURE__ */ new Set([
|
|
2463
|
-
MANIFEST_PATH,
|
|
2464
|
-
".mcp.json",
|
|
2465
|
-
".codex/config.toml",
|
|
2466
|
-
".codex/hooks.json",
|
|
2467
|
-
".claude/settings.json",
|
|
2468
|
-
".opencode/opencode.json",
|
|
2469
|
-
".opencode/mcp.json"
|
|
2470
|
-
]);
|
|
1518
|
+
var PRIVATE_FILES = /* @__PURE__ */ new Set([MANIFEST_PATH]);
|
|
2471
1519
|
function canonicalRoot(root) {
|
|
2472
1520
|
let ancestor = resolve6(root);
|
|
2473
1521
|
const missing = [];
|
|
2474
1522
|
while (!lstatSync2(ancestor, { throwIfNoEntry: false })) {
|
|
2475
1523
|
missing.unshift(basename3(ancestor));
|
|
2476
|
-
ancestor =
|
|
1524
|
+
ancestor = dirname5(ancestor);
|
|
2477
1525
|
}
|
|
2478
|
-
return
|
|
1526
|
+
return join11(realpathSync2(ancestor), ...missing);
|
|
2479
1527
|
}
|
|
2480
1528
|
function contains(parent, child) {
|
|
2481
1529
|
const path = relative3(parent, child);
|
|
@@ -2486,9 +1534,9 @@ function assertBackupLocation(root, backup) {
|
|
|
2486
1534
|
throw new Error(`update backup must be outside the target project: ${backup}`);
|
|
2487
1535
|
}
|
|
2488
1536
|
const ancestors = [];
|
|
2489
|
-
for (let path = backup; ; path =
|
|
1537
|
+
for (let path = backup; ; path = dirname5(path)) {
|
|
2490
1538
|
ancestors.unshift(path);
|
|
2491
|
-
if (
|
|
1539
|
+
if (dirname5(path) === path) break;
|
|
2492
1540
|
}
|
|
2493
1541
|
for (const path of ancestors) {
|
|
2494
1542
|
const info = lstatSync2(path, { throwIfNoEntry: false });
|
|
@@ -2503,19 +1551,19 @@ function assertBackupLocation(root, backup) {
|
|
|
2503
1551
|
}
|
|
2504
1552
|
function createDirectories(path, created, mode = 511) {
|
|
2505
1553
|
const missing = [];
|
|
2506
|
-
for (let current = path; !lstatSync2(current, { throwIfNoEntry: false }); current =
|
|
1554
|
+
for (let current = path; !lstatSync2(current, { throwIfNoEntry: false }); current = dirname5(current)) {
|
|
2507
1555
|
missing.unshift(current);
|
|
2508
1556
|
}
|
|
2509
1557
|
for (const directory of missing) {
|
|
2510
|
-
|
|
1558
|
+
mkdirSync(directory, { mode });
|
|
2511
1559
|
created.push(directory);
|
|
2512
1560
|
}
|
|
2513
1561
|
}
|
|
2514
1562
|
function writeBackupFile(path, content) {
|
|
2515
|
-
createDirectories(
|
|
1563
|
+
createDirectories(dirname5(path), [], 448);
|
|
2516
1564
|
const fd = openSync(path, "wx", 384);
|
|
2517
1565
|
try {
|
|
2518
|
-
|
|
1566
|
+
writeFileSync2(fd, content);
|
|
2519
1567
|
fsyncSync(fd);
|
|
2520
1568
|
} finally {
|
|
2521
1569
|
closeSync(fd);
|
|
@@ -2523,26 +1571,26 @@ function writeBackupFile(path, content) {
|
|
|
2523
1571
|
}
|
|
2524
1572
|
function saveSnapshot(root, paths, backup) {
|
|
2525
1573
|
const entries = [];
|
|
2526
|
-
createDirectories(
|
|
2527
|
-
|
|
1574
|
+
createDirectories(dirname5(backup), [], 448);
|
|
1575
|
+
mkdirSync(backup, { mode: 448 });
|
|
2528
1576
|
for (const path of paths) {
|
|
2529
|
-
const full =
|
|
1577
|
+
const full = join11(root, path);
|
|
2530
1578
|
const info = lstatSync2(full, { throwIfNoEntry: false });
|
|
2531
1579
|
if (!info) {
|
|
2532
1580
|
entries.push({ path, exists: false });
|
|
2533
1581
|
continue;
|
|
2534
1582
|
}
|
|
2535
|
-
const content =
|
|
2536
|
-
writeBackupFile(
|
|
1583
|
+
const content = readFileSync8(full);
|
|
1584
|
+
writeBackupFile(join11(backup, "files", path), content);
|
|
2537
1585
|
entries.push({
|
|
2538
1586
|
path,
|
|
2539
1587
|
exists: true,
|
|
2540
1588
|
mode: info.mode & 4095,
|
|
2541
|
-
sha256:
|
|
1589
|
+
sha256: createHash2("sha256").update(content).digest("hex")
|
|
2542
1590
|
});
|
|
2543
1591
|
}
|
|
2544
1592
|
writeBackupFile(
|
|
2545
|
-
|
|
1593
|
+
join11(backup, "snapshot.json"),
|
|
2546
1594
|
`${JSON.stringify({ version: 1, root, createdAt: (/* @__PURE__ */ new Date()).toISOString(), entries }, null, 2)}
|
|
2547
1595
|
`
|
|
2548
1596
|
);
|
|
@@ -2557,16 +1605,16 @@ function rollback(root, backup, entries, touched, createdDirectories) {
|
|
|
2557
1605
|
try {
|
|
2558
1606
|
assertManagedPaths(root, [path]);
|
|
2559
1607
|
const entry = entries.get(path);
|
|
2560
|
-
const full =
|
|
1608
|
+
const full = join11(root, path);
|
|
2561
1609
|
const current = lstatSync2(full, { throwIfNoEntry: false });
|
|
2562
1610
|
if (!entry?.exists) {
|
|
2563
1611
|
if (current) unlinkSync2(full);
|
|
2564
1612
|
continue;
|
|
2565
1613
|
}
|
|
2566
|
-
const original =
|
|
2567
|
-
if (!current || !
|
|
1614
|
+
const original = readFileSync8(join11(backup, "files", path));
|
|
1615
|
+
if (!current || !readFileSync8(full).equals(original)) {
|
|
2568
1616
|
if (current) unlinkSync2(full);
|
|
2569
|
-
|
|
1617
|
+
writeFileSync2(full, original, { mode: 384 });
|
|
2570
1618
|
}
|
|
2571
1619
|
chmodSync2(full, entry.mode);
|
|
2572
1620
|
} catch (error) {
|
|
@@ -2587,7 +1635,7 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
|
|
|
2587
1635
|
assertManagedPaths(root, paths);
|
|
2588
1636
|
const target = canonicalRoot(root);
|
|
2589
1637
|
const backup = resolve6(
|
|
2590
|
-
backupDir ??
|
|
1638
|
+
backupDir ?? join11(homedir(), ".local", "state", "vaubaan-harness", "backups", randomUUID())
|
|
2591
1639
|
);
|
|
2592
1640
|
assertBackupLocation(target, backup);
|
|
2593
1641
|
let snapshot;
|
|
@@ -2605,18 +1653,18 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
|
|
|
2605
1653
|
try {
|
|
2606
1654
|
assertManagedPaths(target, paths);
|
|
2607
1655
|
for (const path of removals) {
|
|
2608
|
-
if (!lstatSync2(
|
|
1656
|
+
if (!lstatSync2(join11(target, path), { throwIfNoEntry: false })) continue;
|
|
2609
1657
|
touched.add(path);
|
|
2610
|
-
unlinkSync2(
|
|
1658
|
+
unlinkSync2(join11(target, path));
|
|
2611
1659
|
}
|
|
2612
1660
|
for (const file of writes) {
|
|
2613
|
-
const full =
|
|
2614
|
-
createDirectories(
|
|
1661
|
+
const full = join11(target, file.path);
|
|
1662
|
+
createDirectories(dirname5(full), createdDirectories);
|
|
2615
1663
|
touched.add(file.path);
|
|
2616
1664
|
const entry = entries.get(file.path);
|
|
2617
1665
|
const mode = file.path === MANIFEST_PATH ? 384 : entry?.exists ? entry.mode : PRIVATE_FILES.has(file.path) ? 384 : 420;
|
|
2618
1666
|
if (entry?.exists && file.path === MANIFEST_PATH) chmodSync2(full, mode);
|
|
2619
|
-
|
|
1667
|
+
writeFileSync2(full, file.content, { mode });
|
|
2620
1668
|
if (entry?.exists) chmodSync2(full, mode);
|
|
2621
1669
|
}
|
|
2622
1670
|
} catch (error) {
|
|
@@ -2630,50 +1678,115 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
|
|
|
2630
1678
|
}
|
|
2631
1679
|
|
|
2632
1680
|
// src/cli/update.ts
|
|
1681
|
+
import { existsSync as existsSync11, readFileSync as readFileSync10 } from "fs";
|
|
1682
|
+
import { dirname as dirname6, join as join13, resolve as resolve7 } from "path";
|
|
1683
|
+
import { isDeepStrictEqual } from "util";
|
|
1684
|
+
|
|
1685
|
+
// src/cli/update-manifest.ts
|
|
1686
|
+
import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
|
|
1687
|
+
import { join as join12 } from "path";
|
|
1688
|
+
import { z as z4 } from "zod";
|
|
1689
|
+
var EngineSchema = z4.enum(ENGINES);
|
|
1690
|
+
var LegacySchema = z4.object({
|
|
1691
|
+
version: z4.enum(["1", "2", "3"]),
|
|
1692
|
+
engine: EngineSchema.optional(),
|
|
1693
|
+
engines: z4.array(EngineSchema).nonempty().optional(),
|
|
1694
|
+
renderedAt: z4.string(),
|
|
1695
|
+
files: z4.array(z4.string())
|
|
1696
|
+
});
|
|
1697
|
+
function readUpdateInstallation(root) {
|
|
1698
|
+
assertManagedPaths(root, [MANIFEST_FILENAME]);
|
|
1699
|
+
if (!existsSync10(join12(root, MANIFEST_FILENAME))) {
|
|
1700
|
+
throw new Error("no harness manifest found; use init for a new installation");
|
|
1701
|
+
}
|
|
1702
|
+
const raw = JSON.parse(readFileSync9(join12(root, MANIFEST_FILENAME), "utf8"));
|
|
1703
|
+
const sourceVersion = String(raw?.version);
|
|
1704
|
+
let manifest;
|
|
1705
|
+
if (["1", "2", "3"].includes(sourceVersion)) {
|
|
1706
|
+
const legacy = LegacySchema.parse(raw);
|
|
1707
|
+
const engines2 = legacy.version === "1" ? [EngineSchema.parse(legacy.engine)] : legacy.engines;
|
|
1708
|
+
manifest = {
|
|
1709
|
+
version: "4",
|
|
1710
|
+
engines: z4.array(EngineSchema).nonempty().parse(engines2),
|
|
1711
|
+
files: legacy.files,
|
|
1712
|
+
renderedAt: legacy.renderedAt
|
|
1713
|
+
};
|
|
1714
|
+
} else {
|
|
1715
|
+
const current = readManifest(root);
|
|
1716
|
+
if (!current) throw new Error("harness manifest disappeared during planning");
|
|
1717
|
+
manifest = current;
|
|
1718
|
+
}
|
|
1719
|
+
const engines = [...new Set(z4.array(EngineSchema).nonempty().parse(manifest.engines))];
|
|
1720
|
+
return { manifest, sourceVersion, engines };
|
|
1721
|
+
}
|
|
1722
|
+
|
|
1723
|
+
// src/cli/update.ts
|
|
1724
|
+
var LEGACY_HOOK_FILES = [".claude/settings.json", ".codex/hooks.json"];
|
|
1725
|
+
var LEGACY_HOOK_MARKER = "@vaubaan/harness stop-hook";
|
|
2633
1726
|
function currentContent(root, path) {
|
|
2634
|
-
return
|
|
1727
|
+
return existsSync11(join13(root, path)) ? readFileSync10(join13(root, path), "utf8") : void 0;
|
|
2635
1728
|
}
|
|
2636
1729
|
function checkArtifactConflicts(root, previous, writes, removals) {
|
|
2637
1730
|
const desired = new Map(writes.map((file) => [file.path, file.content]));
|
|
1731
|
+
const conflicts = [];
|
|
2638
1732
|
for (const path of [...desired.keys(), ...removals]) {
|
|
2639
|
-
if (SHARED_CONFIG_PATHS.includes(path)) continue;
|
|
2640
1733
|
const content = currentContent(root, path);
|
|
2641
|
-
if (content === void 0) continue;
|
|
1734
|
+
if (content === void 0 || content === desired.get(path)) continue;
|
|
2642
1735
|
if (!previous.files.includes(path)) {
|
|
2643
|
-
|
|
2644
|
-
|
|
2645
|
-
);
|
|
1736
|
+
conflicts.push(`existing file outside harness manifest: ${path}`);
|
|
1737
|
+
continue;
|
|
2646
1738
|
}
|
|
2647
|
-
const
|
|
2648
|
-
if (
|
|
2649
|
-
|
|
1739
|
+
const hash = previous.fileHashes?.[path];
|
|
1740
|
+
if (hash && hash !== hashContent(content)) conflicts.push(`modified harness file: ${path}`);
|
|
1741
|
+
}
|
|
1742
|
+
if (conflicts.length) {
|
|
1743
|
+
throw new Error(
|
|
1744
|
+
`${conflicts.join("\n")}
|
|
1745
|
+
move their content to docs/ or .harness-overrides/, or keep them as yours with --preserve <path>`
|
|
1746
|
+
);
|
|
1747
|
+
}
|
|
1748
|
+
}
|
|
1749
|
+
function releaseLegacyPaths(previous, warnings) {
|
|
1750
|
+
const released = previous.files.filter((path) => RELEASED_PATHS.includes(path));
|
|
1751
|
+
for (const path of released) {
|
|
1752
|
+
warnings.push(`no longer managed by the harness, left in place: ${path}`);
|
|
1753
|
+
}
|
|
1754
|
+
if (released.length === 0) return previous;
|
|
1755
|
+
return { ...previous, files: previous.files.filter((path) => !released.includes(path)) };
|
|
1756
|
+
}
|
|
1757
|
+
function legacyHookWarnings(root) {
|
|
1758
|
+
const warnings = [];
|
|
1759
|
+
for (const path of LEGACY_HOOK_FILES) {
|
|
1760
|
+
const content = currentContent(root, path);
|
|
1761
|
+
if (content?.includes(LEGACY_HOOK_MARKER)) {
|
|
1762
|
+
warnings.push(
|
|
1763
|
+
`remove the harness Stop hook entry from ${path}: the Stop hook was removed in 2.0, run \`npx @vaubaan/harness lint\` in CI and pre-commit instead`
|
|
1764
|
+
);
|
|
2650
1765
|
}
|
|
2651
1766
|
}
|
|
1767
|
+
return warnings;
|
|
2652
1768
|
}
|
|
2653
|
-
function
|
|
1769
|
+
function planInstallation(args, settings) {
|
|
2654
1770
|
const root = resolve7(args.targetDir);
|
|
2655
|
-
const {
|
|
1771
|
+
const { engines } = settings;
|
|
1772
|
+
const warnings = [];
|
|
1773
|
+
const previous = releaseLegacyPaths(settings.previous, warnings);
|
|
2656
1774
|
const preserved = [
|
|
2657
1775
|
.../* @__PURE__ */ new Set([...previous.preservedFiles ?? [], ...args.preserveFiles ?? []])
|
|
2658
1776
|
].sort();
|
|
2659
1777
|
if (preserved.includes(MANIFEST_FILENAME))
|
|
2660
1778
|
throw new Error("cannot preserve the harness manifest");
|
|
2661
|
-
|
|
2662
|
-
throw new Error(
|
|
2663
|
-
"--preserve applies to generated artifacts; shared configurations use entry-level preservation"
|
|
2664
|
-
);
|
|
2665
|
-
}
|
|
2666
|
-
assertManagedPaths(root, [...previous.files, ...preserved, ...SHARED_CONFIG_PATHS]);
|
|
1779
|
+
assertManagedPaths(root, [...previous.files, ...preserved]);
|
|
2667
1780
|
const requestedOverrides = args.overridesDir ?? previous.overridesDir;
|
|
2668
1781
|
const overridesDir = args.overridesDir ? resolve7(args.overridesDir) : previous.overridesDir ? resolve7(root, previous.overridesDir) : root;
|
|
2669
|
-
if (requestedOverrides && !
|
|
1782
|
+
if (requestedOverrides && !existsSync11(join13(overridesDir, ".harness-overrides"))) {
|
|
2670
1783
|
throw new Error(`recorded overrides are missing: ${overridesDir}/.harness-overrides`);
|
|
2671
1784
|
}
|
|
2672
|
-
const hasOverrides =
|
|
2673
|
-
const disablePath =
|
|
2674
|
-
if (
|
|
1785
|
+
const hasOverrides = existsSync11(join13(overridesDir, ".harness-overrides"));
|
|
1786
|
+
const disablePath = join13(overridesDir, ".harness-overrides", "disable.yaml");
|
|
1787
|
+
if (existsSync11(disablePath)) {
|
|
2675
1788
|
try {
|
|
2676
|
-
DisableYamlSchema.parse(parseYAML(
|
|
1789
|
+
DisableYamlSchema.parse(parseYAML(readFileSync10(disablePath, "utf8")));
|
|
2677
1790
|
} catch {
|
|
2678
1791
|
throw new Error(`invalid override selection: ${disablePath}`);
|
|
2679
1792
|
}
|
|
@@ -2682,33 +1795,16 @@ function planUpdate(args) {
|
|
|
2682
1795
|
targetDir: root,
|
|
2683
1796
|
packageDir: args.packageDir,
|
|
2684
1797
|
engines,
|
|
2685
|
-
overridesDir: hasOverrides ? overridesDir : void 0
|
|
2686
|
-
withStopHook: false
|
|
1798
|
+
overridesDir: hasOverrides ? overridesDir : void 0
|
|
2687
1799
|
});
|
|
2688
|
-
const
|
|
2689
|
-
const
|
|
2690
|
-
|
|
1800
|
+
const output = rendered.output.files.filter((file) => !preserved.includes(file.path));
|
|
1801
|
+
const owned = output.map((file) => file.path).sort();
|
|
1802
|
+
const removals = previous.files.filter(
|
|
1803
|
+
(file) => !owned.includes(file) && !preserved.includes(file)
|
|
2691
1804
|
);
|
|
2692
|
-
|
|
2693
|
-
.../* @__PURE__ */ new Set([...rendered.output.files.map((file) => file.path), ...config.ownedFiles])
|
|
2694
|
-
].filter((file) => !preserved.includes(file)).sort();
|
|
2695
|
-
const removals = [
|
|
2696
|
-
.../* @__PURE__ */ new Set([
|
|
2697
|
-
...previous.files.filter(
|
|
2698
|
-
(file) => !owned.includes(file) && !SHARED_CONFIG_PATHS.includes(file)
|
|
2699
|
-
),
|
|
2700
|
-
...config.removals
|
|
2701
|
-
])
|
|
2702
|
-
].filter((file) => !preserved.includes(file));
|
|
2703
|
-
assertManagedPaths(root, [...output.map((file) => file.path), ...removals]);
|
|
1805
|
+
assertManagedPaths(root, [...owned, ...removals]);
|
|
2704
1806
|
checkArtifactConflicts(root, previous, output, removals);
|
|
2705
|
-
const hashes = Object.fromEntries(
|
|
2706
|
-
owned.map((path) => {
|
|
2707
|
-
const content = output.find((file) => file.path === path)?.content ?? currentContent(root, path);
|
|
2708
|
-
if (content === void 0) throw new Error(`missing planned harness file: ${path}`);
|
|
2709
|
-
return [path, hashContent(content)];
|
|
2710
|
-
})
|
|
2711
|
-
);
|
|
1807
|
+
const hashes = Object.fromEntries(output.map((file) => [file.path, hashContent(file.content)]));
|
|
2712
1808
|
const manifest = {
|
|
2713
1809
|
version: MANIFEST_VERSION,
|
|
2714
1810
|
harnessVersion: VERSION,
|
|
@@ -2716,39 +1812,41 @@ function planUpdate(args) {
|
|
|
2716
1812
|
renderedAt: previous.renderedAt,
|
|
2717
1813
|
files: owned,
|
|
2718
1814
|
fileHashes: hashes,
|
|
2719
|
-
stopHookInstalled: hookEngines.length > 0,
|
|
2720
|
-
stopHookEngines: [...hookEngines].sort(),
|
|
2721
1815
|
...hasOverrides ? { overridesDir: overridesDir === root ? "." : overridesDir } : {},
|
|
2722
|
-
...preserved.length ? { preservedFiles: preserved } : {}
|
|
2723
|
-
...config.opencodeConfig ? { opencodeConfig: config.opencodeConfig } : {},
|
|
2724
|
-
...config.hookConfigs ? { hookConfigs: config.hookConfigs } : {}
|
|
1816
|
+
...preserved.length ? { preservedFiles: preserved } : {}
|
|
2725
1817
|
};
|
|
2726
1818
|
const writes = output.filter((file) => currentContent(root, file.path) !== file.content);
|
|
2727
|
-
const existingRemovals = removals.filter((path) =>
|
|
2728
|
-
if (writes.length || existingRemovals.length || !
|
|
1819
|
+
const existingRemovals = removals.filter((path) => existsSync11(join13(root, path)));
|
|
1820
|
+
if (writes.length || existingRemovals.length || !isDeepStrictEqual(settings.previous, manifest)) {
|
|
2729
1821
|
manifest.renderedAt = (/* @__PURE__ */ new Date()).toISOString();
|
|
2730
1822
|
writes.push({ path: MANIFEST_FILENAME, content: `${JSON.stringify(manifest, null, 2)}
|
|
2731
1823
|
` });
|
|
2732
1824
|
}
|
|
2733
|
-
|
|
1825
|
+
warnings.push(...rendered.output.warnings, ...legacyHookWarnings(root));
|
|
1826
|
+
if (preserved.length) warnings.push(`preserved user-owned artifacts: ${preserved.join(", ")}`);
|
|
1827
|
+
return { writes, removals: existingRemovals, owned, manifest, warnings };
|
|
1828
|
+
}
|
|
1829
|
+
function planUpdate(args) {
|
|
1830
|
+
const root = resolve7(args.targetDir);
|
|
1831
|
+
const { manifest: previous, sourceVersion, engines } = readUpdateInstallation(root);
|
|
1832
|
+
const plan = planInstallation(args, { previous, sourceVersion, engines });
|
|
1833
|
+
const warnings = [...plan.warnings];
|
|
2734
1834
|
if (!previous.fileHashes) {
|
|
2735
1835
|
warnings.push(
|
|
2736
1836
|
"legacy manifest has no file fingerprints: managed artifacts will be regenerated; backup preserves their previous contents"
|
|
2737
1837
|
);
|
|
2738
1838
|
}
|
|
2739
|
-
if (preserved.length) warnings.push(`preserved user-owned artifacts: ${preserved.join(", ")}`);
|
|
2740
|
-
if (engines.includes("codex-cli"))
|
|
2741
|
-
warnings.push("ensure .agents/ is ignored by Git (run harness check)");
|
|
2742
1839
|
return {
|
|
2743
|
-
writes,
|
|
2744
|
-
removals:
|
|
1840
|
+
writes: plan.writes,
|
|
1841
|
+
removals: plan.removals,
|
|
1842
|
+
owned: plan.owned,
|
|
2745
1843
|
result: {
|
|
2746
1844
|
version: VERSION,
|
|
2747
1845
|
fromManifestVersion: sourceVersion,
|
|
2748
1846
|
dryRun: args.dryRun === true,
|
|
2749
|
-
upToDate: writes.length === 0 &&
|
|
2750
|
-
filesToWrite: writes.map((file) => file.path),
|
|
2751
|
-
filesToRemove:
|
|
1847
|
+
upToDate: plan.writes.length === 0 && plan.removals.length === 0,
|
|
1848
|
+
filesToWrite: plan.writes.map((file) => file.path),
|
|
1849
|
+
filesToRemove: plan.removals,
|
|
2752
1850
|
warnings
|
|
2753
1851
|
}
|
|
2754
1852
|
};
|
|
@@ -2756,48 +1854,92 @@ function planUpdate(args) {
|
|
|
2756
1854
|
function updateCommand(args) {
|
|
2757
1855
|
const plan = planUpdate(args);
|
|
2758
1856
|
if (args.dryRun || plan.result.upToDate) return plan.result;
|
|
2759
|
-
const
|
|
2760
|
-
|
|
2761
|
-
|
|
2762
|
-
plan.removals,
|
|
2763
|
-
args.backupDir
|
|
2764
|
-
);
|
|
1857
|
+
const root = resolve7(args.targetDir);
|
|
1858
|
+
const { backupDir } = applyUpdateTransaction(root, plan.writes, plan.removals, args.backupDir);
|
|
1859
|
+
pruneEmptyDirs(root, new Set(plan.removals.map((path) => dirname6(join13(root, path)))));
|
|
2765
1860
|
return { ...plan.result, backupDir };
|
|
2766
1861
|
}
|
|
2767
1862
|
|
|
1863
|
+
// src/cli/init.ts
|
|
1864
|
+
function emptyManifest(engines) {
|
|
1865
|
+
return { version: MANIFEST_VERSION, engines: [...engines], renderedAt: "", files: [] };
|
|
1866
|
+
}
|
|
1867
|
+
function initCommand(args) {
|
|
1868
|
+
const root = resolve8(args.targetDir);
|
|
1869
|
+
const engines = resolveEngineList(args.engines);
|
|
1870
|
+
const previous = readManifest(root) ?? emptyManifest(engines);
|
|
1871
|
+
const plan = planInstallation(
|
|
1872
|
+
{
|
|
1873
|
+
targetDir: root,
|
|
1874
|
+
packageDir: args.packageDir,
|
|
1875
|
+
overridesDir: args.overridesDir,
|
|
1876
|
+
preserveFiles: args.preserveFiles
|
|
1877
|
+
},
|
|
1878
|
+
{ previous, sourceVersion: previous.version, engines }
|
|
1879
|
+
);
|
|
1880
|
+
const touchedExisting = [...plan.writes.map((file) => file.path), ...plan.removals].some(
|
|
1881
|
+
(path) => path !== MANIFEST_FILENAME && existsSync12(join14(root, path))
|
|
1882
|
+
);
|
|
1883
|
+
let backupDir;
|
|
1884
|
+
if (plan.writes.length || plan.removals.length) {
|
|
1885
|
+
backupDir = applyUpdateTransaction(root, plan.writes, plan.removals, args.backupDir).backupDir;
|
|
1886
|
+
if (!touchedExisting && !args.backupDir) {
|
|
1887
|
+
rmSync(backupDir, { recursive: true, force: true });
|
|
1888
|
+
backupDir = void 0;
|
|
1889
|
+
}
|
|
1890
|
+
pruneEmptyDirs(root, new Set(plan.removals.map((path) => dirname7(join14(root, path)))));
|
|
1891
|
+
}
|
|
1892
|
+
return {
|
|
1893
|
+
filesWritten: plan.owned,
|
|
1894
|
+
staleFilesRemoved: plan.removals,
|
|
1895
|
+
warnings: plan.warnings,
|
|
1896
|
+
engines,
|
|
1897
|
+
...backupDir ? { backupDir } : {}
|
|
1898
|
+
};
|
|
1899
|
+
}
|
|
1900
|
+
|
|
1901
|
+
// src/cli/render.ts
|
|
1902
|
+
import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
|
|
1903
|
+
import { dirname as dirname8, join as join15 } from "path";
|
|
1904
|
+
function renderCommand(args) {
|
|
1905
|
+
const engines = resolveEngineList(args.engines);
|
|
1906
|
+
const harness = loadHarness(args.packageDir);
|
|
1907
|
+
const output = render({ harness, engines });
|
|
1908
|
+
const filesWritten = [];
|
|
1909
|
+
for (const f of output.files) {
|
|
1910
|
+
const full = join15(args.outDir, f.path);
|
|
1911
|
+
mkdirSync3(dirname8(full), { recursive: true });
|
|
1912
|
+
writeFileSync4(full, f.content);
|
|
1913
|
+
filesWritten.push(f.path);
|
|
1914
|
+
}
|
|
1915
|
+
return { filesWritten, warnings: output.warnings };
|
|
1916
|
+
}
|
|
1917
|
+
|
|
2768
1918
|
// src/cli/index.ts
|
|
2769
1919
|
function resolvePackageDir() {
|
|
2770
|
-
const here =
|
|
2771
|
-
return
|
|
1920
|
+
const here = dirname9(fileURLToPath2(import.meta.url));
|
|
1921
|
+
return resolve9(here, "..");
|
|
1922
|
+
}
|
|
1923
|
+
function parseList(raw) {
|
|
1924
|
+
if (raw === void 0) return void 0;
|
|
1925
|
+
return raw.split(",").map((item) => item.trim()).filter(Boolean);
|
|
2772
1926
|
}
|
|
1927
|
+
var ENGINES_HELP = "comma-separated engines to render: claude-code, codex-cli, opencode";
|
|
2773
1928
|
var program = new Command();
|
|
2774
1929
|
program.name("vaubaan-harness").description(
|
|
2775
|
-
"Vaubaan harness \u2014 render skills
|
|
1930
|
+
"Vaubaan harness \u2014 keep a project's docs alive: render the doc skills into each engine's native layout, lint the docs in CI"
|
|
2776
1931
|
).version(VERSION);
|
|
2777
1932
|
program.command("init").description(
|
|
2778
|
-
"Render the harness (
|
|
2779
|
-
).argument("<target-dir>", "directory to render harness into").option(
|
|
2780
|
-
"--engines <list>",
|
|
2781
|
-
"comma-separated subset of engines (claude-code, codex-cli, opencode) \u2014 defaults to all 3"
|
|
2782
|
-
).option("--overrides-dir <dir>", "directory containing .harness-overrides/").option("--package-dir <dir>", "override harness package directory (for dev/test)").option(
|
|
2783
|
-
"--with-mcp <list>",
|
|
2784
|
-
"comma-separated MCP servers to render config for (context7) \u2014 opt-in"
|
|
2785
|
-
).option(
|
|
2786
|
-
"--no-stop-hook",
|
|
2787
|
-
"skip rendering the Stop-hook configs that run lint at end of each agent turn"
|
|
2788
|
-
).action((targetDir, opts) => {
|
|
1933
|
+
"Render the harness (doc skills, commands, AGENTS.md) into a project. Commit the result."
|
|
1934
|
+
).argument("<target-dir>", "directory to render harness into").requiredOption("--engines <list>", ENGINES_HELP).option("--overrides-dir <dir>", "directory containing .harness-overrides/").option("--package-dir <dir>", "override harness package directory (for dev/test)").option("--preserve <paths>", "comma-separated generated files to leave under user ownership").option("--backup-dir <dir>", "new backup directory outside the project").action((targetDir, opts) => {
|
|
2789
1935
|
const packageDir = opts.packageDir ?? resolvePackageDir();
|
|
2790
|
-
const enginesRaw = opts.engines;
|
|
2791
|
-
const engines = enginesRaw ? enginesRaw.split(",").map((s) => s.trim()) : void 0;
|
|
2792
|
-
const withMcpRaw = opts.withMcp;
|
|
2793
|
-
const mcpServers = withMcpRaw ? withMcpRaw.split(",").map((s) => s.trim()) : void 0;
|
|
2794
1936
|
const result = initCommand({
|
|
2795
1937
|
targetDir,
|
|
2796
|
-
engines,
|
|
1938
|
+
engines: parseList(opts.engines) ?? [],
|
|
2797
1939
|
overridesDir: opts.overridesDir,
|
|
2798
1940
|
packageDir,
|
|
2799
|
-
|
|
2800
|
-
|
|
1941
|
+
preserveFiles: parseList(opts.preserve),
|
|
1942
|
+
backupDir: opts.backupDir
|
|
2801
1943
|
});
|
|
2802
1944
|
process.stdout.write(`rendered ${result.filesWritten.length} files to ${targetDir}
|
|
2803
1945
|
`);
|
|
@@ -2807,20 +1949,15 @@ program.command("init").description(
|
|
|
2807
1949
|
`
|
|
2808
1950
|
);
|
|
2809
1951
|
}
|
|
2810
|
-
if (result.
|
|
2811
|
-
|
|
2812
|
-
if (result.filesWritten.includes(".codex/hooks.json")) {
|
|
2813
|
-
process.stdout.write(
|
|
2814
|
-
"codex: the hook runs once you trust this project and approve the hook (startup review or /hooks)\n"
|
|
2815
|
-
);
|
|
2816
|
-
}
|
|
2817
|
-
}
|
|
1952
|
+
if (result.backupDir) process.stdout.write(`backup: ${result.backupDir}
|
|
1953
|
+
`);
|
|
2818
1954
|
for (const w of result.warnings) process.stderr.write(`warning: ${w}
|
|
2819
1955
|
`);
|
|
1956
|
+
process.stdout.write(
|
|
1957
|
+
"next: commit the generated files, then run `npx @vaubaan/harness lint` before each commit (add it to your pre-commit hook and CI)\n"
|
|
1958
|
+
);
|
|
2820
1959
|
});
|
|
2821
|
-
program.command("update").description(
|
|
2822
|
-
"Migrate an existing harness installation, retaining its engines and project settings"
|
|
2823
|
-
).argument("[target-dir]", "project directory", ".").option("--dry-run", "preview changes without writing files or backups").option("--json", "print the migration summary as JSON").option("--backup-dir <dir>", "new backup directory outside the project").option("--overrides-dir <dir>", "directory containing .harness-overrides/").option("--preserve <paths>", "comma-separated generated files to leave under user ownership").action((targetDir, opts) => {
|
|
1960
|
+
program.command("update").description("Re-render an existing installation with this version, keeping its engines").argument("[target-dir]", "project directory", ".").option("--dry-run", "preview changes without writing files or backups").option("--json", "print the migration summary as JSON").option("--backup-dir <dir>", "new backup directory outside the project").option("--overrides-dir <dir>", "directory containing .harness-overrides/").option("--preserve <paths>", "comma-separated generated files to leave under user ownership").action((targetDir, opts) => {
|
|
2824
1961
|
const result = updateCommand({
|
|
2825
1962
|
targetDir,
|
|
2826
1963
|
packageDir: resolvePackageDir(),
|
|
@@ -2845,6 +1982,9 @@ program.command("update").description(
|
|
|
2845
1982
|
`);
|
|
2846
1983
|
for (const warning of result.warnings) process.stderr.write(`warning: ${warning}
|
|
2847
1984
|
`);
|
|
1985
|
+
if (!result.dryRun && !result.upToDate) {
|
|
1986
|
+
process.stdout.write("next: commit the generated files\n");
|
|
1987
|
+
}
|
|
2848
1988
|
});
|
|
2849
1989
|
program.command("uninstall").description("Remove all files previously written by `init` into a target directory").argument("<target-dir>", "directory to uninstall harness from").action((targetDir) => {
|
|
2850
1990
|
const result = uninstallCommand({ targetDir });
|
|
@@ -2855,7 +1995,7 @@ program.command("uninstall").description("Remove all files previously written by
|
|
|
2855
1995
|
for (const w of result.warnings) process.stderr.write(`warning: ${w}
|
|
2856
1996
|
`);
|
|
2857
1997
|
});
|
|
2858
|
-
program.command("check").description("Verify repo layout:
|
|
1998
|
+
program.command("check").description("Verify repo layout: doc pillars present and .gitignore correct").argument("<repo>", "path to repo to check").action((repo) => {
|
|
2859
1999
|
const result = checkCommand(repo);
|
|
2860
2000
|
if (result.pass) {
|
|
2861
2001
|
process.stdout.write("\u2714 layout OK\n");
|
|
@@ -2868,9 +2008,13 @@ program.command("check").description("Verify repo layout: 6 pillars present and
|
|
|
2868
2008
|
program.command("lint").description("Run all mechanical linters and exit non-zero on errors").option(
|
|
2869
2009
|
"--pillar <pillar>",
|
|
2870
2010
|
"filter by pillar (spec, decisions, handbook, tests, workflow, quality)"
|
|
2871
|
-
).option("--format <fmt>", "text | json", "text").option("--cwd <dir>", "repo root", ".").action((opts) => {
|
|
2872
|
-
const repoRoot =
|
|
2873
|
-
const
|
|
2011
|
+
).option("--only <ids>", "comma-separated linter ids to run (e.g. lint:cross-links)").option("--format <fmt>", "text | json", "text").option("--cwd <dir>", "repo root", ".").action((opts) => {
|
|
2012
|
+
const repoRoot = resolve9(opts.cwd ?? ".");
|
|
2013
|
+
const only = parseList(opts.only);
|
|
2014
|
+
const lintOpts = {
|
|
2015
|
+
...opts.pillar ? { pillar: opts.pillar } : {},
|
|
2016
|
+
...only && only.length > 0 ? { only } : {}
|
|
2017
|
+
};
|
|
2874
2018
|
const report = runLinters(repoRoot, lintOpts);
|
|
2875
2019
|
if (opts.format === "json") {
|
|
2876
2020
|
process.stdout.write(`${JSON.stringify(report, null, 2)}
|
|
@@ -2881,40 +2025,23 @@ program.command("lint").description("Run all mechanical linters and exit non-zer
|
|
|
2881
2025
|
}
|
|
2882
2026
|
process.exit(report.summary.pass ? 0 : 1);
|
|
2883
2027
|
});
|
|
2884
|
-
program.command("render").description("Render harness for preview (no overrides applied).
|
|
2885
|
-
"--engines <list>",
|
|
2886
|
-
"comma-separated subset of engines (claude-code, codex-cli, opencode) \u2014 defaults to all 3"
|
|
2887
|
-
).requiredOption("--out <dir>", "output directory").option("--package-dir <dir>", "override harness package directory").option(
|
|
2888
|
-
"--with-mcp <list>",
|
|
2889
|
-
"comma-separated MCP servers to render config for (context7) \u2014 opt-in"
|
|
2890
|
-
).option("--no-stop-hook", "skip rendering the Stop-hook configs").action((opts) => {
|
|
2028
|
+
program.command("render").description("Render harness for preview (no overrides applied)").requiredOption("--engines <list>", ENGINES_HELP).requiredOption("--out <dir>", "output directory").option("--package-dir <dir>", "override harness package directory").action((opts) => {
|
|
2891
2029
|
const packageDir = opts.packageDir ?? resolvePackageDir();
|
|
2892
|
-
const enginesRaw = opts.engines;
|
|
2893
|
-
const engines = enginesRaw ? enginesRaw.split(",").map((s) => s.trim()) : void 0;
|
|
2894
|
-
const withMcpRaw = opts.withMcp;
|
|
2895
|
-
const mcpServers = withMcpRaw ? withMcpRaw.split(",").map((s) => s.trim()) : void 0;
|
|
2896
2030
|
const result = renderCommand({
|
|
2897
|
-
engines,
|
|
2031
|
+
engines: parseList(opts.engines) ?? [],
|
|
2898
2032
|
outDir: opts.out,
|
|
2899
|
-
packageDir
|
|
2900
|
-
mcpServers,
|
|
2901
|
-
withStopHook: opts.stopHook !== false
|
|
2033
|
+
packageDir
|
|
2902
2034
|
});
|
|
2903
2035
|
process.stdout.write(`rendered ${result.filesWritten.length} files to ${opts.out}
|
|
2904
2036
|
`);
|
|
2905
2037
|
for (const w of result.warnings) process.stderr.write(`warning: ${w}
|
|
2906
2038
|
`);
|
|
2907
2039
|
});
|
|
2908
|
-
program.command("stop-hook").description(
|
|
2909
|
-
|
|
2910
|
-
|
|
2911
|
-
|
|
2912
|
-
|
|
2913
|
-
cwd: opts.cwd
|
|
2914
|
-
});
|
|
2915
|
-
if (result.stdout) process.stdout.write(result.stdout);
|
|
2916
|
-
if (result.stderr) process.stderr.write(result.stderr);
|
|
2917
|
-
process.exit(result.exitCode);
|
|
2040
|
+
program.command("stop-hook", { hidden: true }).description("deprecated no-op kept for Stop hook entries written by 1.x").option("--engine <engine>").option("--cwd <dir>").action(() => {
|
|
2041
|
+
process.stderr.write(
|
|
2042
|
+
"vaubaan-harness stop-hook was removed in 2.0: remove this entry from your engine settings and run `npx @vaubaan/harness lint` in CI and pre-commit instead\n"
|
|
2043
|
+
);
|
|
2044
|
+
process.exit(0);
|
|
2918
2045
|
});
|
|
2919
2046
|
program.parseAsync(process.argv).catch((err) => {
|
|
2920
2047
|
process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
|