@vaubaan/harness 2.2.0 → 2.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +517 -68
- package/dist/cli/index.js +153 -121
- 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 +90 -58
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +1 -1
- package/dist/init.js +90 -58
- package/dist/init.js.map +1 -1
- package/dist/linters/index.js +124 -117
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +65 -32
- package/dist/parser/index.js +42 -38
- package/dist/parser/index.js.map +1 -1
- package/dist/{render-BzrBb_l4.d.ts → render-CTx7VNOK.d.ts} +3 -3
- package/dist/render.d.ts +1 -1
- package/dist/render.js +37 -32
- package/dist/render.js.map +1 -1
- package/dist/skills/doc-audit.skill.md +21 -20
- package/dist/skills/drift-detector.skill.md +17 -17
- package/dist/skills/handbook-writer.skill.md +3 -3
- 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/{journey.md.tmpl → intent.md.tmpl} +8 -7
- package/package.json +3 -7
- package/dist/commands/journey.cmd.md +0 -22
- package/dist/commands/story.cmd.md +0 -24
- package/dist/skills/journey-writer.skill.md +0 -159
package/dist/init.js
CHANGED
|
@@ -9,9 +9,15 @@ var MANAGED_FILES = /* @__PURE__ */ new Set([
|
|
|
9
9
|
"AGENTS.md",
|
|
10
10
|
"CLAUDE.md",
|
|
11
11
|
".harness-manifest.json",
|
|
12
|
-
// Index of the optional
|
|
12
|
+
// Index of the optional intents pillar, rendered while an intent file exists.
|
|
13
|
+
"docs/intents/README.md",
|
|
14
|
+
// Its 2.2 location, kept managed so `update` can remove it (see MOVED_PATHS).
|
|
13
15
|
"docs/journeys/README.md"
|
|
14
16
|
]);
|
|
17
|
+
var MOVED_PATHS = /* @__PURE__ */ new Map([
|
|
18
|
+
// 2.3: the journeys pillar became the intents pillar.
|
|
19
|
+
["docs/journeys/README.md", "docs/intents/README.md"]
|
|
20
|
+
]);
|
|
15
21
|
var RELEASED_PATHS = [
|
|
16
22
|
".mcp.json",
|
|
17
23
|
".codex/config.toml",
|
|
@@ -84,7 +90,7 @@ import { join as join2 } from "path";
|
|
|
84
90
|
import { z } from "zod";
|
|
85
91
|
|
|
86
92
|
// src/version.ts
|
|
87
|
-
var VERSION = "2.
|
|
93
|
+
var VERSION = "2.3.1";
|
|
88
94
|
|
|
89
95
|
// src/cli/manifest.ts
|
|
90
96
|
var MANIFEST_FILENAME = ".harness-manifest.json";
|
|
@@ -156,12 +162,16 @@ var CmdArgEnumSchema = z2.object({
|
|
|
156
162
|
name: z2.string().min(1),
|
|
157
163
|
type: z2.literal("enum"),
|
|
158
164
|
values: z2.array(z2.string()).min(1),
|
|
159
|
-
default: z2.string().optional()
|
|
165
|
+
default: z2.string().optional(),
|
|
166
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
167
|
+
required: z2.boolean().optional()
|
|
160
168
|
}).strict();
|
|
161
169
|
var CmdArgStringSchema = z2.object({
|
|
162
170
|
name: z2.string().min(1),
|
|
163
171
|
type: z2.literal("string"),
|
|
164
|
-
default: z2.string().optional()
|
|
172
|
+
default: z2.string().optional(),
|
|
173
|
+
/** False when the command runs without the argument. Defaults to true. */
|
|
174
|
+
required: z2.boolean().optional()
|
|
165
175
|
}).strict();
|
|
166
176
|
var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
|
|
167
177
|
var CmdFrontmatterSchema = z2.object({
|
|
@@ -171,10 +181,10 @@ var CmdFrontmatterSchema = z2.object({
|
|
|
171
181
|
args: z2.array(CmdArgSchema).optional(),
|
|
172
182
|
description: z2.string().min(1)
|
|
173
183
|
}).strict();
|
|
174
|
-
var
|
|
175
|
-
var
|
|
184
|
+
var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
|
|
185
|
+
var IntentFrontmatterSchema = z2.object({
|
|
176
186
|
title: z2.string().min(1),
|
|
177
|
-
status: z2.enum(
|
|
187
|
+
status: z2.enum(INTENT_STATUSES),
|
|
178
188
|
actors: z2.array(z2.string().min(1)).min(1),
|
|
179
189
|
spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
|
|
180
190
|
last_reviewed: z2.union([z2.date(), z2.string().min(1)])
|
|
@@ -182,7 +192,7 @@ var JourneyFrontmatterSchema = z2.object({
|
|
|
182
192
|
var Schemas = {
|
|
183
193
|
Skill: SkillFrontmatterSchema,
|
|
184
194
|
Cmd: CmdFrontmatterSchema,
|
|
185
|
-
|
|
195
|
+
Intent: IntentFrontmatterSchema
|
|
186
196
|
};
|
|
187
197
|
var ParseError = class extends Error {
|
|
188
198
|
constructor(file, issues) {
|
|
@@ -266,12 +276,12 @@ function loadOverrides(worktreeDir) {
|
|
|
266
276
|
return { add: added, disable };
|
|
267
277
|
}
|
|
268
278
|
|
|
269
|
-
// src/parser/
|
|
279
|
+
// src/parser/intent.ts
|
|
270
280
|
import { existsSync as existsSync3, readFileSync as readFileSync4, readdirSync, statSync as statSync2 } from "fs";
|
|
271
281
|
import { basename as basename2, join as join4 } from "path";
|
|
272
282
|
import matter2 from "gray-matter";
|
|
273
|
-
var
|
|
274
|
-
var
|
|
283
|
+
var INTENTS_DIR = "docs/intents";
|
|
284
|
+
var INTENTS_INDEX_PATH = `${INTENTS_DIR}/README.md`;
|
|
275
285
|
var NODE_FIELDS = [
|
|
276
286
|
"status",
|
|
277
287
|
"spec",
|
|
@@ -325,7 +335,7 @@ function parseFrontmatter(text, errors) {
|
|
|
325
335
|
errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
|
|
326
336
|
return void 0;
|
|
327
337
|
}
|
|
328
|
-
const result = Schemas.
|
|
338
|
+
const result = Schemas.Intent.safeParse(data);
|
|
329
339
|
if (result.success) return result.data;
|
|
330
340
|
for (const issue of result.error.issues) {
|
|
331
341
|
const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
|
|
@@ -338,7 +348,7 @@ function newNode(title, level, line) {
|
|
|
338
348
|
title,
|
|
339
349
|
level,
|
|
340
350
|
line,
|
|
341
|
-
|
|
351
|
+
isTerminal: true,
|
|
342
352
|
fieldLines: {},
|
|
343
353
|
anchors: [],
|
|
344
354
|
acceptance: [],
|
|
@@ -365,12 +375,12 @@ function parseFields(node, lines, from, to, errors) {
|
|
|
365
375
|
const known = key;
|
|
366
376
|
node.fieldLines[known] = lineNo;
|
|
367
377
|
if (known === "status") {
|
|
368
|
-
if (
|
|
378
|
+
if (INTENT_STATUSES.includes(value)) {
|
|
369
379
|
node.status = value;
|
|
370
380
|
} else {
|
|
371
381
|
errors.push({
|
|
372
382
|
line: lineNo,
|
|
373
|
-
message: `invalid status \`${value}\` (expected ${
|
|
383
|
+
message: `invalid status \`${value}\` (expected ${INTENT_STATUSES.join(" | ")})`
|
|
374
384
|
});
|
|
375
385
|
}
|
|
376
386
|
} else if (known === "spec") {
|
|
@@ -391,7 +401,7 @@ function parseFields(node, lines, from, to, errors) {
|
|
|
391
401
|
return;
|
|
392
402
|
}
|
|
393
403
|
}
|
|
394
|
-
function
|
|
404
|
+
function parseIntentFile(relPath, text) {
|
|
395
405
|
const errors = [];
|
|
396
406
|
const meta = parseFrontmatter(text, errors);
|
|
397
407
|
const lines = maskFencedCode(text.split(/\r?\n/));
|
|
@@ -402,7 +412,7 @@ function parseJourney(relPath, text) {
|
|
|
402
412
|
if (h) headings.push({ index: i, ...h });
|
|
403
413
|
}
|
|
404
414
|
const h1 = headings.find((h) => h.depth === 1);
|
|
405
|
-
let
|
|
415
|
+
let statement;
|
|
406
416
|
if (h1) {
|
|
407
417
|
const paragraph = [];
|
|
408
418
|
for (let i = h1.index + 1; i < lines.length; i++) {
|
|
@@ -414,7 +424,7 @@ function parseJourney(relPath, text) {
|
|
|
414
424
|
if (line === MASKED_LINE || parseHeading(line)) break;
|
|
415
425
|
paragraph.push(line.trim());
|
|
416
426
|
}
|
|
417
|
-
if (paragraph.length)
|
|
427
|
+
if (paragraph.length) statement = paragraph.join(" ");
|
|
418
428
|
}
|
|
419
429
|
const nodes = [];
|
|
420
430
|
const stack = [];
|
|
@@ -430,7 +440,7 @@ function parseJourney(relPath, text) {
|
|
|
430
440
|
if (parentIndex !== void 0) {
|
|
431
441
|
node.parent = parentIndex;
|
|
432
442
|
const parent = nodes[parentIndex];
|
|
433
|
-
if (parent) parent.
|
|
443
|
+
if (parent) parent.isTerminal = false;
|
|
434
444
|
}
|
|
435
445
|
const next = headings[k + 1];
|
|
436
446
|
parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
|
|
@@ -440,32 +450,32 @@ function parseJourney(relPath, text) {
|
|
|
440
450
|
nodes.push(node);
|
|
441
451
|
}
|
|
442
452
|
const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
|
|
443
|
-
return { ...meta ? { meta } : {}, title, ...
|
|
453
|
+
return { ...meta ? { meta } : {}, title, ...statement ? { statement } : {}, nodes, errors };
|
|
444
454
|
}
|
|
445
|
-
function
|
|
446
|
-
const dir = join4(targetDir,
|
|
455
|
+
function listIntentFiles(targetDir) {
|
|
456
|
+
const dir = join4(targetDir, INTENTS_DIR);
|
|
447
457
|
if (!existsSync3(dir) || !statSync2(dir).isDirectory()) return [];
|
|
448
458
|
return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync2(join4(dir, f)).isFile()).sort();
|
|
449
459
|
}
|
|
450
|
-
function
|
|
451
|
-
return
|
|
452
|
-
const path = `${
|
|
460
|
+
function readIntentFiles(targetDir) {
|
|
461
|
+
return listIntentFiles(targetDir).map((file) => {
|
|
462
|
+
const path = `${INTENTS_DIR}/${file}`;
|
|
453
463
|
const text = readFileSync4(join4(targetDir, path), "utf8");
|
|
454
|
-
return { path, file, ...
|
|
464
|
+
return { path, file, ...parseIntentFile(path, text) };
|
|
455
465
|
});
|
|
456
466
|
}
|
|
457
|
-
function
|
|
458
|
-
const
|
|
459
|
-
const problems =
|
|
467
|
+
function loadIntentFiles(targetDir) {
|
|
468
|
+
const intentFiles = readIntentFiles(targetDir);
|
|
469
|
+
const problems = intentFiles.flatMap(
|
|
460
470
|
(j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
|
|
461
471
|
);
|
|
462
472
|
if (problems.length) {
|
|
463
473
|
throw new Error(
|
|
464
|
-
`invalid
|
|
474
|
+
`invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
|
|
465
475
|
${problems.join("\n")}`
|
|
466
476
|
);
|
|
467
477
|
}
|
|
468
|
-
return
|
|
478
|
+
return intentFiles;
|
|
469
479
|
}
|
|
470
480
|
|
|
471
481
|
// src/renderers/common.ts
|
|
@@ -515,12 +525,13 @@ function frontmatterDataForCmd(cmd) {
|
|
|
515
525
|
description: cmd.meta.description
|
|
516
526
|
};
|
|
517
527
|
if (cmd.meta.args && cmd.meta.args.length > 0) {
|
|
518
|
-
data.args = cmd.meta.args.map((a) => {
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
}
|
|
522
|
-
|
|
523
|
-
|
|
528
|
+
data.args = cmd.meta.args.map((a) => ({
|
|
529
|
+
name: a.name,
|
|
530
|
+
type: a.type,
|
|
531
|
+
...a.type === "enum" ? { values: a.values } : {},
|
|
532
|
+
...a.default !== void 0 ? { default: a.default } : {},
|
|
533
|
+
...a.required === false ? { required: false } : {}
|
|
534
|
+
}));
|
|
524
535
|
}
|
|
525
536
|
return data;
|
|
526
537
|
}
|
|
@@ -553,16 +564,16 @@ function buildUmbrellaBody(extras) {
|
|
|
553
564
|
...extras.hasQualityDoc ? [
|
|
554
565
|
"- `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."
|
|
555
566
|
] : [],
|
|
556
|
-
...extras.
|
|
557
|
-
"- `docs/
|
|
567
|
+
...extras.hasIntents ? [
|
|
568
|
+
"- `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."
|
|
558
569
|
] : [],
|
|
559
570
|
"",
|
|
560
571
|
"## Doc-first",
|
|
561
572
|
"",
|
|
562
573
|
"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.",
|
|
563
574
|
"",
|
|
564
|
-
...extras.
|
|
565
|
-
"- Visible change of behavior \u2192 a `proposed`
|
|
575
|
+
...extras.hasIntents ? [
|
|
576
|
+
"- Visible change of behavior \u2192 a `proposed` intent first (`/intent <verb + object>`), never the code first."
|
|
566
577
|
] : [],
|
|
567
578
|
"- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
|
|
568
579
|
"- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
|
|
@@ -692,16 +703,16 @@ function getRenderer(engine) {
|
|
|
692
703
|
return RENDERERS[engine];
|
|
693
704
|
}
|
|
694
705
|
|
|
695
|
-
// src/renderers/
|
|
696
|
-
var INTRO = "User
|
|
697
|
-
function
|
|
698
|
-
const lines = ["#
|
|
699
|
-
const sorted = [...
|
|
700
|
-
for (const
|
|
701
|
-
const status =
|
|
702
|
-
const actors =
|
|
703
|
-
lines.push(`- [${
|
|
704
|
-
for (const node of
|
|
706
|
+
// src/renderers/intents-index.ts
|
|
707
|
+
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 .`.";
|
|
708
|
+
function buildIntentsIndex(intentFiles) {
|
|
709
|
+
const lines = ["# Intents", "", INTRO, ""];
|
|
710
|
+
const sorted = [...intentFiles].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
|
|
711
|
+
for (const intentFile of sorted) {
|
|
712
|
+
const status = intentFile.meta?.status ?? "proposed";
|
|
713
|
+
const actors = intentFile.meta?.actors.join(", ") ?? "";
|
|
714
|
+
lines.push(`- [${intentFile.title}](./${intentFile.file}) \u2014 ${status} \xB7 ${actors}`);
|
|
715
|
+
for (const node of intentFile.nodes) {
|
|
705
716
|
lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
|
|
706
717
|
}
|
|
707
718
|
}
|
|
@@ -779,14 +790,14 @@ function render(input) {
|
|
|
779
790
|
availableCommands: Array.from(exposedCmds.values()),
|
|
780
791
|
hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
|
|
781
792
|
hasQualityDoc: input.hasQualityDoc === true,
|
|
782
|
-
|
|
793
|
+
hasIntents: (input.intentFiles?.length ?? 0) > 0
|
|
783
794
|
});
|
|
784
795
|
files.push({ path: "AGENTS.md", content: umbrellaContent });
|
|
785
796
|
if (engines.includes("claude-code")) {
|
|
786
797
|
files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
|
|
787
798
|
}
|
|
788
|
-
if (input.
|
|
789
|
-
files.push({ path:
|
|
799
|
+
if (input.intentFiles && input.intentFiles.length > 0) {
|
|
800
|
+
files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });
|
|
790
801
|
}
|
|
791
802
|
return { files, warnings };
|
|
792
803
|
}
|
|
@@ -819,8 +830,8 @@ function planInit(args) {
|
|
|
819
830
|
const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
|
|
820
831
|
const projectSkills = loadProjectSkills(args.targetDir);
|
|
821
832
|
const hasQualityDoc = existsSync4(join5(args.targetDir, QUALITY_DOC_PATH));
|
|
822
|
-
const
|
|
823
|
-
const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc,
|
|
833
|
+
const intentFiles = loadIntentFiles(args.targetDir);
|
|
834
|
+
const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, intentFiles });
|
|
824
835
|
return { engines, output };
|
|
825
836
|
}
|
|
826
837
|
|
|
@@ -1029,7 +1040,7 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
|
|
|
1029
1040
|
}
|
|
1030
1041
|
|
|
1031
1042
|
// src/cli/update.ts
|
|
1032
|
-
import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
|
|
1043
|
+
import { existsSync as existsSync7, readFileSync as readFileSync8, readdirSync as readdirSync4, statSync as statSync3 } from "fs";
|
|
1033
1044
|
import { dirname as dirname5, join as join9, resolve as resolve5 } from "path";
|
|
1034
1045
|
import { isDeepStrictEqual } from "util";
|
|
1035
1046
|
|
|
@@ -1080,6 +1091,27 @@ function releaseLegacyPaths(previous, warnings) {
|
|
|
1080
1091
|
if (released.length === 0) return previous;
|
|
1081
1092
|
return { ...previous, files: previous.files.filter((path) => !released.includes(path)) };
|
|
1082
1093
|
}
|
|
1094
|
+
function carryMovedPaths(root, previous, warnings) {
|
|
1095
|
+
let files = previous.files;
|
|
1096
|
+
let fileHashes = previous.fileHashes;
|
|
1097
|
+
for (const [from, to] of MOVED_PATHS) {
|
|
1098
|
+
if (!files.includes(from) || existsSync7(join9(root, from))) continue;
|
|
1099
|
+
files = [...new Set(files.map((path) => path === from ? to : path))];
|
|
1100
|
+
const hash = fileHashes?.[from];
|
|
1101
|
+
if (fileHashes && hash !== void 0) {
|
|
1102
|
+
const { [from]: _moved, ...rest } = fileHashes;
|
|
1103
|
+
fileHashes = { ...rest, [to]: hash };
|
|
1104
|
+
}
|
|
1105
|
+
}
|
|
1106
|
+
const oldDir = join9(root, "docs/journeys");
|
|
1107
|
+
if (existsSync7(oldDir) && statSync3(oldDir).isDirectory() && readdirSync4(oldDir).length > 0) {
|
|
1108
|
+
warnings.push(
|
|
1109
|
+
"docs/journeys/ is now docs/intents/: run `git mv docs/journeys docs/intents`, then `npx @vaubaan/harness update .` again"
|
|
1110
|
+
);
|
|
1111
|
+
}
|
|
1112
|
+
if (files === previous.files) return previous;
|
|
1113
|
+
return { ...previous, files, ...fileHashes ? { fileHashes } : {} };
|
|
1114
|
+
}
|
|
1083
1115
|
function legacyHookWarnings(root) {
|
|
1084
1116
|
const warnings = [];
|
|
1085
1117
|
for (const path of LEGACY_HOOK_FILES) {
|
|
@@ -1096,7 +1128,7 @@ function planInstallation(args, settings) {
|
|
|
1096
1128
|
const root = resolve5(args.targetDir);
|
|
1097
1129
|
const { engines } = settings;
|
|
1098
1130
|
const warnings = [];
|
|
1099
|
-
const previous = releaseLegacyPaths(settings.previous, warnings);
|
|
1131
|
+
const previous = carryMovedPaths(root, releaseLegacyPaths(settings.previous, warnings), warnings);
|
|
1100
1132
|
const preserved = [
|
|
1101
1133
|
.../* @__PURE__ */ new Set([...previous.preservedFiles ?? [], ...args.preserveFiles ?? []])
|
|
1102
1134
|
].sort();
|