@vaubaan/harness 2.4.0 → 3.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 +207 -83
- package/dist/cli/index.js +4165 -843
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/harn-canvas.cmd.md +23 -0
- package/dist/commands/{decision.cmd.md → harn-decision.cmd.md} +6 -6
- package/dist/commands/{doc-audit.cmd.md → harn-doc-audit.cmd.md} +7 -7
- package/dist/commands/{drift.cmd.md → harn-drift.cmd.md} +6 -6
- package/dist/commands/{handbook.cmd.md → harn-handbook.cmd.md} +6 -6
- package/dist/commands/harn-improve.cmd.md +20 -0
- package/dist/commands/{intent.cmd.md → harn-intent.cmd.md} +9 -9
- package/dist/commands/{readme.cmd.md → harn-readme.cmd.md} +6 -6
- package/dist/commands/{spec.cmd.md → harn-spec.cmd.md} +6 -6
- package/dist/commands/{test-plan.cmd.md → harn-test-plan.cmd.md} +6 -6
- package/dist/commands/harn-upgrade.cmd.md +22 -0
- package/dist/commands/{workflow.cmd.md → harn-workflow.cmd.md} +6 -6
- package/dist/index.d.ts +32 -3
- package/dist/index.js +533 -96
- package/dist/index.js.map +1 -1
- package/dist/init.d.ts +1 -1
- package/dist/init.js +468 -93
- package/dist/init.js.map +1 -1
- package/dist/linters/index.d.ts +3 -34
- package/dist/linters/index.js +996 -554
- package/dist/linters/index.js.map +1 -1
- package/dist/parser/index.d.ts +96 -6
- package/dist/parser/index.js +220 -10
- package/dist/parser/index.js.map +1 -1
- package/dist/render-BhUar2gf.d.ts +81 -0
- package/dist/render.d.ts +1 -1
- package/dist/render.js +233 -22
- package/dist/render.js.map +1 -1
- package/dist/skills/harn-canvas-review.skill.md +87 -0
- package/dist/skills/{decision-record-writer.skill.md → harn-decision-record-writer.skill.md} +2 -1
- package/dist/skills/{doc-audit.skill.md → harn-doc-audit.skill.md} +75 -26
- package/dist/skills/{drift-detector.skill.md → harn-drift-detector.skill.md} +15 -14
- package/dist/skills/harn-guide.skill.md +137 -0
- package/dist/skills/{handbook-writer.skill.md → harn-handbook-writer.skill.md} +2 -1
- package/dist/skills/{intent-writer.skill.md → harn-intent-writer.skill.md} +83 -16
- package/dist/skills/{readme-writer.skill.md → harn-readme-writer.skill.md} +4 -4
- package/dist/skills/harn-self-improve.skill.md +84 -0
- package/dist/skills/{spec-writer.skill.md → harn-spec-writer.skill.md} +8 -8
- package/dist/skills/{test-plan-writer.skill.md → harn-test-plan-writer.skill.md} +6 -5
- package/dist/skills/harn-upgrade.skill.md +171 -0
- package/dist/skills/{workflow-writer.skill.md → harn-workflow-writer.skill.md} +6 -5
- package/dist/templates/decisions-index.md.tmpl +11 -0
- package/dist/templates/handbook-index.md.tmpl +8 -0
- package/dist/templates/profile.md.tmpl +30 -0
- package/dist/types-CfUByAIr.d.ts +35 -0
- package/dist/view/index.d.ts +117 -0
- package/dist/view/index.js +3987 -0
- package/dist/view/index.js.map +1 -0
- package/package.json +5 -1
- package/dist/render-CTx7VNOK.d.ts +0 -45
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: harn-upgrade
|
|
3
|
+
description: |
|
|
4
|
+
Moves a project to a newer version of @vaubaan/harness: pins the
|
|
5
|
+
package, previews and applies `update`, resolves the conflicts it
|
|
6
|
+
lists, then applies the migration notes of every version crossed
|
|
7
|
+
(kept in this skill, one entry per release). Use it when the human
|
|
8
|
+
asks to update or upgrade the harness, or when `lint:generated-fresh`
|
|
9
|
+
fails after the package version changed.
|
|
10
|
+
engines: [claude-code, codex-cli, opencode]
|
|
11
|
+
tags: [harness, upgrade]
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Harness Upgrade
|
|
15
|
+
|
|
16
|
+
You move this project from the harness version that rendered it to a
|
|
17
|
+
newer one. `update` re-renders the generated files; it does not choose a
|
|
18
|
+
version, and it cannot do what a version asks of the project's own
|
|
19
|
+
files. That part is yours, and it is written below, version by version.
|
|
20
|
+
|
|
21
|
+
This file is rendered by the version *currently installed*: its notes
|
|
22
|
+
stop at that version. The notes of the target version arrive with it,
|
|
23
|
+
which is why step 3 comes before step 5.
|
|
24
|
+
|
|
25
|
+
## Procedure
|
|
26
|
+
|
|
27
|
+
1. **Read where the project is.** `harnessVersion` in
|
|
28
|
+
`.harness-manifest.json` is the version that rendered it (absent
|
|
29
|
+
before 1.1). Read how the project runs the harness: a dev dependency
|
|
30
|
+
in the package manifest, a pinned `npx @vaubaan/harness@<version>` in
|
|
31
|
+
CI or in the pre-commit hook, or the unpinned `npx`.
|
|
32
|
+
2. **Choose the target with the human.** The latest version, unless
|
|
33
|
+
they name one. Read its changelog entries between the two versions
|
|
34
|
+
(`npm view @vaubaan/harness versions`, then the `CHANGELOG.md` of the
|
|
35
|
+
package). Crossing a major version: say so, and what it removes,
|
|
36
|
+
before touching anything.
|
|
37
|
+
3. **Start from a clean tree**, on a branch named as the project's
|
|
38
|
+
workflow says, so the upgrade is one reviewable change. Then pin the
|
|
39
|
+
target wherever the project pins the harness: the dev dependency
|
|
40
|
+
(`npm install --save-dev @vaubaan/harness@<target>`), the CI file,
|
|
41
|
+
the hook. All of them, to the same version.
|
|
42
|
+
4. **Preview.** `npx @vaubaan/harness update . --dry-run`. It writes
|
|
43
|
+
nothing. Read the writes, the removals and every warning.
|
|
44
|
+
5. **Re-read this skill once the preview is clean**: after step 6 the
|
|
45
|
+
file on disk is the target version's, with the notes you need.
|
|
46
|
+
Until then, read them from the package:
|
|
47
|
+
`node_modules/@vaubaan/harness/dist/skills/harn-upgrade.skill.md`.
|
|
48
|
+
6. **Resolve conflicts, then apply.** `update` stops before any write
|
|
49
|
+
when a generated path holds a file it did not write, or a generated
|
|
50
|
+
file edited by hand. For each one: move the content to its source
|
|
51
|
+
(`docs/`, `docs/skills/`, `.harness-overrides/`), or keep the file as
|
|
52
|
+
the project's with `--preserve <path>` and tell the human it will no
|
|
53
|
+
longer be refreshed. Never delete a file to get past the check. Then
|
|
54
|
+
`npx @vaubaan/harness update .`.
|
|
55
|
+
7. **Apply the migration notes** below, for every version after the one
|
|
56
|
+
the project was on, up to the target, in order.
|
|
57
|
+
8. **Lint.** `npx @vaubaan/harness lint`. A new version may bring new
|
|
58
|
+
checks: fix each with the skill its message names, never by disabling
|
|
59
|
+
the linter. A check you cannot satisfy in this change is a finding
|
|
60
|
+
for the human, not a reason to pin back silently.
|
|
61
|
+
9. **Report**, then commit as the project's workflow says: from which
|
|
62
|
+
version to which, what was removed, what the notes made you change,
|
|
63
|
+
which files are preserved and therefore not refreshed, what is left.
|
|
64
|
+
|
|
65
|
+
## Guardrails
|
|
66
|
+
|
|
67
|
+
- **Never skip a major.** From 1.x, go to the last 2.x first, lint
|
|
68
|
+
green, commit, then to 3.x.
|
|
69
|
+
- **Never edit a generated file** to make it match: change its source
|
|
70
|
+
and run `update .`.
|
|
71
|
+
- **A backup exists.** `update` prints the folder where it kept the
|
|
72
|
+
previous content of every file it touched. On a failed apply it rolls
|
|
73
|
+
back by itself; mention the folder in your report.
|
|
74
|
+
- **Rollback** is pinning the previous version and running `update .`
|
|
75
|
+
again; a version's notes say when that is not enough.
|
|
76
|
+
- **Do not adopt new pillars during an upgrade.** A new version may
|
|
77
|
+
offer some; that is a separate decision (`harn-guide`).
|
|
78
|
+
|
|
79
|
+
## Migration notes
|
|
80
|
+
|
|
81
|
+
One entry per release that asks something of a project, newest first.
|
|
82
|
+
"Nothing to do" means `update .` is the whole migration.
|
|
83
|
+
|
|
84
|
+
### 3.0
|
|
85
|
+
|
|
86
|
+
Breaking: pillars are active by presence, and only the README is
|
|
87
|
+
required; every shipped skill and command is prefixed with `harn-`.
|
|
88
|
+
|
|
89
|
+
- **Commands and skills are renamed**: `/spec` is `/harn-spec`, `/intent`
|
|
90
|
+
is `/harn-intent`, `/harness-upgrade` is `/harn-upgrade`, and so on;
|
|
91
|
+
`spec-writer` is `harn-spec-writer`, `harness-guide` is `harn-guide`.
|
|
92
|
+
`update` removes the old files and writes the new ones by itself.
|
|
93
|
+
Then search the project's own docs, scripts and CI for the old command
|
|
94
|
+
names and replace them. `update` warns on every project skill
|
|
95
|
+
(`docs/skills/`), override (`.harness-overrides/skills/`) or
|
|
96
|
+
`disable.yaml` entry that still names an old id: rename it, or it
|
|
97
|
+
becomes an extra skill instead of replacing the shipped one.
|
|
98
|
+
|
|
99
|
+
- **Nothing breaks for a project that has the six former pillars**:
|
|
100
|
+
their folders exist, so they are active and their skills stay.
|
|
101
|
+
- **A pillar folder you had only because the lint demanded it** (test
|
|
102
|
+
plans that say nothing, a workflow nobody follows): ask the human
|
|
103
|
+
whether to keep it. Deleting the folder, then `update .`, removes its
|
|
104
|
+
skill, its command and its checks.
|
|
105
|
+
- **`AGENTS.md` changes**: its map and rules now hold a line only for an
|
|
106
|
+
active pillar, and one line names the others. If the project preserved
|
|
107
|
+
`AGENTS.md`, tell the human it no longer reflects the pillars.
|
|
108
|
+
- **`lint:doc-layout`** no longer requires any folder; it now fails on a
|
|
109
|
+
pillar folder that holds no file. Fill it or remove it.
|
|
110
|
+
- **`check`** no longer requires `docs/`: only the README and the
|
|
111
|
+
`.gitignore` entries.
|
|
112
|
+
- **The `stop-hook` command is gone.** 2.x kept it as a silent no-op for
|
|
113
|
+
hook entries written by 1.x. Search `.claude/settings.json` and
|
|
114
|
+
`.codex/hooks.json` for `@vaubaan/harness stop-hook` and remove the
|
|
115
|
+
entry: it now fails on every turn. `update` warns when it finds one.
|
|
116
|
+
- **Custom skills** in `docs/skills/` or `.harness-overrides/` keep
|
|
117
|
+
working; they may now declare `pillars: [...]` to be rendered only
|
|
118
|
+
while one of those pillars is active.
|
|
119
|
+
- **Programmatic callers of `render()`**: `hasQualityDoc` is replaced by
|
|
120
|
+
`activePillars`.
|
|
121
|
+
- New, nothing to do unless wanted: the `add <pillar>` command, the
|
|
122
|
+
`profiles` pillar, the `harn-guide` and `harn-upgrade` skills; the
|
|
123
|
+
view of the context (`vaubaan-harness view`) and review sessions
|
|
124
|
+
(`/harn-canvas`); lessons from reviews (`/harn-improve`), which read
|
|
125
|
+
agent conversations only if the project lists them under
|
|
126
|
+
`lessons.sources` in `.harnessrc`. All of them write only under
|
|
127
|
+
`.vaubaan/`, already gitignored.
|
|
128
|
+
|
|
129
|
+
### 2.4, 2.3.1
|
|
130
|
+
|
|
131
|
+
Nothing to do.
|
|
132
|
+
|
|
133
|
+
### 2.3
|
|
134
|
+
|
|
135
|
+
The journeys pillar became the intents pillar. Only for a project that
|
|
136
|
+
has `docs/journeys/`:
|
|
137
|
+
|
|
138
|
+
1. `git mv docs/journeys docs/intents`, then `update .`.
|
|
139
|
+
2. Replace `/story` and `/journey` by `/harn-intent` in the project's own
|
|
140
|
+
docs, and `lint:journey-*` by `lint:intent-*` in a lint configuration.
|
|
141
|
+
|
|
142
|
+
### 2.2, 2.1
|
|
143
|
+
|
|
144
|
+
Nothing to do.
|
|
145
|
+
|
|
146
|
+
### 2.0
|
|
147
|
+
|
|
148
|
+
Breaking: generated files are committed, and the Stop hook is replaced
|
|
149
|
+
by the lint in CI and in the pre-commit hook.
|
|
150
|
+
|
|
151
|
+
1. After `update .`: stale agent files and the OpenCode plugin are
|
|
152
|
+
removed; files 1.x wrote into engine settings (`.mcp.json`,
|
|
153
|
+
`.claude/settings.json`, `.codex/hooks.json`, `.codex/config.toml`,
|
|
154
|
+
`.opencode/opencode.json`) are left in place and are now the
|
|
155
|
+
project's.
|
|
156
|
+
2. Remove the `npx -y @vaubaan/harness stop-hook` entry from
|
|
157
|
+
`.claude/settings.json` or `.codex/hooks.json`.
|
|
158
|
+
3. Remove `AGENTS.md`, `CLAUDE.md`, `.claude/`, `.codex/`, `.agents/`,
|
|
159
|
+
`.opencode/`, `.harness-manifest.json`, `.harness/` and `.mcp.json`
|
|
160
|
+
from `.gitignore`; keep `.harness-overrides/` and `.vaubaan/`. Commit
|
|
161
|
+
the generated files.
|
|
162
|
+
4. Run `npx @vaubaan/harness lint` in CI and add it to the pre-commit
|
|
163
|
+
hook.
|
|
164
|
+
|
|
165
|
+
### 1.x
|
|
166
|
+
|
|
167
|
+
- From `@sbw-vaubaan/harness` (before 1.3): `uninstall .` with the old
|
|
168
|
+
package, then `init . --engines=<list>` with the new one.
|
|
169
|
+
- From 0.x or 1.0: re-run `init . --engines=<list>`; a manifest older
|
|
170
|
+
than version 4 is migrated by `update`, never by `init`.
|
|
171
|
+
- Within 1.x otherwise: `update --dry-run`, then `update`.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
id: workflow-writer
|
|
2
|
+
id: harn-workflow-writer
|
|
3
3
|
description: |
|
|
4
4
|
Updates `docs/workflow/coding-workflow.md`. Reads `.github/workflows/`,
|
|
5
5
|
`vercel.json`, the `package.json` scripts, the repo's branch/PR
|
|
@@ -7,6 +7,7 @@ description: |
|
|
|
7
7
|
PR process / branches / release).
|
|
8
8
|
engines: [claude-code, codex-cli, opencode]
|
|
9
9
|
requires: [multi-step]
|
|
10
|
+
pillars: [workflow]
|
|
10
11
|
tags: [workflow, doc, writer, ci]
|
|
11
12
|
---
|
|
12
13
|
|
|
@@ -38,8 +39,8 @@ short.
|
|
|
38
39
|
|
|
39
40
|
- The agent modifies a CI workflow, a deployment config, or a
|
|
40
41
|
`package.json` script → update the workflow doc.
|
|
41
|
-
- `doc-audit` flags `coding-workflow.md` as missing or stale.
|
|
42
|
-
- `/workflow` invoked by the human.
|
|
42
|
+
- `harn-doc-audit` flags `coding-workflow.md` as missing or stale.
|
|
43
|
+
- `/harn-workflow` invoked by the human.
|
|
43
44
|
- Onboarding: a new contributor needs a recap of the process.
|
|
44
45
|
|
|
45
46
|
## Procedure
|
|
@@ -94,7 +95,7 @@ short.
|
|
|
94
95
|
## Criteria
|
|
95
96
|
|
|
96
97
|
- **5 sections present**. The `lint:cardinal-files` linter checks the
|
|
97
|
-
file's presence; `doc-audit` checks the presence of the 5 required
|
|
98
|
+
file's presence; `harn-doc-audit` checks the presence of the 5 required
|
|
98
99
|
sections by their header (regex). All 5 are mandatory; the
|
|
99
100
|
Languages section is optional.
|
|
100
101
|
- **Concrete and actionable**. Mention the exact commands
|
|
@@ -194,7 +195,7 @@ Finish by:
|
|
|
194
195
|
command, read `package.json` or ask the human. A workflow doc with a
|
|
195
196
|
wrong command is worse than no doc.
|
|
196
197
|
- **No "because it's better" reasoning**. Justifications live in the
|
|
197
|
-
ADRs (`decision-record-writer`). The workflow doc describes *what is
|
|
198
|
+
ADRs (`harn-decision-record-writer`). The workflow doc describes *what is
|
|
198
199
|
in place*.
|
|
199
200
|
- **Cross-link, do not duplicate**. The content of `ci.yml` is not
|
|
200
201
|
copied here — we link to the file. The workflow doc *summarizes* and
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Decisions
|
|
2
|
+
|
|
3
|
+
The structural decisions in force in this project, one file per
|
|
4
|
+
decision, `<slug>.md`, no numbering. Each has four sections: Context,
|
|
5
|
+
Decision, Consequences, Rejected alternatives. A decision that changes
|
|
6
|
+
is rewritten as a new file; the old one is deleted and its option moves
|
|
7
|
+
to the Rejected alternatives of the new one.
|
|
8
|
+
|
|
9
|
+
## Decisions in force
|
|
10
|
+
|
|
11
|
+
<!-- One bullet per decision, newest first: its title as a link to its file, then the rule in one sentence. -->
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# Handbook
|
|
2
|
+
|
|
3
|
+
What the code of this project does not say: entry points, invariants
|
|
4
|
+
across files, traps, settings outside the repo, manual procedures. One
|
|
5
|
+
`<slug>.md` per feature, no numbering; each declares the code it depends
|
|
6
|
+
on in `tracks:`.
|
|
7
|
+
|
|
8
|
+
<!-- One bullet per handbook: its title as a link to its file, then what it covers. -->
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: <WHO THEY ARE, IN A FEW WORDS>
|
|
3
|
+
status: hypothesis
|
|
4
|
+
last_reviewed: <DATE>
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# <WHO THEY ARE>
|
|
8
|
+
|
|
9
|
+
<!--
|
|
10
|
+
One file per kind of user the project serves; the file name is the name
|
|
11
|
+
the intents use in `actors:`. A profile is a `hypothesis` until research
|
|
12
|
+
backs it: then set `status: validated` and add `evidence:`, a relative
|
|
13
|
+
path to a file of the repo or a URL. Never copy interview notes here.
|
|
14
|
+
|
|
15
|
+
A pain is what the user lives, not a missing feature. The most severe
|
|
16
|
+
first: the order is the rank. Each bullet opens with its name in bold;
|
|
17
|
+
`**Context rot**` is referred to as `context-rot` in an intent's
|
|
18
|
+
`relieves:`. No jobs section: the profile's jobs are the intents that
|
|
19
|
+
name it. Target 20-40 lines.
|
|
20
|
+
-->
|
|
21
|
+
|
|
22
|
+
<One paragraph: who they are and in what situation.>
|
|
23
|
+
|
|
24
|
+
## Pains
|
|
25
|
+
|
|
26
|
+
- **<Name of the pain>** — <what hurts or blocks them today>
|
|
27
|
+
|
|
28
|
+
## Gains
|
|
29
|
+
|
|
30
|
+
- **<Name of the gain>** — <the outcome they hope for>
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
interface HarnessLintConfig {
|
|
2
|
+
ignore: ReadonlyArray<string>;
|
|
3
|
+
}
|
|
4
|
+
declare function loadLintConfig(repoRoot: string): HarnessLintConfig;
|
|
5
|
+
|
|
6
|
+
type Severity = "error" | "warning";
|
|
7
|
+
interface LintIssue {
|
|
8
|
+
linter: string;
|
|
9
|
+
severity: Severity;
|
|
10
|
+
file: string;
|
|
11
|
+
line?: number;
|
|
12
|
+
message: string;
|
|
13
|
+
}
|
|
14
|
+
interface LintContext {
|
|
15
|
+
repoRoot: string;
|
|
16
|
+
config: HarnessLintConfig;
|
|
17
|
+
}
|
|
18
|
+
interface Linter {
|
|
19
|
+
id: string;
|
|
20
|
+
pillars: ReadonlyArray<string>;
|
|
21
|
+
defaultSeverity: Severity;
|
|
22
|
+
suggestedSkills?: ReadonlyArray<string>;
|
|
23
|
+
run(repoRoot: string, ctx?: LintContext): LintIssue[];
|
|
24
|
+
}
|
|
25
|
+
interface LintReport {
|
|
26
|
+
version: 1;
|
|
27
|
+
summary: {
|
|
28
|
+
errors: number;
|
|
29
|
+
warnings: number;
|
|
30
|
+
pass: boolean;
|
|
31
|
+
};
|
|
32
|
+
issues: LintIssue[];
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export { type HarnessLintConfig as H, type LintContext as L, type Severity as S, type LintIssue as a, type LintReport as b, type Linter as c, loadLintConfig as l };
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
import { b as LintReport, a as LintIssue } from '../types-CfUByAIr.js';
|
|
2
|
+
|
|
3
|
+
type Domain = "harness" | "project" | "local";
|
|
4
|
+
declare const NODE_TYPES: readonly ["readme", "spec", "section", "term", "decision", "alternative", "handbook", "test-plan", "known-gap", "workflow", "quality", "doc", "intent-file", "intent", "linter", "skill", "command", "rendered-file", "path", "glob", "lesson"];
|
|
5
|
+
type NodeType = (typeof NODE_TYPES)[number];
|
|
6
|
+
type EdgeType = "contains" | "tracks" | "anchors" | "requires" | "creates" | "spec" | "links-to" | "gap-of" | "checks" | "suggests" | "invokes" | "renders-to";
|
|
7
|
+
type AttrValue = string | number | boolean | null | string[] | {
|
|
8
|
+
[k: string]: AttrValue;
|
|
9
|
+
};
|
|
10
|
+
interface GraphNode {
|
|
11
|
+
id: string;
|
|
12
|
+
type: NodeType;
|
|
13
|
+
domain: Domain;
|
|
14
|
+
title: string;
|
|
15
|
+
/** Path from the repo root, or the package name for a harness node. */
|
|
16
|
+
sourcePath: string;
|
|
17
|
+
/** 1-based; 0 when the node has no line of its own. */
|
|
18
|
+
line: number;
|
|
19
|
+
parent?: string;
|
|
20
|
+
attrs: Record<string, AttrValue>;
|
|
21
|
+
issues: LintIssue[];
|
|
22
|
+
}
|
|
23
|
+
interface GraphEdge {
|
|
24
|
+
from: string;
|
|
25
|
+
to: string;
|
|
26
|
+
type: EdgeType;
|
|
27
|
+
line: number;
|
|
28
|
+
}
|
|
29
|
+
interface ContextGraph {
|
|
30
|
+
version: 1;
|
|
31
|
+
harness: string;
|
|
32
|
+
nodes: GraphNode[];
|
|
33
|
+
edges: GraphEdge[];
|
|
34
|
+
lint: {
|
|
35
|
+
ran: boolean;
|
|
36
|
+
errors: number;
|
|
37
|
+
warnings: number;
|
|
38
|
+
unattached: LintIssue[];
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
interface BuildOptions {
|
|
42
|
+
/** Run the linters and attach their issues (default true). */
|
|
43
|
+
lint?: boolean;
|
|
44
|
+
/** A report already computed; skips running the linters. */
|
|
45
|
+
report?: LintReport;
|
|
46
|
+
/** Directory holding the shipped `skills/` and `commands/`. */
|
|
47
|
+
packageDir?: string;
|
|
48
|
+
}
|
|
49
|
+
declare function buildGraph(repoRoot: string, opts?: BuildOptions): ContextGraph;
|
|
50
|
+
/** The graph as written to `.vaubaan/graph.json`. */
|
|
51
|
+
declare function serializeGraph(graph: ContextGraph): string;
|
|
52
|
+
declare const GRAPH_PATH: string;
|
|
53
|
+
|
|
54
|
+
interface ThreadMessage {
|
|
55
|
+
author: "human" | "agent";
|
|
56
|
+
body: string;
|
|
57
|
+
at: string;
|
|
58
|
+
changes?: Array<{
|
|
59
|
+
path: string;
|
|
60
|
+
line: number;
|
|
61
|
+
}>;
|
|
62
|
+
}
|
|
63
|
+
interface Thread {
|
|
64
|
+
id: string;
|
|
65
|
+
anchor: {
|
|
66
|
+
nodeId: string;
|
|
67
|
+
sourcePath: string;
|
|
68
|
+
line: number;
|
|
69
|
+
};
|
|
70
|
+
status: "open" | "submitted" | "answered" | "resolved";
|
|
71
|
+
batch?: number;
|
|
72
|
+
messages: ThreadMessage[];
|
|
73
|
+
}
|
|
74
|
+
interface JournalEntry {
|
|
75
|
+
at: string;
|
|
76
|
+
files: string[];
|
|
77
|
+
errors: number;
|
|
78
|
+
warnings: number;
|
|
79
|
+
note?: string;
|
|
80
|
+
}
|
|
81
|
+
/** What a review session adds to the view; absent for the static page. */
|
|
82
|
+
interface SessionView {
|
|
83
|
+
id: string;
|
|
84
|
+
/** The graph at the session start, for the differences. */
|
|
85
|
+
base: ContextGraph;
|
|
86
|
+
threads: Thread[];
|
|
87
|
+
journal: JournalEntry[];
|
|
88
|
+
/** Graph revision, bumped on each rebuild. */
|
|
89
|
+
revision: number;
|
|
90
|
+
}
|
|
91
|
+
interface RenderOptions {
|
|
92
|
+
session?: SessionView;
|
|
93
|
+
/** Prefix of source links; the static page sits two levels under the repo root. */
|
|
94
|
+
sourcePrefix?: string;
|
|
95
|
+
}
|
|
96
|
+
/** A stable HTML id for a node id. */
|
|
97
|
+
declare function htmlId(nodeId: string): string;
|
|
98
|
+
declare function renderView(graph: ContextGraph, opts?: RenderOptions): string;
|
|
99
|
+
|
|
100
|
+
interface ViewArgs {
|
|
101
|
+
targetDir: string;
|
|
102
|
+
/** Directory receiving `graph.json` and `view/index.html`; default `<target>/.vaubaan`. */
|
|
103
|
+
outDir?: string;
|
|
104
|
+
/** Skip the linters (faster; no issue attached). */
|
|
105
|
+
lint?: boolean;
|
|
106
|
+
packageDir?: string;
|
|
107
|
+
}
|
|
108
|
+
interface ViewResult {
|
|
109
|
+
graph: ContextGraph;
|
|
110
|
+
graphPath: string;
|
|
111
|
+
htmlPath: string;
|
|
112
|
+
}
|
|
113
|
+
declare const VIEW_PATH = ".vaubaan/view/index.html";
|
|
114
|
+
/** Builds the context graph and renders the view (docs/spec/coding-agent-harness.md §10.4). */
|
|
115
|
+
declare function viewCommand(args: ViewArgs): ViewResult;
|
|
116
|
+
|
|
117
|
+
export { type AttrValue, type BuildOptions, type ContextGraph, type Domain, type EdgeType, GRAPH_PATH, type GraphEdge, type GraphNode, type JournalEntry, NODE_TYPES, type NodeType, type RenderOptions, type SessionView, type Thread, type ThreadMessage, VIEW_PATH, type ViewArgs, type ViewResult, buildGraph, htmlId, renderView, serializeGraph, viewCommand };
|