@vaubaan/harness 2.1.0 → 2.3.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 +537 -67
- package/dist/cli/index.js +582 -83
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/doc-audit.cmd.md +1 -1
- package/dist/commands/intent.cmd.md +33 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +343 -63
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +1 -1
- package/dist/init.js +340 -60
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +536 -62
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +143 -1
- package/dist/parser/index.js +235 -4
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-C-FWmUfX.d.ts → render-CTx7VNOK.d.ts} +3 -1
- package/dist/render.d.ts +1 -1
- package/dist/render.js +98 -14
- package/dist/render.js.map +1 -1
- package/dist/skills/doc-audit.skill.md +35 -4
- package/dist/skills/drift-detector.skill.md +36 -5
- package/dist/skills/handbook-writer.skill.md +3 -0
- package/dist/skills/intent-writer.skill.md +174 -0
- package/dist/templates/e2e-tests.md.tmpl +1 -1
- package/dist/templates/integration-tests.md.tmpl +1 -1
- package/dist/templates/intent.md.tmpl +46 -0
- package/package.json +3 -7
package/dist/cli/index.js
CHANGED
|
@@ -17,6 +17,12 @@ function fileExists(repoRoot, relativePath) {
|
|
|
17
17
|
function readText(repoRoot, relativePath) {
|
|
18
18
|
return readFileSync(join(repoRoot, relativePath), "utf8");
|
|
19
19
|
}
|
|
20
|
+
function trackedPathExists(repoRoot, pattern) {
|
|
21
|
+
if (pattern.includes("*")) {
|
|
22
|
+
return fg.sync(pattern, { cwd: repoRoot, absolute: false }).length > 0;
|
|
23
|
+
}
|
|
24
|
+
return existsSync(join(repoRoot, pattern));
|
|
25
|
+
}
|
|
20
26
|
function listMarkdown(repoRoot, dir) {
|
|
21
27
|
const cwd = join(repoRoot, dir);
|
|
22
28
|
if (!existsSync(cwd)) return [];
|
|
@@ -300,16 +306,7 @@ var docLayout = {
|
|
|
300
306
|
};
|
|
301
307
|
|
|
302
308
|
// src/linters/frontmatter-tracks.ts
|
|
303
|
-
import { existsSync as existsSync3 } from "fs";
|
|
304
|
-
import { join as join3 } from "path";
|
|
305
|
-
import fg3 from "fast-glob";
|
|
306
309
|
var TRACKED_DIRS = ["docs/handbook", "docs/tests", "docs/workflow"];
|
|
307
|
-
function trackedPathExists(repoRoot, pattern) {
|
|
308
|
-
if (pattern.includes("*")) {
|
|
309
|
-
return fg3.sync(pattern, { cwd: repoRoot, absolute: false }).length > 0;
|
|
310
|
-
}
|
|
311
|
-
return existsSync3(join3(repoRoot, pattern));
|
|
312
|
-
}
|
|
313
310
|
var frontmatterTracks = {
|
|
314
311
|
id: "lint:frontmatter-tracks",
|
|
315
312
|
pillars: ["handbook", "tests", "workflow"],
|
|
@@ -357,13 +354,25 @@ var frontmatterTracks = {
|
|
|
357
354
|
};
|
|
358
355
|
|
|
359
356
|
// src/linters/generated-fresh.ts
|
|
360
|
-
import { existsSync as existsSync7, readFileSync as
|
|
357
|
+
import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
|
|
361
358
|
import { join as join8, resolve as resolve4 } from "path";
|
|
362
359
|
|
|
363
360
|
// src/cli/managed-paths.ts
|
|
364
361
|
import { lstatSync, realpathSync, statSync as statSync2 } from "fs";
|
|
365
|
-
import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as
|
|
366
|
-
var MANAGED_FILES = /* @__PURE__ */ new Set([
|
|
362
|
+
import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join3, resolve as resolve2, win32 } from "path";
|
|
363
|
+
var MANAGED_FILES = /* @__PURE__ */ new Set([
|
|
364
|
+
"AGENTS.md",
|
|
365
|
+
"CLAUDE.md",
|
|
366
|
+
".harness-manifest.json",
|
|
367
|
+
// Index of the optional intents pillar, rendered while an intent file exists.
|
|
368
|
+
"docs/intents/README.md",
|
|
369
|
+
// Its 2.2 location, kept managed so `update` can remove it (see MOVED_PATHS).
|
|
370
|
+
"docs/journeys/README.md"
|
|
371
|
+
]);
|
|
372
|
+
var MOVED_PATHS = /* @__PURE__ */ new Map([
|
|
373
|
+
// 2.3: the journeys pillar became the intents pillar.
|
|
374
|
+
["docs/journeys/README.md", "docs/intents/README.md"]
|
|
375
|
+
]);
|
|
367
376
|
var RELEASED_PATHS = [
|
|
368
377
|
".mcp.json",
|
|
369
378
|
".codex/config.toml",
|
|
@@ -396,7 +405,7 @@ function canonicalTargetRoot(root) {
|
|
|
396
405
|
if (!statSync2(canonical).isDirectory()) {
|
|
397
406
|
throw new Error(`harness target is not a directory: ${root}`);
|
|
398
407
|
}
|
|
399
|
-
return
|
|
408
|
+
return join3(canonical, ...missing);
|
|
400
409
|
}
|
|
401
410
|
function assertManagedLocation(path) {
|
|
402
411
|
const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
|
|
@@ -411,7 +420,7 @@ function assertNoSymbolicComponents(root, path) {
|
|
|
411
420
|
const parts = path.split("/");
|
|
412
421
|
let current = root;
|
|
413
422
|
for (const [index, part] of parts.entries()) {
|
|
414
|
-
current =
|
|
423
|
+
current = join3(current, part);
|
|
415
424
|
const info = lstatSync(current, { throwIfNoEntry: false });
|
|
416
425
|
if (!info) return;
|
|
417
426
|
if (info.isSymbolicLink()) {
|
|
@@ -431,12 +440,12 @@ function assertManagedPaths(root, files) {
|
|
|
431
440
|
|
|
432
441
|
// src/cli/manifest.ts
|
|
433
442
|
import { createHash } from "crypto";
|
|
434
|
-
import { chmodSync, existsSync as
|
|
435
|
-
import { join as
|
|
443
|
+
import { chmodSync, existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync } from "fs";
|
|
444
|
+
import { join as join4 } from "path";
|
|
436
445
|
import { z } from "zod";
|
|
437
446
|
|
|
438
447
|
// src/version.ts
|
|
439
|
-
var VERSION = "2.
|
|
448
|
+
var VERSION = "2.3.0";
|
|
440
449
|
|
|
441
450
|
// src/cli/manifest.ts
|
|
442
451
|
var MANIFEST_FILENAME = ".harness-manifest.json";
|
|
@@ -452,7 +461,7 @@ var ManifestSchema = z.object({
|
|
|
452
461
|
preservedFiles: z.array(z.string()).optional()
|
|
453
462
|
});
|
|
454
463
|
function manifestPath(targetDir) {
|
|
455
|
-
return
|
|
464
|
+
return join4(targetDir, MANIFEST_FILENAME);
|
|
456
465
|
}
|
|
457
466
|
function hashContent(content) {
|
|
458
467
|
return createHash("sha256").update(content).digest("hex");
|
|
@@ -460,7 +469,7 @@ function hashContent(content) {
|
|
|
460
469
|
function readManifest(targetDir) {
|
|
461
470
|
assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
|
|
462
471
|
const path = manifestPath(targetDir);
|
|
463
|
-
if (!
|
|
472
|
+
if (!existsSync3(path)) return null;
|
|
464
473
|
const raw = JSON.parse(readFileSync2(path, "utf8"));
|
|
465
474
|
return ManifestSchema.parse(raw);
|
|
466
475
|
}
|
|
@@ -471,9 +480,9 @@ import { dirname as dirname3, join as join7, resolve as resolve3 } from "path";
|
|
|
471
480
|
import { fileURLToPath } from "url";
|
|
472
481
|
|
|
473
482
|
// src/loader.ts
|
|
474
|
-
import { existsSync as
|
|
475
|
-
import { join as
|
|
476
|
-
import
|
|
483
|
+
import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
|
|
484
|
+
import { join as join5 } from "path";
|
|
485
|
+
import fg3 from "fast-glob";
|
|
477
486
|
import { z as z3 } from "zod";
|
|
478
487
|
|
|
479
488
|
// src/parser/common.ts
|
|
@@ -508,12 +517,16 @@ var CmdArgEnumSchema = z2.object({
|
|
|
508
517
|
name: z2.string().min(1),
|
|
509
518
|
type: z2.literal("enum"),
|
|
510
519
|
values: z2.array(z2.string()).min(1),
|
|
511
|
-
default: z2.string().optional()
|
|
520
|
+
default: z2.string().optional(),
|
|
521
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
522
|
+
required: z2.boolean().optional()
|
|
512
523
|
}).strict();
|
|
513
524
|
var CmdArgStringSchema = z2.object({
|
|
514
525
|
name: z2.string().min(1),
|
|
515
526
|
type: z2.literal("string"),
|
|
516
|
-
default: z2.string().optional()
|
|
527
|
+
default: z2.string().optional(),
|
|
528
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
529
|
+
required: z2.boolean().optional()
|
|
517
530
|
}).strict();
|
|
518
531
|
var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
|
|
519
532
|
var CmdFrontmatterSchema = z2.object({
|
|
@@ -523,9 +536,18 @@ var CmdFrontmatterSchema = z2.object({
|
|
|
523
536
|
args: z2.array(CmdArgSchema).optional(),
|
|
524
537
|
description: z2.string().min(1)
|
|
525
538
|
}).strict();
|
|
539
|
+
var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
|
|
540
|
+
var IntentFrontmatterSchema = z2.object({
|
|
541
|
+
title: z2.string().min(1),
|
|
542
|
+
status: z2.enum(INTENT_STATUSES),
|
|
543
|
+
actors: z2.array(z2.string().min(1)).min(1),
|
|
544
|
+
spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
|
|
545
|
+
last_reviewed: z2.union([z2.date(), z2.string().min(1)])
|
|
546
|
+
}).strict();
|
|
526
547
|
var Schemas = {
|
|
527
548
|
Skill: SkillFrontmatterSchema,
|
|
528
|
-
Cmd: CmdFrontmatterSchema
|
|
549
|
+
Cmd: CmdFrontmatterSchema,
|
|
550
|
+
Intent: IntentFrontmatterSchema
|
|
529
551
|
};
|
|
530
552
|
var ParseError = class extends Error {
|
|
531
553
|
constructor(file, issues) {
|
|
@@ -573,31 +595,31 @@ function parseYAML(source) {
|
|
|
573
595
|
// src/loader.ts
|
|
574
596
|
var DisableYamlSchema = z3.object({ disable: z3.array(z3.string()).optional() }).passthrough();
|
|
575
597
|
function loadHarness(packageDir, opts = {}) {
|
|
576
|
-
const skillsDir = opts.skillsDir ??
|
|
577
|
-
const commandsDir = opts.commandsDir ??
|
|
578
|
-
const skillFiles =
|
|
579
|
-
const cmdFiles =
|
|
598
|
+
const skillsDir = opts.skillsDir ?? join5(packageDir, "skills");
|
|
599
|
+
const commandsDir = opts.commandsDir ?? join5(packageDir, "commands");
|
|
600
|
+
const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
|
|
601
|
+
const cmdFiles = fg3.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
|
|
580
602
|
return {
|
|
581
603
|
skills: skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8"))),
|
|
582
604
|
cmds: cmdFiles.map((f) => parseCmd(f, readFileSync4(f, "utf8")))
|
|
583
605
|
};
|
|
584
606
|
}
|
|
585
607
|
function loadProjectSkills(targetDir) {
|
|
586
|
-
const skillsDir =
|
|
587
|
-
if (!
|
|
588
|
-
const skillFiles =
|
|
608
|
+
const skillsDir = join5(targetDir, "docs", "skills");
|
|
609
|
+
if (!existsSync4(skillsDir)) return [];
|
|
610
|
+
const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
|
|
589
611
|
return skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8")));
|
|
590
612
|
}
|
|
591
613
|
function loadOverrides(worktreeDir) {
|
|
592
|
-
const overridesDir =
|
|
593
|
-
if (!
|
|
614
|
+
const overridesDir = join5(worktreeDir, ".harness-overrides");
|
|
615
|
+
if (!existsSync4(overridesDir)) return void 0;
|
|
594
616
|
const added = loadHarness(overridesDir, {
|
|
595
|
-
skillsDir:
|
|
596
|
-
commandsDir:
|
|
617
|
+
skillsDir: join5(overridesDir, "skills"),
|
|
618
|
+
commandsDir: join5(overridesDir, "commands")
|
|
597
619
|
});
|
|
598
|
-
const disablePath =
|
|
620
|
+
const disablePath = join5(overridesDir, "disable.yaml");
|
|
599
621
|
let disable = [];
|
|
600
|
-
if (
|
|
622
|
+
if (existsSync4(disablePath)) {
|
|
601
623
|
try {
|
|
602
624
|
const parsed = DisableYamlSchema.safeParse(parseYAML(readFileSync4(disablePath, "utf8")));
|
|
603
625
|
if (parsed.success && parsed.data.disable) {
|
|
@@ -609,6 +631,214 @@ function loadOverrides(worktreeDir) {
|
|
|
609
631
|
return { add: added, disable };
|
|
610
632
|
}
|
|
611
633
|
|
|
634
|
+
// src/parser/intent.ts
|
|
635
|
+
import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync, statSync as statSync3 } from "fs";
|
|
636
|
+
import { basename as basename2, join as join6 } from "path";
|
|
637
|
+
import matter3 from "gray-matter";
|
|
638
|
+
var INTENTS_DIR = "docs/intents";
|
|
639
|
+
var INTENTS_INDEX_PATH = `${INTENTS_DIR}/README.md`;
|
|
640
|
+
var NODE_FIELDS = [
|
|
641
|
+
"status",
|
|
642
|
+
"spec",
|
|
643
|
+
"anchors",
|
|
644
|
+
"acceptance",
|
|
645
|
+
"requires",
|
|
646
|
+
"creates"
|
|
647
|
+
];
|
|
648
|
+
var TERMINAL_FIELDS = [
|
|
649
|
+
"anchors",
|
|
650
|
+
"acceptance",
|
|
651
|
+
"requires",
|
|
652
|
+
"creates"
|
|
653
|
+
];
|
|
654
|
+
var MASKED_LINE = "\0";
|
|
655
|
+
var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
|
|
656
|
+
var HEADING_RE = /^(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
|
|
657
|
+
var FIELD_RE = /^([a-z][a-z-]*):\s*(.*)$/;
|
|
658
|
+
var LIST_ITEM_RE = /^\s*-\s+(.*)$/;
|
|
659
|
+
function maskFencedCode(lines) {
|
|
660
|
+
let fence;
|
|
661
|
+
return lines.map((line) => {
|
|
662
|
+
const m = FENCE_RE.exec(line);
|
|
663
|
+
if (fence !== void 0) {
|
|
664
|
+
if (m?.[1] && m[1][0] === fence[0] && m[1].length >= fence.length) fence = void 0;
|
|
665
|
+
return MASKED_LINE;
|
|
666
|
+
}
|
|
667
|
+
if (m?.[1]) {
|
|
668
|
+
fence = m[1];
|
|
669
|
+
return MASKED_LINE;
|
|
670
|
+
}
|
|
671
|
+
return line;
|
|
672
|
+
});
|
|
673
|
+
}
|
|
674
|
+
function parseHeading(line) {
|
|
675
|
+
const m = HEADING_RE.exec(line);
|
|
676
|
+
if (!m?.[1] || !m[2]) return void 0;
|
|
677
|
+
return { depth: m[1].length, title: m[2] };
|
|
678
|
+
}
|
|
679
|
+
function splitList(value) {
|
|
680
|
+
return value.split(",").map((v) => v.trim()).filter(Boolean);
|
|
681
|
+
}
|
|
682
|
+
function bodyStart(lines) {
|
|
683
|
+
if (lines[0]?.trim() !== "---") return 0;
|
|
684
|
+
for (let i = 1; i < lines.length; i++) {
|
|
685
|
+
const l = lines[i]?.trim();
|
|
686
|
+
if (l === "---" || l === "...") return i + 1;
|
|
687
|
+
}
|
|
688
|
+
return lines.length;
|
|
689
|
+
}
|
|
690
|
+
function parseFrontmatter2(text, errors) {
|
|
691
|
+
let data;
|
|
692
|
+
try {
|
|
693
|
+
data = matter3(text).data;
|
|
694
|
+
} catch (error) {
|
|
695
|
+
const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
|
|
696
|
+
errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
|
|
697
|
+
return void 0;
|
|
698
|
+
}
|
|
699
|
+
const result = Schemas.Intent.safeParse(data);
|
|
700
|
+
if (result.success) return result.data;
|
|
701
|
+
for (const issue of result.error.issues) {
|
|
702
|
+
const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
|
|
703
|
+
errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });
|
|
704
|
+
}
|
|
705
|
+
return void 0;
|
|
706
|
+
}
|
|
707
|
+
function newNode(title, level, line) {
|
|
708
|
+
return {
|
|
709
|
+
title,
|
|
710
|
+
level,
|
|
711
|
+
line,
|
|
712
|
+
isTerminal: true,
|
|
713
|
+
fieldLines: {},
|
|
714
|
+
anchors: [],
|
|
715
|
+
acceptance: [],
|
|
716
|
+
requires: [],
|
|
717
|
+
creates: [],
|
|
718
|
+
unknownFields: []
|
|
719
|
+
};
|
|
720
|
+
}
|
|
721
|
+
function parseFields(node, lines, from, to, errors) {
|
|
722
|
+
let lastKey;
|
|
723
|
+
for (let i = from; i < to; i++) {
|
|
724
|
+
const line = lines[i] ?? "";
|
|
725
|
+
if (line.trim() === "") continue;
|
|
726
|
+
const lineNo = i + 1;
|
|
727
|
+
const field = FIELD_RE.exec(line.trimEnd());
|
|
728
|
+
if (field?.[1] !== void 0) {
|
|
729
|
+
const key = field[1];
|
|
730
|
+
const value = (field[2] ?? "").trim();
|
|
731
|
+
lastKey = key;
|
|
732
|
+
if (!NODE_FIELDS.includes(key)) {
|
|
733
|
+
node.unknownFields.push({ key, line: lineNo });
|
|
734
|
+
continue;
|
|
735
|
+
}
|
|
736
|
+
const known = key;
|
|
737
|
+
node.fieldLines[known] = lineNo;
|
|
738
|
+
if (known === "status") {
|
|
739
|
+
if (INTENT_STATUSES.includes(value)) {
|
|
740
|
+
node.status = value;
|
|
741
|
+
} else {
|
|
742
|
+
errors.push({
|
|
743
|
+
line: lineNo,
|
|
744
|
+
message: `invalid status \`${value}\` (expected ${INTENT_STATUSES.join(" | ")})`
|
|
745
|
+
});
|
|
746
|
+
}
|
|
747
|
+
} else if (known === "spec") {
|
|
748
|
+
node.spec = value;
|
|
749
|
+
} else if (known === "acceptance") {
|
|
750
|
+
if (value) node.acceptance.push(value);
|
|
751
|
+
} else {
|
|
752
|
+
node[known] = splitList(value);
|
|
753
|
+
}
|
|
754
|
+
continue;
|
|
755
|
+
}
|
|
756
|
+
const item = LIST_ITEM_RE.exec(line);
|
|
757
|
+
if (lastKey === "acceptance" && item) {
|
|
758
|
+
const text = (item[1] ?? "").trim();
|
|
759
|
+
if (text) node.acceptance.push(text);
|
|
760
|
+
continue;
|
|
761
|
+
}
|
|
762
|
+
return;
|
|
763
|
+
}
|
|
764
|
+
}
|
|
765
|
+
function parseIntentFile(relPath, text) {
|
|
766
|
+
const errors = [];
|
|
767
|
+
const meta = parseFrontmatter2(text, errors);
|
|
768
|
+
const lines = maskFencedCode(text.split(/\r?\n/));
|
|
769
|
+
const start = bodyStart(lines);
|
|
770
|
+
const headings = [];
|
|
771
|
+
for (let i = start; i < lines.length; i++) {
|
|
772
|
+
const h = parseHeading(lines[i] ?? "");
|
|
773
|
+
if (h) headings.push({ index: i, ...h });
|
|
774
|
+
}
|
|
775
|
+
const h1 = headings.find((h) => h.depth === 1);
|
|
776
|
+
let statement;
|
|
777
|
+
if (h1) {
|
|
778
|
+
const paragraph = [];
|
|
779
|
+
for (let i = h1.index + 1; i < lines.length; i++) {
|
|
780
|
+
const line = lines[i] ?? "";
|
|
781
|
+
if (line.trim() === "") {
|
|
782
|
+
if (paragraph.length) break;
|
|
783
|
+
continue;
|
|
784
|
+
}
|
|
785
|
+
if (line === MASKED_LINE || parseHeading(line)) break;
|
|
786
|
+
paragraph.push(line.trim());
|
|
787
|
+
}
|
|
788
|
+
if (paragraph.length) statement = paragraph.join(" ");
|
|
789
|
+
}
|
|
790
|
+
const nodes = [];
|
|
791
|
+
const stack = [];
|
|
792
|
+
for (const [k, h] of headings.entries()) {
|
|
793
|
+
if (h.depth < 2) continue;
|
|
794
|
+
const node = newNode(h.title, h.depth - 1, h.index + 1);
|
|
795
|
+
while (stack.length) {
|
|
796
|
+
const top = nodes[stack[stack.length - 1]];
|
|
797
|
+
if (top && top.level < node.level) break;
|
|
798
|
+
stack.pop();
|
|
799
|
+
}
|
|
800
|
+
const parentIndex = stack[stack.length - 1];
|
|
801
|
+
if (parentIndex !== void 0) {
|
|
802
|
+
node.parent = parentIndex;
|
|
803
|
+
const parent = nodes[parentIndex];
|
|
804
|
+
if (parent) parent.isTerminal = false;
|
|
805
|
+
}
|
|
806
|
+
const next = headings[k + 1];
|
|
807
|
+
parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
|
|
808
|
+
const inherited = parentIndex !== void 0 ? nodes[parentIndex]?.effectiveStatus : meta?.status;
|
|
809
|
+
node.effectiveStatus = node.status ?? inherited;
|
|
810
|
+
stack.push(nodes.length);
|
|
811
|
+
nodes.push(node);
|
|
812
|
+
}
|
|
813
|
+
const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
|
|
814
|
+
return { ...meta ? { meta } : {}, title, ...statement ? { statement } : {}, nodes, errors };
|
|
815
|
+
}
|
|
816
|
+
function listIntentFiles(targetDir) {
|
|
817
|
+
const dir = join6(targetDir, INTENTS_DIR);
|
|
818
|
+
if (!existsSync5(dir) || !statSync3(dir).isDirectory()) return [];
|
|
819
|
+
return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync3(join6(dir, f)).isFile()).sort();
|
|
820
|
+
}
|
|
821
|
+
function readIntentFiles(targetDir) {
|
|
822
|
+
return listIntentFiles(targetDir).map((file) => {
|
|
823
|
+
const path = `${INTENTS_DIR}/${file}`;
|
|
824
|
+
const text = readFileSync5(join6(targetDir, path), "utf8");
|
|
825
|
+
return { path, file, ...parseIntentFile(path, text) };
|
|
826
|
+
});
|
|
827
|
+
}
|
|
828
|
+
function loadIntentFiles(targetDir) {
|
|
829
|
+
const intentFiles = readIntentFiles(targetDir);
|
|
830
|
+
const problems = intentFiles.flatMap(
|
|
831
|
+
(j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
|
|
832
|
+
);
|
|
833
|
+
if (problems.length) {
|
|
834
|
+
throw new Error(
|
|
835
|
+
`invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
|
|
836
|
+
${problems.join("\n")}`
|
|
837
|
+
);
|
|
838
|
+
}
|
|
839
|
+
return intentFiles;
|
|
840
|
+
}
|
|
841
|
+
|
|
612
842
|
// src/renderers/common.ts
|
|
613
843
|
import { stringify as yamlStringify } from "yaml";
|
|
614
844
|
function checkSkillCapabilities(skill, engine) {
|
|
@@ -656,22 +886,26 @@ function frontmatterDataForCmd(cmd) {
|
|
|
656
886
|
description: cmd.meta.description
|
|
657
887
|
};
|
|
658
888
|
if (cmd.meta.args && cmd.meta.args.length > 0) {
|
|
659
|
-
data.args = cmd.meta.args.map((a) => {
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
}
|
|
663
|
-
|
|
664
|
-
|
|
889
|
+
data.args = cmd.meta.args.map((a) => ({
|
|
890
|
+
name: a.name,
|
|
891
|
+
type: a.type,
|
|
892
|
+
...a.type === "enum" ? { values: a.values } : {},
|
|
893
|
+
...a.default !== void 0 ? { default: a.default } : {},
|
|
894
|
+
...a.required === false ? { required: false } : {}
|
|
895
|
+
}));
|
|
665
896
|
}
|
|
666
897
|
return data;
|
|
667
898
|
}
|
|
668
899
|
function buildUmbrellaBody(extras) {
|
|
669
|
-
const
|
|
670
|
-
|
|
671
|
-
|
|
900
|
+
const triggersBySkill = /* @__PURE__ */ new Map();
|
|
901
|
+
for (const c of extras.availableCommands) {
|
|
902
|
+
const triggers = triggersBySkill.get(c.meta.invokes_skill) ?? [];
|
|
903
|
+
triggers.push(c.meta.trigger);
|
|
904
|
+
triggersBySkill.set(c.meta.invokes_skill, triggers);
|
|
905
|
+
}
|
|
672
906
|
const skillLines = extras.availableSkills.map((s) => {
|
|
673
|
-
const
|
|
674
|
-
const label =
|
|
907
|
+
const triggers = triggersBySkill.get(s.meta.id) ?? [];
|
|
908
|
+
const label = triggers.length > 0 ? `\`${s.meta.id}\` (${triggers.map((t) => `\`${t}\``).join(", ")})` : `\`${s.meta.id}\``;
|
|
675
909
|
return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
|
|
676
910
|
});
|
|
677
911
|
const sections = [
|
|
@@ -691,11 +925,17 @@ function buildUmbrellaBody(extras) {
|
|
|
691
925
|
...extras.hasQualityDoc ? [
|
|
692
926
|
"- `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."
|
|
693
927
|
] : [],
|
|
928
|
+
...extras.hasIntents ? [
|
|
929
|
+
"- `docs/intents/<intent>.md` \u2014 user intents, one tree per level-1 intent, anchored to the code. `docs/intents/README.md` is the generated index."
|
|
930
|
+
] : [],
|
|
694
931
|
"",
|
|
695
932
|
"## Doc-first",
|
|
696
933
|
"",
|
|
697
934
|
"The order is: **understand the docs \u2192 fill the gaps \u2192 code \u2192 update the docs \u2192 commit**. If the docs are silent or stale on something you change, fill the gap upfront with the doc-skill writers \u2014 not downstream, not after the fact.",
|
|
698
935
|
"",
|
|
936
|
+
...extras.hasIntents ? [
|
|
937
|
+
"- Visible change of behavior \u2192 a `proposed` intent first (`/intent <verb + object>`), never the code first."
|
|
938
|
+
] : [],
|
|
699
939
|
"- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
|
|
700
940
|
"- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
|
|
701
941
|
"- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
|
|
@@ -824,6 +1064,23 @@ function getRenderer(engine) {
|
|
|
824
1064
|
return RENDERERS[engine];
|
|
825
1065
|
}
|
|
826
1066
|
|
|
1067
|
+
// src/renderers/intents-index.ts
|
|
1068
|
+
var INTRO = "User intents of this project, anchored to the code. Generated by `@vaubaan/harness` from `docs/intents/*.md`: edit the intents, not this file, then run `npx @vaubaan/harness update .`.";
|
|
1069
|
+
function buildIntentsIndex(intentFiles) {
|
|
1070
|
+
const lines = ["# Intents", "", INTRO, ""];
|
|
1071
|
+
const sorted = [...intentFiles].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
|
|
1072
|
+
for (const intentFile of sorted) {
|
|
1073
|
+
const status = intentFile.meta?.status ?? "proposed";
|
|
1074
|
+
const actors = intentFile.meta?.actors.join(", ") ?? "";
|
|
1075
|
+
lines.push(`- [${intentFile.title}](./${intentFile.file}) \u2014 ${status} \xB7 ${actors}`);
|
|
1076
|
+
for (const node of intentFile.nodes) {
|
|
1077
|
+
lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
|
|
1078
|
+
}
|
|
1079
|
+
}
|
|
1080
|
+
return `${lines.join("\n")}
|
|
1081
|
+
`;
|
|
1082
|
+
}
|
|
1083
|
+
|
|
827
1084
|
// src/render.ts
|
|
828
1085
|
var RenderError = class extends Error {
|
|
829
1086
|
constructor(message) {
|
|
@@ -893,12 +1150,16 @@ function render(input) {
|
|
|
893
1150
|
availableSkills: Array.from(exposedSkills.values()),
|
|
894
1151
|
availableCommands: Array.from(exposedCmds.values()),
|
|
895
1152
|
hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
|
|
896
|
-
hasQualityDoc: input.hasQualityDoc === true
|
|
1153
|
+
hasQualityDoc: input.hasQualityDoc === true,
|
|
1154
|
+
hasIntents: (input.intentFiles?.length ?? 0) > 0
|
|
897
1155
|
});
|
|
898
1156
|
files.push({ path: "AGENTS.md", content: umbrellaContent });
|
|
899
1157
|
if (engines.includes("claude-code")) {
|
|
900
1158
|
files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
|
|
901
1159
|
}
|
|
1160
|
+
if (input.intentFiles && input.intentFiles.length > 0) {
|
|
1161
|
+
files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });
|
|
1162
|
+
}
|
|
902
1163
|
return { files, warnings };
|
|
903
1164
|
}
|
|
904
1165
|
|
|
@@ -930,7 +1191,8 @@ function planInit(args) {
|
|
|
930
1191
|
const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
|
|
931
1192
|
const projectSkills = loadProjectSkills(args.targetDir);
|
|
932
1193
|
const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
|
|
933
|
-
const
|
|
1194
|
+
const intentFiles = loadIntentFiles(args.targetDir);
|
|
1195
|
+
const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, intentFiles });
|
|
934
1196
|
return { engines, output };
|
|
935
1197
|
}
|
|
936
1198
|
|
|
@@ -977,7 +1239,7 @@ var generatedFresh = {
|
|
|
977
1239
|
const full = join8(repoRoot, file.path);
|
|
978
1240
|
if (!existsSync7(full)) {
|
|
979
1241
|
issues.push(issue(file.path, `generated file is missing; ${FIX}`));
|
|
980
|
-
} else if (
|
|
1242
|
+
} else if (readFileSync6(full, "utf8") !== file.content) {
|
|
981
1243
|
issues.push(
|
|
982
1244
|
issue(
|
|
983
1245
|
file.path,
|
|
@@ -1008,7 +1270,8 @@ var FORBIDDEN_GITIGNORE_ENTRIES = [
|
|
|
1008
1270
|
".codex/",
|
|
1009
1271
|
".agents/",
|
|
1010
1272
|
".opencode/",
|
|
1011
|
-
".harness-manifest.json"
|
|
1273
|
+
".harness-manifest.json",
|
|
1274
|
+
"docs/intents/README.md"
|
|
1012
1275
|
];
|
|
1013
1276
|
function gitignoreEntries(text) {
|
|
1014
1277
|
const entries = /* @__PURE__ */ new Set();
|
|
@@ -1067,9 +1330,211 @@ var gitignoreHarness = {
|
|
|
1067
1330
|
}
|
|
1068
1331
|
};
|
|
1069
1332
|
|
|
1333
|
+
// src/linters/intent-anchors.ts
|
|
1334
|
+
var intentAnchors = {
|
|
1335
|
+
id: "lint:intent-anchors",
|
|
1336
|
+
pillars: ["intents"],
|
|
1337
|
+
defaultSeverity: "error",
|
|
1338
|
+
suggestedSkills: ["/intent"],
|
|
1339
|
+
run(repoRoot) {
|
|
1340
|
+
const issues = [];
|
|
1341
|
+
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
1342
|
+
for (const node of intentFile.nodes) {
|
|
1343
|
+
if (node.effectiveStatus === "deprecated") continue;
|
|
1344
|
+
for (const anchor of node.anchors) {
|
|
1345
|
+
if (trackedPathExists(repoRoot, anchor)) continue;
|
|
1346
|
+
issues.push({
|
|
1347
|
+
linter: this.id,
|
|
1348
|
+
severity: "error",
|
|
1349
|
+
file: intentFile.path,
|
|
1350
|
+
line: node.line,
|
|
1351
|
+
message: `"${node.title}": anchor matches no file: ${anchor}`
|
|
1352
|
+
});
|
|
1353
|
+
}
|
|
1354
|
+
}
|
|
1355
|
+
}
|
|
1356
|
+
return issues;
|
|
1357
|
+
}
|
|
1358
|
+
};
|
|
1359
|
+
|
|
1360
|
+
// src/linters/intent-graph.ts
|
|
1361
|
+
var intentGraph = {
|
|
1362
|
+
id: "lint:intent-graph",
|
|
1363
|
+
pillars: ["intents"],
|
|
1364
|
+
defaultSeverity: "warning",
|
|
1365
|
+
suggestedSkills: ["/intent"],
|
|
1366
|
+
run(repoRoot) {
|
|
1367
|
+
const intentFiles = readIntentFiles(repoRoot);
|
|
1368
|
+
const terminals = intentFiles.flatMap(
|
|
1369
|
+
(intentFile) => intentFile.nodes.filter((node) => node.isTerminal).map((node) => ({ intentFile, node }))
|
|
1370
|
+
);
|
|
1371
|
+
const created = new Set(terminals.flatMap(({ node }) => node.creates));
|
|
1372
|
+
const issues = [];
|
|
1373
|
+
for (const { intentFile, node } of terminals) {
|
|
1374
|
+
for (const entity of node.requires) {
|
|
1375
|
+
if (created.has(entity)) continue;
|
|
1376
|
+
issues.push({
|
|
1377
|
+
linter: this.id,
|
|
1378
|
+
severity: "warning",
|
|
1379
|
+
file: intentFile.path,
|
|
1380
|
+
line: node.line,
|
|
1381
|
+
message: `"${node.title}": entity \`${entity}\` is required here but no terminal intent creates it`
|
|
1382
|
+
});
|
|
1383
|
+
}
|
|
1384
|
+
}
|
|
1385
|
+
return issues;
|
|
1386
|
+
}
|
|
1387
|
+
};
|
|
1388
|
+
|
|
1389
|
+
// src/linters/intent-util.ts
|
|
1390
|
+
import { posix } from "path";
|
|
1391
|
+
function intentFileSpecs(meta) {
|
|
1392
|
+
if (!meta) return [];
|
|
1393
|
+
return typeof meta.spec === "string" ? [meta.spec] : [...meta.spec];
|
|
1394
|
+
}
|
|
1395
|
+
function resolveSpecPath(filePath, spec) {
|
|
1396
|
+
const withoutFragment = spec.split("#")[0] ?? "";
|
|
1397
|
+
return posix.normalize(posix.join(posix.dirname(filePath), withoutFragment));
|
|
1398
|
+
}
|
|
1399
|
+
|
|
1400
|
+
// src/linters/intent-schema.ts
|
|
1401
|
+
var DERIVABLE_FIELDS = /* @__PURE__ */ new Set(["uses", "guards"]);
|
|
1402
|
+
var intentSchema = {
|
|
1403
|
+
id: "lint:intent-schema",
|
|
1404
|
+
pillars: ["intents"],
|
|
1405
|
+
defaultSeverity: "error",
|
|
1406
|
+
suggestedSkills: ["/intent"],
|
|
1407
|
+
run(repoRoot) {
|
|
1408
|
+
const issues = [];
|
|
1409
|
+
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
1410
|
+
const report = (message, line) => {
|
|
1411
|
+
issues.push({
|
|
1412
|
+
linter: this.id,
|
|
1413
|
+
severity: "error",
|
|
1414
|
+
file: intentFile.path,
|
|
1415
|
+
...line !== void 0 ? { line } : {},
|
|
1416
|
+
message
|
|
1417
|
+
});
|
|
1418
|
+
};
|
|
1419
|
+
for (const error of intentFile.errors) report(error.message, error.line);
|
|
1420
|
+
for (const spec of intentFileSpecs(intentFile.meta)) {
|
|
1421
|
+
if (!fileExists(repoRoot, resolveSpecPath(intentFile.path, spec))) {
|
|
1422
|
+
report(`frontmatter \`spec\` does not resolve: ${spec}`, 1);
|
|
1423
|
+
}
|
|
1424
|
+
}
|
|
1425
|
+
for (const node of intentFile.nodes) {
|
|
1426
|
+
const at = (message) => report(`"${node.title}": ${message}`, node.line);
|
|
1427
|
+
for (const { key, line } of node.unknownFields) {
|
|
1428
|
+
report(
|
|
1429
|
+
DERIVABLE_FIELDS.has(key) ? `"${node.title}": \`${key}:\` is derivable, never declared` : `"${node.title}": unknown field \`${key}:\``,
|
|
1430
|
+
line
|
|
1431
|
+
);
|
|
1432
|
+
}
|
|
1433
|
+
if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(intentFile.path, node.spec))) {
|
|
1434
|
+
report(`"${node.title}": \`spec:\` does not resolve: ${node.spec}`, node.fieldLines.spec);
|
|
1435
|
+
}
|
|
1436
|
+
if (!node.isTerminal) {
|
|
1437
|
+
for (const field of TERMINAL_FIELDS) {
|
|
1438
|
+
const line = node.fieldLines[field];
|
|
1439
|
+
if (line !== void 0) {
|
|
1440
|
+
report(
|
|
1441
|
+
`"${node.title}": \`${field}:\` is a field of a terminal intent, this node has sub-intents`,
|
|
1442
|
+
line
|
|
1443
|
+
);
|
|
1444
|
+
}
|
|
1445
|
+
}
|
|
1446
|
+
continue;
|
|
1447
|
+
}
|
|
1448
|
+
if (Object.keys(node.fieldLines).length === 0) {
|
|
1449
|
+
at("a terminal intent carries at least one field");
|
|
1450
|
+
continue;
|
|
1451
|
+
}
|
|
1452
|
+
if (node.effectiveStatus === "implemented" && node.anchors.length === 0) {
|
|
1453
|
+
at("an `implemented` intent needs `anchors:`");
|
|
1454
|
+
}
|
|
1455
|
+
if (node.effectiveStatus === "proposed" && node.acceptance.length === 0) {
|
|
1456
|
+
at("a `proposed` intent needs `acceptance:` with at least one `- ` item");
|
|
1457
|
+
}
|
|
1458
|
+
}
|
|
1459
|
+
}
|
|
1460
|
+
return issues;
|
|
1461
|
+
}
|
|
1462
|
+
};
|
|
1463
|
+
|
|
1464
|
+
// src/linters/intent-vocabulary.ts
|
|
1465
|
+
var VOCABULARY_HEADING = /^#+\s*(\d+(\.\d+)*\.?\s*)?(Vocabulary|Vocabulaire)\b/i;
|
|
1466
|
+
var TERM = /^\s*[-*]\s+\*\*([^*]+)\*\*/;
|
|
1467
|
+
function entitySlug(term) {
|
|
1468
|
+
return term.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
|
|
1469
|
+
}
|
|
1470
|
+
function vocabularyOf(specText) {
|
|
1471
|
+
const lines = maskFencedCode(specText.split(/\r?\n/));
|
|
1472
|
+
let depth;
|
|
1473
|
+
let terms;
|
|
1474
|
+
for (const line of lines) {
|
|
1475
|
+
const heading = parseHeading(line);
|
|
1476
|
+
if (depth !== void 0) {
|
|
1477
|
+
if (heading && heading.depth <= depth) break;
|
|
1478
|
+
const term = TERM.exec(line)?.[1];
|
|
1479
|
+
if (term) terms?.add(entitySlug(term));
|
|
1480
|
+
continue;
|
|
1481
|
+
}
|
|
1482
|
+
if (heading && VOCABULARY_HEADING.test(line)) {
|
|
1483
|
+
depth = heading.depth;
|
|
1484
|
+
terms = /* @__PURE__ */ new Set();
|
|
1485
|
+
}
|
|
1486
|
+
}
|
|
1487
|
+
return terms;
|
|
1488
|
+
}
|
|
1489
|
+
var intentVocabulary = {
|
|
1490
|
+
id: "lint:intent-vocabulary",
|
|
1491
|
+
pillars: ["intents"],
|
|
1492
|
+
defaultSeverity: "error",
|
|
1493
|
+
suggestedSkills: ["/spec"],
|
|
1494
|
+
run(repoRoot) {
|
|
1495
|
+
const issues = [];
|
|
1496
|
+
for (const intentFile of readIntentFiles(repoRoot)) {
|
|
1497
|
+
const used = intentFile.nodes.flatMap(
|
|
1498
|
+
(node) => [...node.requires, ...node.creates].map((entity) => ({ entity, node }))
|
|
1499
|
+
);
|
|
1500
|
+
if (used.length === 0) continue;
|
|
1501
|
+
const specs = intentFileSpecs(intentFile.meta).map((spec) => resolveSpecPath(intentFile.path, spec)).filter((path) => fileExists(repoRoot, path));
|
|
1502
|
+
if (specs.length === 0) continue;
|
|
1503
|
+
const entities = /* @__PURE__ */ new Set();
|
|
1504
|
+
let hasVocabulary = false;
|
|
1505
|
+
for (const spec of specs) {
|
|
1506
|
+
const terms = vocabularyOf(readText(repoRoot, spec));
|
|
1507
|
+
if (!terms) continue;
|
|
1508
|
+
hasVocabulary = true;
|
|
1509
|
+
for (const term of terms) entities.add(term);
|
|
1510
|
+
}
|
|
1511
|
+
if (!hasVocabulary) {
|
|
1512
|
+
issues.push({
|
|
1513
|
+
linter: this.id,
|
|
1514
|
+
severity: "warning",
|
|
1515
|
+
file: intentFile.path,
|
|
1516
|
+
message: `no Vocabulary section in ${specs.join(", ")}; entities not checked`
|
|
1517
|
+
});
|
|
1518
|
+
continue;
|
|
1519
|
+
}
|
|
1520
|
+
for (const { entity, node } of used) {
|
|
1521
|
+
if (entities.has(entity)) continue;
|
|
1522
|
+
issues.push({
|
|
1523
|
+
linter: this.id,
|
|
1524
|
+
severity: "error",
|
|
1525
|
+
file: intentFile.path,
|
|
1526
|
+
line: node.line,
|
|
1527
|
+
message: `"${node.title}": entity \`${entity}\` is not a Vocabulary term of ${specs.join(", ")}`
|
|
1528
|
+
});
|
|
1529
|
+
}
|
|
1530
|
+
}
|
|
1531
|
+
return issues;
|
|
1532
|
+
}
|
|
1533
|
+
};
|
|
1534
|
+
|
|
1070
1535
|
// src/linters/orphan-decisions.ts
|
|
1071
|
-
import { basename as
|
|
1072
|
-
import
|
|
1536
|
+
import { basename as basename3 } from "path";
|
|
1537
|
+
import fg4 from "fast-glob";
|
|
1073
1538
|
var orphanDecisions = {
|
|
1074
1539
|
id: "lint:orphan-decisions",
|
|
1075
1540
|
pillars: ["decisions"],
|
|
@@ -1080,7 +1545,7 @@ var orphanDecisions = {
|
|
|
1080
1545
|
const issues = [];
|
|
1081
1546
|
const adrs = listMarkdown(repoRoot, "docs/decisions");
|
|
1082
1547
|
if (adrs.length === 0) return issues;
|
|
1083
|
-
const otherDocs =
|
|
1548
|
+
const otherDocs = fg4.sync("**/*.md", {
|
|
1084
1549
|
cwd: repoRoot,
|
|
1085
1550
|
absolute: false,
|
|
1086
1551
|
ignore: [
|
|
@@ -1097,7 +1562,7 @@ var orphanDecisions = {
|
|
|
1097
1562
|
});
|
|
1098
1563
|
const referenceCorpus = otherDocs.map((f) => readText(repoRoot, f)).join("\n");
|
|
1099
1564
|
for (const adr of adrs) {
|
|
1100
|
-
const filename =
|
|
1565
|
+
const filename = basename3(adr);
|
|
1101
1566
|
const stem = filename.replace(/\.md$/, "");
|
|
1102
1567
|
const referenced = referenceCorpus.includes(filename) || referenceCorpus.includes(stem);
|
|
1103
1568
|
if (!referenced) {
|
|
@@ -1273,33 +1738,42 @@ var specTechAgnostic = {
|
|
|
1273
1738
|
};
|
|
1274
1739
|
|
|
1275
1740
|
// src/linters/tracks-drift.ts
|
|
1276
|
-
import
|
|
1741
|
+
import fg5 from "fast-glob";
|
|
1277
1742
|
var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
|
|
1743
|
+
var INTENTS_DIR2 = "docs/intents";
|
|
1278
1744
|
var DEFAULT_DRIFT_THRESHOLD = 10;
|
|
1279
1745
|
function expandGlob(repoRoot, pattern) {
|
|
1280
1746
|
if (pattern.includes("*")) {
|
|
1281
|
-
return
|
|
1747
|
+
return fg5.sync(pattern, { cwd: repoRoot, absolute: false });
|
|
1282
1748
|
}
|
|
1283
1749
|
return [pattern];
|
|
1284
1750
|
}
|
|
1751
|
+
function trackedPaths(dir, file, text, data) {
|
|
1752
|
+
if (dir === INTENTS_DIR2) {
|
|
1753
|
+
const anchors = parseIntentFile(file, text).nodes.flatMap((node) => node.anchors);
|
|
1754
|
+
return anchors.length > 0 ? [...new Set(anchors)] : void 0;
|
|
1755
|
+
}
|
|
1756
|
+
return Array.isArray(data.tracks) ? data.tracks : void 0;
|
|
1757
|
+
}
|
|
1285
1758
|
var tracksDrift = {
|
|
1286
1759
|
id: "lint:tracks-drift",
|
|
1287
|
-
pillars: ["handbook", "tests", "workflow"],
|
|
1760
|
+
pillars: ["handbook", "tests", "workflow", "intents"],
|
|
1288
1761
|
defaultSeverity: "warning",
|
|
1289
1762
|
suggestedSkills: ["/drift", "/handbook"],
|
|
1290
1763
|
run(repoRoot) {
|
|
1291
1764
|
const issues = [];
|
|
1292
|
-
for (const dir of TRACKED_DIRS2) {
|
|
1765
|
+
for (const dir of [...TRACKED_DIRS2, INTENTS_DIR2]) {
|
|
1293
1766
|
const files = listMarkdown(repoRoot, dir);
|
|
1294
1767
|
for (const f of files) {
|
|
1295
1768
|
const text = readText(repoRoot, f);
|
|
1296
1769
|
const { data } = parseFrontmatter(text);
|
|
1297
|
-
|
|
1770
|
+
const tracks = trackedPaths(dir, f, text, data);
|
|
1771
|
+
if (!tracks) continue;
|
|
1298
1772
|
const docCommit = gitLastCommitForPath(repoRoot, f);
|
|
1299
1773
|
if (!docCommit) continue;
|
|
1300
1774
|
const threshold = typeof data.driftThreshold === "number" && data.driftThreshold > 0 ? data.driftThreshold : DEFAULT_DRIFT_THRESHOLD;
|
|
1301
1775
|
let driftCount = 0;
|
|
1302
|
-
for (const tracked of
|
|
1776
|
+
for (const tracked of tracks) {
|
|
1303
1777
|
if (typeof tracked !== "string") continue;
|
|
1304
1778
|
const targets = expandGlob(repoRoot, tracked);
|
|
1305
1779
|
for (const t of targets.length > 0 ? targets : [tracked]) {
|
|
@@ -1336,6 +1810,10 @@ var ALL_LINTERS = [
|
|
|
1336
1810
|
orphanDecisions,
|
|
1337
1811
|
gitignoreHarness,
|
|
1338
1812
|
qualitySchema,
|
|
1813
|
+
intentSchema,
|
|
1814
|
+
intentAnchors,
|
|
1815
|
+
intentVocabulary,
|
|
1816
|
+
intentGraph,
|
|
1339
1817
|
generatedFresh
|
|
1340
1818
|
];
|
|
1341
1819
|
function runLinters(repoRoot, opts = {}) {
|
|
@@ -1391,7 +1869,7 @@ function formatReportText(report) {
|
|
|
1391
1869
|
}
|
|
1392
1870
|
|
|
1393
1871
|
// src/cli/check.ts
|
|
1394
|
-
import { existsSync as existsSync8, readFileSync as
|
|
1872
|
+
import { existsSync as existsSync8, readFileSync as readFileSync7 } from "fs";
|
|
1395
1873
|
import { join as join9 } from "path";
|
|
1396
1874
|
var REQUIRED_DIRS2 = [
|
|
1397
1875
|
"docs/spec",
|
|
@@ -1414,7 +1892,7 @@ function checkCommand(repoRoot) {
|
|
|
1414
1892
|
if (!existsSync8(gitignorePath)) {
|
|
1415
1893
|
issues.push(".gitignore missing at repo root");
|
|
1416
1894
|
} else {
|
|
1417
|
-
const text =
|
|
1895
|
+
const text = readFileSync7(gitignorePath, "utf8");
|
|
1418
1896
|
for (const entry of missingGitignoreEntries(text)) {
|
|
1419
1897
|
issues.push(`.gitignore missing entry: ${entry}`);
|
|
1420
1898
|
}
|
|
@@ -1430,7 +1908,7 @@ import { existsSync as existsSync12, mkdirSync as mkdirSync2, rmSync, writeFileS
|
|
|
1430
1908
|
import { dirname as dirname7, join as join14, resolve as resolve8 } from "path";
|
|
1431
1909
|
|
|
1432
1910
|
// src/cli/uninstall.ts
|
|
1433
|
-
import { existsSync as existsSync9, readFileSync as
|
|
1911
|
+
import { existsSync as existsSync9, readFileSync as readFileSync8, readdirSync as readdirSync2, rmdirSync, unlinkSync } from "fs";
|
|
1434
1912
|
import { dirname as dirname4, join as join10, relative as relative2, resolve as resolve5 } from "path";
|
|
1435
1913
|
function uninstallCommand(args) {
|
|
1436
1914
|
const root = resolve5(args.targetDir);
|
|
@@ -1447,7 +1925,7 @@ function uninstallCommand(args) {
|
|
|
1447
1925
|
const modified = files.filter((file) => {
|
|
1448
1926
|
const hash = manifest.fileHashes?.[file];
|
|
1449
1927
|
const full = join10(root, file);
|
|
1450
|
-
return hash !== void 0 && existsSync9(full) && hashContent(
|
|
1928
|
+
return hash !== void 0 && existsSync9(full) && hashContent(readFileSync8(full)) !== hash;
|
|
1451
1929
|
});
|
|
1452
1930
|
const ownedFiles = files.filter((file) => !modified.includes(file));
|
|
1453
1931
|
const { filesRemoved, dirsPruned, missing } = removeRenderedFiles(root, ownedFiles);
|
|
@@ -1489,7 +1967,7 @@ function pruneEmptyDirs(root, leaves) {
|
|
|
1489
1967
|
const sorted = [...candidates].sort((a, b) => b.length - a.length);
|
|
1490
1968
|
for (const dir of sorted) {
|
|
1491
1969
|
if (!existsSync9(dir)) continue;
|
|
1492
|
-
if (
|
|
1970
|
+
if (readdirSync2(dir).length > 0) continue;
|
|
1493
1971
|
rmdirSync(dir);
|
|
1494
1972
|
pruned.push(relative2(root, dir));
|
|
1495
1973
|
}
|
|
@@ -1505,22 +1983,22 @@ import {
|
|
|
1505
1983
|
lstatSync as lstatSync2,
|
|
1506
1984
|
mkdirSync,
|
|
1507
1985
|
openSync,
|
|
1508
|
-
readFileSync as
|
|
1509
|
-
readdirSync as
|
|
1986
|
+
readFileSync as readFileSync9,
|
|
1987
|
+
readdirSync as readdirSync3,
|
|
1510
1988
|
realpathSync as realpathSync2,
|
|
1511
1989
|
rmdirSync as rmdirSync2,
|
|
1512
1990
|
unlinkSync as unlinkSync2,
|
|
1513
1991
|
writeFileSync as writeFileSync2
|
|
1514
1992
|
} from "fs";
|
|
1515
1993
|
import { homedir } from "os";
|
|
1516
|
-
import { basename as
|
|
1994
|
+
import { basename as basename4, dirname as dirname5, isAbsolute as isAbsolute3, join as join11, relative as relative3, resolve as resolve6, sep } from "path";
|
|
1517
1995
|
var MANIFEST_PATH = ".harness-manifest.json";
|
|
1518
1996
|
var PRIVATE_FILES = /* @__PURE__ */ new Set([MANIFEST_PATH]);
|
|
1519
1997
|
function canonicalRoot(root) {
|
|
1520
1998
|
let ancestor = resolve6(root);
|
|
1521
1999
|
const missing = [];
|
|
1522
2000
|
while (!lstatSync2(ancestor, { throwIfNoEntry: false })) {
|
|
1523
|
-
missing.unshift(
|
|
2001
|
+
missing.unshift(basename4(ancestor));
|
|
1524
2002
|
ancestor = dirname5(ancestor);
|
|
1525
2003
|
}
|
|
1526
2004
|
return join11(realpathSync2(ancestor), ...missing);
|
|
@@ -1580,7 +2058,7 @@ function saveSnapshot(root, paths, backup) {
|
|
|
1580
2058
|
entries.push({ path, exists: false });
|
|
1581
2059
|
continue;
|
|
1582
2060
|
}
|
|
1583
|
-
const content =
|
|
2061
|
+
const content = readFileSync9(full);
|
|
1584
2062
|
writeBackupFile(join11(backup, "files", path), content);
|
|
1585
2063
|
entries.push({
|
|
1586
2064
|
path,
|
|
@@ -1611,8 +2089,8 @@ function rollback(root, backup, entries, touched, createdDirectories) {
|
|
|
1611
2089
|
if (current) unlinkSync2(full);
|
|
1612
2090
|
continue;
|
|
1613
2091
|
}
|
|
1614
|
-
const original =
|
|
1615
|
-
if (!current || !
|
|
2092
|
+
const original = readFileSync9(join11(backup, "files", path));
|
|
2093
|
+
if (!current || !readFileSync9(full).equals(original)) {
|
|
1616
2094
|
if (current) unlinkSync2(full);
|
|
1617
2095
|
writeFileSync2(full, original, { mode: 384 });
|
|
1618
2096
|
}
|
|
@@ -1623,7 +2101,7 @@ function rollback(root, backup, entries, touched, createdDirectories) {
|
|
|
1623
2101
|
}
|
|
1624
2102
|
for (const directory of [...createdDirectories].reverse()) {
|
|
1625
2103
|
try {
|
|
1626
|
-
if (
|
|
2104
|
+
if (readdirSync3(directory).length === 0) rmdirSync2(directory);
|
|
1627
2105
|
} catch (error) {
|
|
1628
2106
|
errors.push(`${directory}: ${errorMessage(error)}`);
|
|
1629
2107
|
}
|
|
@@ -1678,12 +2156,12 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
|
|
|
1678
2156
|
}
|
|
1679
2157
|
|
|
1680
2158
|
// src/cli/update.ts
|
|
1681
|
-
import { existsSync as existsSync11, readFileSync as
|
|
2159
|
+
import { existsSync as existsSync11, readFileSync as readFileSync11, readdirSync as readdirSync4, statSync as statSync4 } from "fs";
|
|
1682
2160
|
import { dirname as dirname6, join as join13, resolve as resolve7 } from "path";
|
|
1683
2161
|
import { isDeepStrictEqual } from "util";
|
|
1684
2162
|
|
|
1685
2163
|
// src/cli/update-manifest.ts
|
|
1686
|
-
import { existsSync as existsSync10, readFileSync as
|
|
2164
|
+
import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
|
|
1687
2165
|
import { join as join12 } from "path";
|
|
1688
2166
|
import { z as z4 } from "zod";
|
|
1689
2167
|
var EngineSchema = z4.enum(ENGINES);
|
|
@@ -1699,7 +2177,7 @@ function readUpdateInstallation(root) {
|
|
|
1699
2177
|
if (!existsSync10(join12(root, MANIFEST_FILENAME))) {
|
|
1700
2178
|
throw new Error("no harness manifest found; use init for a new installation");
|
|
1701
2179
|
}
|
|
1702
|
-
const raw = JSON.parse(
|
|
2180
|
+
const raw = JSON.parse(readFileSync10(join12(root, MANIFEST_FILENAME), "utf8"));
|
|
1703
2181
|
const sourceVersion = String(raw?.version);
|
|
1704
2182
|
let manifest;
|
|
1705
2183
|
if (["1", "2", "3"].includes(sourceVersion)) {
|
|
@@ -1724,7 +2202,7 @@ function readUpdateInstallation(root) {
|
|
|
1724
2202
|
var LEGACY_HOOK_FILES = [".claude/settings.json", ".codex/hooks.json"];
|
|
1725
2203
|
var LEGACY_HOOK_MARKER = "@vaubaan/harness stop-hook";
|
|
1726
2204
|
function currentContent(root, path) {
|
|
1727
|
-
return existsSync11(join13(root, path)) ?
|
|
2205
|
+
return existsSync11(join13(root, path)) ? readFileSync11(join13(root, path), "utf8") : void 0;
|
|
1728
2206
|
}
|
|
1729
2207
|
function checkArtifactConflicts(root, previous, writes, removals) {
|
|
1730
2208
|
const desired = new Map(writes.map((file) => [file.path, file.content]));
|
|
@@ -1754,6 +2232,27 @@ function releaseLegacyPaths(previous, warnings) {
|
|
|
1754
2232
|
if (released.length === 0) return previous;
|
|
1755
2233
|
return { ...previous, files: previous.files.filter((path) => !released.includes(path)) };
|
|
1756
2234
|
}
|
|
2235
|
+
function carryMovedPaths(root, previous, warnings) {
|
|
2236
|
+
let files = previous.files;
|
|
2237
|
+
let fileHashes = previous.fileHashes;
|
|
2238
|
+
for (const [from, to] of MOVED_PATHS) {
|
|
2239
|
+
if (!files.includes(from) || existsSync11(join13(root, from))) continue;
|
|
2240
|
+
files = [...new Set(files.map((path) => path === from ? to : path))];
|
|
2241
|
+
const hash = fileHashes?.[from];
|
|
2242
|
+
if (fileHashes && hash !== void 0) {
|
|
2243
|
+
const { [from]: _moved, ...rest } = fileHashes;
|
|
2244
|
+
fileHashes = { ...rest, [to]: hash };
|
|
2245
|
+
}
|
|
2246
|
+
}
|
|
2247
|
+
const oldDir = join13(root, "docs/journeys");
|
|
2248
|
+
if (existsSync11(oldDir) && statSync4(oldDir).isDirectory() && readdirSync4(oldDir).length > 0) {
|
|
2249
|
+
warnings.push(
|
|
2250
|
+
"docs/journeys/ is now docs/intents/: run `git mv docs/journeys docs/intents`, then `npx @vaubaan/harness update .` again"
|
|
2251
|
+
);
|
|
2252
|
+
}
|
|
2253
|
+
if (files === previous.files) return previous;
|
|
2254
|
+
return { ...previous, files, ...fileHashes ? { fileHashes } : {} };
|
|
2255
|
+
}
|
|
1757
2256
|
function legacyHookWarnings(root) {
|
|
1758
2257
|
const warnings = [];
|
|
1759
2258
|
for (const path of LEGACY_HOOK_FILES) {
|
|
@@ -1770,7 +2269,7 @@ function planInstallation(args, settings) {
|
|
|
1770
2269
|
const root = resolve7(args.targetDir);
|
|
1771
2270
|
const { engines } = settings;
|
|
1772
2271
|
const warnings = [];
|
|
1773
|
-
const previous = releaseLegacyPaths(settings.previous, warnings);
|
|
2272
|
+
const previous = carryMovedPaths(root, releaseLegacyPaths(settings.previous, warnings), warnings);
|
|
1774
2273
|
const preserved = [
|
|
1775
2274
|
.../* @__PURE__ */ new Set([...previous.preservedFiles ?? [], ...args.preserveFiles ?? []])
|
|
1776
2275
|
].sort();
|
|
@@ -1786,7 +2285,7 @@ function planInstallation(args, settings) {
|
|
|
1786
2285
|
const disablePath = join13(overridesDir, ".harness-overrides", "disable.yaml");
|
|
1787
2286
|
if (existsSync11(disablePath)) {
|
|
1788
2287
|
try {
|
|
1789
|
-
DisableYamlSchema.parse(parseYAML(
|
|
2288
|
+
DisableYamlSchema.parse(parseYAML(readFileSync11(disablePath, "utf8")));
|
|
1790
2289
|
} catch {
|
|
1791
2290
|
throw new Error(`invalid override selection: ${disablePath}`);
|
|
1792
2291
|
}
|
|
@@ -2007,7 +2506,7 @@ program.command("check").description("Verify repo layout: doc pillars present an
|
|
|
2007
2506
|
});
|
|
2008
2507
|
program.command("lint").description("Run all mechanical linters and exit non-zero on errors").option(
|
|
2009
2508
|
"--pillar <pillar>",
|
|
2010
|
-
"filter by pillar (spec, decisions, handbook, tests, workflow, quality)"
|
|
2509
|
+
"filter by pillar (spec, decisions, handbook, tests, workflow, quality, intents)"
|
|
2011
2510
|
).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
2511
|
const repoRoot = resolve9(opts.cwd ?? ".");
|
|
2013
2512
|
const only = parseList(opts.only);
|