@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/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 journeys pillar, rendered while a journey exists.
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.2.0";
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 JOURNEY_STATUSES = ["proposed", "implemented", "deprecated"];
175
- var JourneyFrontmatterSchema = z2.object({
184
+ var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
185
+ var IntentFrontmatterSchema = z2.object({
176
186
  title: z2.string().min(1),
177
- status: z2.enum(JOURNEY_STATUSES),
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
- Journey: JourneyFrontmatterSchema
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/journey.ts
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 JOURNEYS_DIR = "docs/journeys";
274
- var JOURNEYS_INDEX_PATH = `${JOURNEYS_DIR}/README.md`;
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.Journey.safeParse(data);
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
- isLeaf: true,
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 (JOURNEY_STATUSES.includes(value)) {
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 ${JOURNEY_STATUSES.join(" | ")})`
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 parseJourney(relPath, text) {
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 story;
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) story = paragraph.join(" ");
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.isLeaf = false;
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, ...story ? { story } : {}, nodes, errors };
453
+ return { ...meta ? { meta } : {}, title, ...statement ? { statement } : {}, nodes, errors };
444
454
  }
445
- function listJourneyFiles(targetDir) {
446
- const dir = join4(targetDir, JOURNEYS_DIR);
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 readJourneys(targetDir) {
451
- return listJourneyFiles(targetDir).map((file) => {
452
- const path = `${JOURNEYS_DIR}/${file}`;
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, ...parseJourney(path, text) };
464
+ return { path, file, ...parseIntentFile(path, text) };
455
465
  });
456
466
  }
457
- function loadJourneys(targetDir) {
458
- const journeys = readJourneys(targetDir);
459
- const problems = journeys.flatMap(
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 journeys (run \`npx @vaubaan/harness lint --pillar journeys\`):
474
+ `invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
465
475
  ${problems.join("\n")}`
466
476
  );
467
477
  }
468
- return journeys;
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
- if (a.type === "enum") {
520
- return a.default !== void 0 ? { name: a.name, type: a.type, values: a.values, default: a.default } : { name: a.name, type: a.type, values: a.values };
521
- }
522
- return a.default !== void 0 ? { name: a.name, type: a.type, default: a.default } : { name: a.name, type: a.type };
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.hasJourneys ? [
557
- "- `docs/journeys/<journey>.md` \u2014 user intentions and journeys, anchored to the code. `docs/journeys/README.md` is the generated index."
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.hasJourneys ? [
565
- "- Visible change of behavior \u2192 a `proposed` leaf first (`/story <intent>`), never the code first."
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/journeys-index.ts
696
- var INTRO = "User intentions and journeys of this project, anchored to the code. Generated by `@vaubaan/harness` from `docs/journeys/*.md`: edit the journeys, not this file, then run `npx @vaubaan/harness update .`.";
697
- function buildJourneysIndex(journeys) {
698
- const lines = ["# Journeys", "", INTRO, ""];
699
- const sorted = [...journeys].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
700
- for (const journey of sorted) {
701
- const status = journey.meta?.status ?? "proposed";
702
- const actors = journey.meta?.actors.join(", ") ?? "";
703
- lines.push(`- [${journey.title}](./${journey.file}) \u2014 ${status} \xB7 ${actors}`);
704
- for (const node of journey.nodes) {
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
- hasJourneys: (input.journeys?.length ?? 0) > 0
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.journeys && input.journeys.length > 0) {
789
- files.push({ path: JOURNEYS_INDEX_PATH, content: buildJourneysIndex(input.journeys) });
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 journeys = loadJourneys(args.targetDir);
823
- const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, journeys });
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();