@venizia/vulcan 0.4.10-2 → 0.4.10-3

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.
Files changed (50) hide show
  1. package/README.md +19 -14
  2. package/base/hooks/guard-outside.ts +6 -17
  3. package/base/hooks/guard-writes.ts +3 -24
  4. package/base/rules.md +3 -3
  5. package/base/skills/visualize-work/SKILL.md +1 -1
  6. package/base/skills/visualize-work/references/spec.md +1 -1
  7. package/package.json +3 -3
  8. package/src/agents/resolve.ts +1 -0
  9. package/src/board/common/types.ts +2 -2
  10. package/src/board/schema.ts +4 -1
  11. package/src/board/settings.ts +1 -1
  12. package/src/commands/help.command.ts +2 -63
  13. package/src/commands/table.ts +315 -0
  14. package/src/commit/check.ts +1 -0
  15. package/src/commit/common/constants.ts +2 -0
  16. package/src/commit/hook.ts +44 -4
  17. package/src/common/constants.ts +6 -3
  18. package/src/common/env-variables.ts +37 -0
  19. package/src/common/index.ts +1 -0
  20. package/src/config/loader.ts +22 -0
  21. package/src/config/schema.ts +121 -4
  22. package/src/create/add-app.ts +5 -0
  23. package/src/create/common/constants.ts +5 -3
  24. package/src/create/preset.ts +1 -0
  25. package/src/doctor/checks.ts +10 -0
  26. package/src/doctor/common/constants.ts +26 -0
  27. package/src/doctor/runner.ts +1 -0
  28. package/src/doctor/schema.ts +4 -0
  29. package/src/hooks/owner-reply.ts +5 -0
  30. package/src/hooks/project-guards.ts +25 -4
  31. package/src/hooks/session-digest.ts +9 -0
  32. package/src/init/scaffold.ts +1 -0
  33. package/src/local/auto-clean.ts +2 -1
  34. package/src/local/clean.ts +1 -0
  35. package/src/manifest/render.ts +48 -6
  36. package/src/owner/constants.ts +3 -1
  37. package/src/owner/profile.ts +1 -0
  38. package/src/owner/schema.ts +37 -6
  39. package/src/router.ts +4 -130
  40. package/src/rules/base.ts +1 -0
  41. package/src/signals/loop.ts +1 -0
  42. package/src/skills/frontmatter.ts +1 -0
  43. package/src/sync/planner.ts +1 -0
  44. package/src/theme/index.ts +1 -0
  45. package/src/theme/tokens.ts +305 -0
  46. package/src/ui/prompt.ts +1 -0
  47. package/src/visualize/page.ts +4 -4
  48. package/src/visualize/render.ts +2 -1
  49. package/src/visualize/theme.ts +27 -10
  50. package/src/wiki/anchors.ts +1 -0
package/README.md CHANGED
@@ -9,6 +9,8 @@ bun x --no-install vulcan sync
9
9
  bun x --no-install vulcan doctor
10
10
  ```
11
11
 
12
+ `doctor` fails with `[scaffold]` until you describe the project in `.agents/knowledge/index.md` and delete the `vulcan:scaffold` line; it is the first item `init` lists under `left to do`.
13
+
12
14
  `--no-install` matters: the unscoped npm name `vulcan` belongs to an unrelated package, and without the
13
15
  flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
14
16
 
@@ -16,16 +18,26 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
16
18
 
17
19
  | Command | What it does |
18
20
  |---|---|
19
- | `init` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.mts`, the three lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, a Makefile with the `-include` and a fallback rule for a missing `vulcan.mk`. Appends the agent entries to `.gitignore`, installs the lint tools (listing them first; a failed install exits 1), and ends with a numbered list of what is left. Needs a `package.json` in the directory. A project whose `package.json` declares `workspaces` gets no root lint configs. Never overwrites; prints what to add to existing files |
21
+ | `init` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.mts`, the two lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, `.agents/hooks/trusted-hosts.local.example`, a Makefile with the `-include` and a fallback rule for a missing `vulcan.mk`. Appends the agent entries to `.gitignore`, installs the lint tools (listing them first; a failed install exits 1), and ends with a numbered list of what is left. Needs a `package.json` in the directory. A project whose `package.json` declares `workspaces` gets no root lint configs. Never overwrites; prints what to add to existing files |
20
22
  | `init --preset <name\|file:path> --project <name> --app <name> [--backend-dir\|--frontend-dir <name>] [--shared-dir <name>]` | Create a new monorepo with its first app from a framework preset: the root manifests, the app's files, the VULCAN layer and a knowledge bundle, then install, `git init` (a missing git is reported, not fatal), `sync` and the checks, and ends with `cd <project> && make dev` and the app's URL. A name missing from the flags is asked in a terminal; none has a default. Refuses a folder that is not empty |
21
- | `add --preset <name\|file:path> --app <name> [--backend-dir\|--frontend-dir <name>] [--api <app> \| --no-api]` | Add an app from a preset to a monorepo `init --preset` created: registers it in `workspaces`, the `catalog`, the config and the knowledge bundle, picks a free port, then installs, syncs and checks. A frontend says which backend app to proxy `/api` to |
23
+ | `add --preset <name\|file:path> (--app <name> \| --lib <name> \| --shared <name>) [--dir <folder>] [--scope <@scope>] [--backend-dir\|--frontend-dir <name>] [--api <app> \| --no-api]` | Add an app, a library other apps import (`--lib`) or a side-neutral shared package (`--shared`) to a monorepo `init --preset` created: registers it in `workspaces`, the `catalog`, the config and the knowledge bundle, picks a free port, then installs, syncs and checks. `--dir` is for a library or a shared package; `--scope` names the package `@scope/<name>`. A frontend says which backend app to proxy `/api` to |
22
24
  | `sync [--dry-run]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`; an existing file is left alone), `.claude/settings.json` (shipped + slot + project hooks + `claude.settings` over your personal keys; what it applied is recorded in `.claude/vulcan-managed.json`, so a removed choice is removed, and a hook it wrote is taken back by its command even after you edited its entry), `.claude/skills/` links, and the committed `.agents/vulcan.manifest.json`. Prints each base rule added, changed or removed since the manifest last recorded it, with its new text, then records the new hashes. `--dry-run` writes nothing and labels each line `would create`, `would replace` or `would remove`. Idempotent |
23
- | `doctor` | Check the project follows VULCAN; exit 1 on any violation |
25
+ | `preset diff <package>` | Read-only: set each file the preset makes now against the file the package has (same, differs, missing); `--full` prints the diffs, `--check` exits 1 on a difference |
26
+ | `agents [list\|add\|remove\|setup]` | See, add, remove or re-choose the coding agents you use on this machine |
27
+ | `doctor` | Check the project follows VULCAN; exit 1 on any violation. The checks are listed in `docs/wiki/content/references/commands/doctor.md` |
28
+ | `commit-check <message-file> \| --range <revs> \| --text <message>` | Check a commit message against the `commit.message` checks of the config; `sync` installs it as the `commit-msg` hook; exit 1 on a problem, 2 on bad input |
29
+ | `board` | Fold the event log (and GitHub pull requests, checks and reviews when `gh` can read them) into flows and write one HTML file, by default `.agents/local/reports/board.html`; read-only |
30
+ | `ci affected --base <ref> \| template <github\|gitlab>` | List the workspace packages a change touches with the checks each has; `template` prints a CI file that runs exactly those |
31
+ | `event add \| tail` | Write a line to the agent event log (`.agents/local/events/<day>.jsonl`) or read it |
32
+ | `visualize <spec.json>` | Make one small static HTML page from a JSON spec, in `.agents/local/prototypes/` |
33
+ | `profile [show\|edit\|reset]` | Tell VULCAN how you like to work (reply language, tone, habits) in `.agents/local/profile.json` |
34
+ | `clean [--tmp\|--worktrees\|--clones\|--cache\|--all] [--yes]` | List what an agent left under `.agents/local/` (a dry run) and, with `--yes`, remove it |
35
+
24
36
  | `upgrade [--stable \| --nightly] [<version\|tag>]` | Install the target `@venizia/vulcan`, then run `sync` from the newly installed CLI. `--stable` (default) is the `latest` dist-tag, never a prerelease; `--nightly` is the higher of `latest` and `next`; a named version or tag wins over both. `--nightly` that cannot read the dist-tags exits 1; a stable upgrade from an installed prerelease says that `--nightly` keeps the prerelease line |
25
37
  | `x <tool> [args...]` | Run a shipped tool at the pinned version: `okf`, `atlas`. `x --help` prints the help; `x <tool> --help` goes to the tool |
26
38
  | `help`, `version` | |
27
39
 
28
- Diagnostics go to stderr; `vulcan` writes nothing to stdout of its own, so `vulcan x atlas mcp` is a
40
+ Diagnostics go to stderr; a command that produces a result prints only that on stdout, and `vulcan x atlas mcp` is a
29
41
  clean MCP stdio server.
30
42
 
31
43
  ## The project config
@@ -52,8 +64,8 @@ An unknown key is an error; every error names the file and the field.
52
64
 
53
65
  - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (51 rules).
54
66
  - `slots.json` - rules a project picks a wording for (V-W-01 today).
55
- - `skills/` - `knowledge-sync`, `docs-writing`, `docs-update`, `build-a-feature` (project-neutral; a project-specific skill stays in its project). Skill evals have not been run against a model: the skills pass the lint, and their output is a draft to review.
56
- - `hooks/` - `session-start.ts` (prints the rules digest) `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call) `guard-manifest.ts` (refuses a write to the generated `.agents/vulcan.manifest.json`) `guard-package.ts` (denies a hand-written new `package.json` in a layout folder when a recorded preset has a `vulcan add` command for it, else only warns) and `guard-remote-hosts.ts` (only for a config with `remoteHosts`: asks before a command reaches a host that is not listed; whole-name or `*` match, never substring).
67
+ - `skills/` - 12 project-neutral skills, described in `docs/wiki/content/references/skills.md` (a project-specific skill stays in its project). Skill evals have not been run against a model: the skills pass the lint, and their output is a draft to review.
68
+ - `hooks/` - 16 hook files, described in `docs/wiki/content/references/hooks/index.md`.
57
69
  - `claude/settings.json`, `make/vulcan.mk`, `templates/`.
58
70
 
59
71
  A project **extends** this: it adds rules with bare IDs (the base owns `V-`), skills, hooks and make targets, and never edits
@@ -61,14 +73,7 @@ or shadows a shipped one.
61
73
 
62
74
  ## `doctor` checks
63
75
 
64
- `config` (exactly one valid config) · `layout` (AGENTS.md, rules, knowledge bundle) · `rule-ids` (every
65
- `V-` ID a project rule points at - an `Extends` list or a first cell - is a base rule) · `rule-slots` (every slot chosen, valid option) · `skills` (no shipped skill
66
- shadowed) · `make` (includes `vulcan.mk`, no shipped target redefined) · `hooks` (shipped hooks are
67
- not re-registered) · `adapters` (sync is current, no hand-written `CLAUDE.md`, valid settings) ·
68
- `manifest` (`.agents/vulcan.manifest.json` exists and matches the config) · `tags` (every release tag `atlas.tagPattern` reads names a declared package, an alias or an ignored tag) ·
69
- `apps` (every `layout` folder is a workspace and every package lives in one; skipped without `layout`) ·
70
- `style` (`@venizia/dev-configs` declared by the package holding the lint config or the root, every lint config builds on it; the packages are `packages/*` and every configured package `path`) ·
71
- `scaffold` (the config is filled in: a project whose `package.json` declares `workspaces` lists its `packages`, and `.agents/knowledge/index.md` no longer holds the `vulcan:scaffold` line `init` writes).
76
+ `doctor` runs 26 checks; each is described in `docs/wiki/content/references/commands/doctor.md`.
72
77
 
73
78
  The session-start digest prints the base write boundaries, the slot choices, the project's own rules (bold `| **W-00** |` rows and `| V-W-02, V-W-03 |` rows that elaborate base rules), the project's `<!-- minimap-shape:start -->` ... `<!-- minimap-shape:end -->` block from `.agents/rules.md` verbatim, and the `digest.oftenDropped` rules.
74
79
 
@@ -10,9 +10,10 @@
10
10
  * is broken costs more than it protects. So input it cannot read passes, and so does a missing package or
11
11
  * `bun` (the settings wrapper says so on stderr). A guard that started and then failed - a crash or a
12
12
  * timeout, here an internal error or an unloadable module - ASKS instead of passing the call unchecked; a
13
- * project config that cannot be read leaves the default allowlist. `VULCAN_GUARDS=off` switches it off,
14
- * read before anything is imported. It imports only the modules it needs - the config loader (and zod) is
15
- * loaded on its own, last, and may fail alone.
13
+ * manifest that cannot be read leaves the default allowlist. `VULCAN_GUARDS=off` switches it off,
14
+ * read before anything is imported. It reads what the project set (`guard.outside`, `guard.toolOwnedPaths`)
15
+ * from the manifest `vulcan sync` wrote, never from the config: a config a newer release wrote, which this
16
+ * VULCAN cannot parse, then changes nothing here.
16
17
  */
17
18
 
18
19
  // A module, so the awaits below are top-level; it has no static import, by design.
@@ -33,20 +34,8 @@ try {
33
34
 
34
35
  if (input) {
35
36
  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
36
- let toolOwnedPaths: string[] = [];
37
- let outside: string = GuardDecisions.ASK;
38
-
39
- try {
40
- const { ConfigLoader } = await import('../../src/config/index.ts');
41
- const loaded = await ConfigLoader.load({ root: projectRoot });
42
-
43
- toolOwnedPaths = loaded.ok ? loaded.config.guard.toolOwnedPaths : [];
44
- outside = loaded.ok ? loaded.config.guard.outside : GuardDecisions.ASK;
45
- } catch (error) {
46
- console.error(
47
- `vulcan: the guard-outside hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - the default allowlist applies`,
48
- );
49
- }
37
+ const { ProjectGuards } = await import('../../src/hooks/project-guards.ts');
38
+ const { toolOwnedPaths, outside } = ProjectGuards.readPolicy({ root: projectRoot });
50
39
 
51
40
  const hits = OutsideGuard.inspect({ input, projectRoot, toolOwnedPaths });
52
41
 
@@ -4,7 +4,8 @@
4
4
  * The project's own deploy and migrate commands (`guard.writes.commands`) are read from the manifest and
5
5
  * checked beside the fixed list, inside compound commands too.
6
6
  * A script the project lists in `guard.writes.trustedScripts` is not read for writes while git says it
7
- * is tracked and unchanged; a config that cannot be read leaves the list empty, so every script is read.
7
+ * is tracked and unchanged. The list is read from the manifest, never from the config: a config this VULCAN cannot
8
+ * parse changes nothing here.
8
9
  * An entry of `guard.writes.readOnlyScripts` in the manifest (the object form of `trustedScripts`, written by
9
10
  * `vulcan sync`) skips that read for the calls whose first argument after the script is one of its words.
10
11
  *
@@ -22,35 +23,13 @@ try {
22
23
  const stdin = await Bun.stdin.text();
23
24
  const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
24
25
  const cwd = hookCommand?.cwd ?? process.cwd();
25
- let scripts: string[] = [];
26
-
27
- // Only a command that names a .ts file can use the list; the config loader (and zod) loads last, on its
28
- // own, and may fail alone.
29
- if (hookCommand && /\.ts\b/.test(hookCommand.command)) {
30
- try {
31
- const { ConfigLoader } = await import('../../src/config/index.ts');
32
- const loaded = await ConfigLoader.load({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
33
-
34
- // The objects are the read-only entries: the manifest carries them, so only the paths count here.
35
- scripts = loaded.ok
36
- ? loaded.config.guard.writes.trustedScripts.filter(
37
- (entry): entry is string => typeof entry === 'string',
38
- )
39
- : [];
40
- } catch (error) {
41
- console.error(
42
- `vulcan: the guard-writes hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - every script is read`,
43
- );
44
- }
45
- }
46
-
47
26
  const root = process.env.CLAUDE_PROJECT_DIR ?? cwd;
48
27
  const policy = ProjectGuards.readPolicy({ root });
49
28
  const hits = hookCommand
50
29
  ? WriteGuard.inspectCommand({
51
30
  command: hookCommand.command,
52
31
  cwd,
53
- trust: { root, scripts, readOnlyScripts: policy.readOnlyScripts },
32
+ trust: { root, scripts: policy.trustedScripts, readOnlyScripts: policy.readOnlyScripts },
54
33
  extra: policy.commands,
55
34
  })
56
35
  : [];
package/base/rules.md CHANGED
@@ -49,14 +49,14 @@ An ID the base drops is never reused.
49
49
  | V-P-10 | **Ask once, with a recommendation.** All open decisions in one numbered round, each with a recommended answer worded so that "yes" accepts it; never ask for a fact you can look up; for a reversible choice state the default in one line and continue, only inside what V-P-02, V-P-03 and V-W-06 already allow; stop for an action they reserve, a plan awaiting approval, a change of shape, or a real fork. | SOFT |
50
50
  | V-P-11 | **Reports: answer first, in the reader's form.** Two lines before any detail; evidence as a table, not prose; a long report goes in a file and the message carries the path. The reader decides the form: the owner gets the project's report shape in their own language, with labels and form of address taken from the `owner` config and their profile, never from fixed words; another agent (a session it started, a cross-session message, a subagent) gets the plain format it asked for and nothing more. | SOFT |
51
51
  | V-P-12 | **Delegate by kind; the brief carries the rules.** Mechanical work (sweeps, greps, renames, gates, counting) goes to a smaller-model subagent; judgment stays with the main agent, which re-checks what comes back. A subagent brief carries the goal, the files, read-only by default, "no git writes", the report shape and a size under 400 words, and the rules digest reaches the subagent (through the tool's subagent-start hook where one exists, otherwise in the brief); the template is `node_modules/@venizia/vulcan/base/references/delegation-brief.md`. | SOFT - the brief; a subagent-start hook where the tool has one |
52
- | V-P-13 | **Name the flow.** Only in a project that logs events (`events.log` on; without it the command writes a line nobody reads, so skip this rule). Work that belongs to a flow starts with the flow: run `vulcan event add --kind flow --title "<a title the owner reads>" --why "<one line, why it exists>" --context "<2-4 sentences: what this is, what is done, what is left>" --next "<the next step and who does it>"` with no `--flow`, in the owner's language. VULCAN gives the flow its id (`VULZ-<project.key>-<number>`) and prints it; use that id on every other line of the flow (`--flow <id>`, `Flow: <id>` in the first line of a message or in a pull request body, the branch name). Never type an id by hand or make one up: a `--flow` that no line of the log carries is refused. Give what is to be done and what must hold as lists, not prose: `--step "<text>"` for a step still to do and `--step-done "<text>"` for one done (the same for acceptance checks with `--check` and `--check-done`), `--app <name>` for each app or module it touches, `--due YYYY-MM-DD`, and `--ref <tracker id>`. To change a flow, run the same command with `--flow <id>`; the newest line wins as a whole, so repeat every list and field that still holds, the lists in the order you want them shown. Log `vulcan event add --kind deploy --flow <id> --summary "<what went live>"` when something is deployed. A board shows the title as the flow's heading, with the reason, context and next step under it; without a flow line it shows the words of its pull request or its first line, marked as having no title yet. | SOFT |
52
+ | V-P-13 | **Name the flow.** Only in a project that logs events (`events.log` on; without it the command writes a line nobody reads, so skip this rule). Work that belongs to a flow starts with the flow: run `vulcan event add --kind flow --title "<a title the owner reads>" --why "<one line, why it exists>" --context "<2-4 sentences: what this is, what is done, what is left>" --next "<the next step and who does it>"` with no `--flow`, in the owner's language. VULCAN gives the flow its id (`VULZ-<project.key>-<number>`) and prints it; use that id on every other line of the flow (`--flow <id>`, `Flow: <id>` in the first line of a message or in a pull request body, the branch name). Never type an id by hand or make one up: a `--flow` that no line of the log carries is refused. Give what is to be done and what must hold as lists, not prose: `--step "<text>"` for a step still to do and `--step-done "<text>"` for one done (the same for acceptance checks with `--check` and `--check-done`), `--app <name>` for each app or module it touches, `--due YYYY-MM-DD`, and `--ref <tracker id>`. To change a flow, run the same command with `--flow <id>`; the newest line wins as a whole, so repeat every list and field that still holds, the lists in the order you want them shown. Log `vulcan event add --kind deploy --flow <id> --summary "<what went live>"` when something is deployed. A board shows the title as the flow's heading, with the reason, context and next step under it; without a flow line it shows the words of its pull request or its first line. | SOFT |
53
53
 
54
54
  ## B - Build and quality
55
55
 
56
56
  | ID | Rule | Enforced by |
57
57
  |----|------|-------------|
58
58
  | V-B-01 | TDD: failing test first. | SOFT |
59
- | V-B-02 | The project's lint and test gates pass with zero warnings before "done". | SOFT - pre-commit runs `vulcan doctor` and lint |
59
+ | V-B-02 | The project's lint and test gates pass with zero warnings before "done". | SOFT - the project's own pre-commit, if it has one, runs `vulcan doctor` and lint |
60
60
  | V-B-03 | Run it, read real output, then claim. Evidence before assertions. | SOFT |
61
61
  | V-B-04 | Never green the suite by weakening it: no deleted/skipped tests, loosened asserts, relaxed strictness, `any`. Red test = information. | SOFT |
62
62
  | V-B-05 | **One script set for every app**, backend and frontend: `server:dev` (`NODE_ENV=development bun run src/index.ts` for a backend, `vite --config .configs/builders/vite.config.mts` for a frontend), `compile` (`bun .configs/builders/compile.ts` for a backend, `vite build --config .configs/builders/vite.config.mts` for a frontend), `typecheck` (`bun check`), `lint` (`devz lint`), `lint:fix` (`devz lint --fix`), `test` (`bun test`), `clean` (`devz clean`). The logic lives in `.configs/builders/` or in `devz`, never in the `package.json` string. No `dev`, `start`, `build`, `rebuild`, `preview` or `server:prod`. A domain extra such as `migrate:dev` is allowed on top. **An app root holds only `.configs/`, `src/`, `package.json`, `tsconfig.json` and `.env.example`**; every other config lives in `.configs/{lints,formatters,builders}/`. A library package keeps Makefile targets instead: `build`, `typecheck`, `lint`, `lint-fix`, `test`, `clean`. | SOFT - `vulcan doctor` notes an app that lacks one or carries a legacy name (info, never a failure) |
@@ -75,7 +75,7 @@ An ID the base drops is never reused.
75
75
  | V-C-06 | **Never a silent catch - log it.** Always braces. Early return. `switch` with `default` over a long if-else chain. Strict TypeScript; no `any` where a type exists. | LINT (braces, floating promises) + SOFT |
76
76
  | V-C-07 | **A function name opens with its verb** - `generate` `build` `to` `is` `has` `assert` `extract` `enrich` `get` `resolve`. `is*` returns a boolean and leaves the branch to the caller; `assert*` throws and returns `void`, so the code after it needs none - reach for `assert*` when every caller would throw on `false` anyway. `has*` is the ownership question (`hasBucket`, never `isBucketExists`). That list is for UTILITY functions; service methods lean on a wider set. **Arrow functions, not `function` declarations** (do not churn existing ones). State plus the operations on it live in a class with static members - the `LoggerFactory` shape - never module-level `let` plus exported arrows. | SOFT |
77
77
  | V-C-08 | **Enumerable strings are a const class plus `TConstValue`,** never a raw string-literal union. When something validates against such a class, it carries `static readonly SCHEME_SET = new Set([...])` over its values and `static isValid(value: string): boolean` reading it, so a runtime check exists wherever a value crosses a boundary (`IsolationLevels` in connectors is the model; a subclass redeclares `SCHEME_SET` with `...Parent.SCHEME_SET` first); a class nothing validates against needs neither. The `T`/`I` prefix follows the declaration keyword: `type` gets `T`, `interface` gets `I`; an interface turned into a type alias is renamed, and no tool catches it - grep both directions. | SOFT |
78
- | V-C-09 | **Comments state only a lasting fact the code cannot show** - a constraint, an external contract, a non-obvious invariant; one to three lines; no history, no dates, no decision or review notes, no restating the code. An exported declaration may carry a short JSDoc: one summary line, `@param`/`@returns` without `{type}`. Machine directives stay. The one other exception is the `// SHORTCUT:` marker of V-B-07. Most code needs none; remove a meaningless comment in the lines you touch. | SOFT |
78
+ | V-C-09 | **Comments state only a lasting fact the code cannot show** - a constraint, an external contract, a non-obvious invariant; one to three lines; no history, no dates, no decision or review notes, no restating the code. An exported declaration carries TSDoc: plain markdown, a summary first, `@param`/`@returns` without `{type}`, `@default` for a default, `@deprecated` with what replaces it, `@example` when use is not obvious; it sits on the declaration itself (a destructured export has nowhere for it), and it is read by people and agents from the generated reference. TSDoc is exempt from the three-line limit. Machine directives stay. The one other exception is the `// SHORTCUT:` marker of V-B-07. Most code needs none; remove a meaningless comment in the lines you touch. | SOFT |
79
79
  | V-C-10 | **No explicit cast in new code.** `as X`, `as any`, `as unknown as X` and `as never` assert nothing; they silence the compiler where the type is wrong. Fix the type instead: a generic on the setter, a narrower parameter, a typed helper, `satisfies`. A pre-existing cast is removed when the line is touched, never copied. Generic parameters are full words (`ApplicationType`, `TDocument`), never `App` or `TDoc` (V-C-04). | SOFT |
80
80
  | V-C-11 | **SIMPLE FIRST, in code and in prose.** Fewest concepts, plainest words, smallest surface. Complexity must buy correctness, speed or safety the simple version cannot, and the artifact says what it bought. Something a reader cannot follow in one pass is a defect even when it works. Fix the root cause with the smallest change; never layer an abstraction on a misdiagnosed problem. Small means the code holds only what the task needs - not golfed: no clever one-liners to save lines, and no code for a need nobody has yet. | SOFT |
81
81
  | V-C-12 | **Consistent, never self-invented.** Before writing anything new - a constant, file, binding key, error shape - find the nearest precedent in this repo and copy its shape. Binding keys are namespaced (`controllers.X`, `services.X`, `repositories.X`, `datasources.X`). Every scope is one folder with nested `common/{types,constants}.ts` and an index barrel (`inversion` is the model). A second style for something that already has one is a defect. | SOFT |
@@ -78,7 +78,7 @@ The rules that make a page worth opening:
78
78
  Vietnamese words are bundled; `language` in the spec overrides it). For any other language, translate the
79
79
  words you need into `chrome` (every key is optional); never invent a label set the owner did not give.
80
80
  - **The colour is the project's, not yours**: leave `accent` out. The page uses the project's `theme` (config key,
81
- written into the manifest by `vulcan sync`), else a neutral slate. Give `accent` (and `accentDark`, `accentText`)
81
+ written into the manifest by `vulcan sync`), else the `venizia` preset. Give `accent` (and `accentDark`, `accentText`)
82
82
  only when you draw a page about another project from outside it. A colour that fails the contrast checks is
83
83
  refused, never swapped; state colours (done, waiting, blocked) are fixed and always carry an icon and a word.
84
84
  - **Say where a claim comes from.** A box or step that states how the code works carries a `source`
@@ -39,7 +39,7 @@ Space, Home, End and Escape, one section per slide; print gives one section afte
39
39
  | `schemaVersion` | `1` |
40
40
  | `title` | The takeaway, at most 120 characters |
41
41
  | `language` | A language code (`en`, `pt-BR`); default: the reply language of the owner's profile, else `en`. The page's own words are bundled for `en` and `vi` (a regional code such as `vi-VN` picks `vi`); any other language takes its words from `chrome` |
42
- | `accent`, `accentDark`, `accentText` | Optional six-digit hex colours that override the project's page colour (the `theme` config key, written into the manifest by `vulcan sync`; without one, a neutral slate). Give them only for a page about another project. A colour that fails the contrast checks (text 4.5:1, marks 3:1) is refused, never swapped; with no `accentDark` it is derived by mixing toward white |
42
+ | `accent`, `accentDark`, `accentText` | Optional six-digit hex colours that override the project's page colour (the `theme` config key, written into the manifest by `vulcan sync`; without one, the `venizia` preset). Give them only for a page about another project. A colour that fails the contrast checks (text 4.5:1, marks 3:1) is refused, never swapped; with no `accentDark` it is derived by mixing toward white |
43
43
  | `status` | `{ state: ok \| warn \| blocked \| info, label? }`; the banner's colour, icon and word |
44
44
  | `asOf`, `scope` | An ISO date, and a sentence on what the page covers |
45
45
  | `verdict`, `caption` | One sentence the reader can stop at; one line under it |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.10-2",
3
+ "version": "0.4.10-3",
4
4
  "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
6
6
  "bugs": {
@@ -45,8 +45,8 @@
45
45
  },
46
46
  "dependencies": {
47
47
  "@clack/prompts": "1.8.1",
48
- "@venizia/vulcan-atlas": "0.4.10-2",
49
- "@venizia/vulcan-okf": "0.4.10-2",
48
+ "@venizia/vulcan-atlas": "0.4.10-3",
49
+ "@venizia/vulcan-okf": "0.4.10-3",
50
50
  "zod": "^4.6.7"
51
51
  },
52
52
  "devDependencies": {
@@ -7,6 +7,7 @@ export const NO_TTY_HINT = `vulcan sync: no agents chosen on this machine - wrot
7
7
 
8
8
  type TParsed = { ok: true; agents: string[] } | { ok: false; error: string };
9
9
 
10
+ /** Parses and resolves the list of agent tools a project targets, from the flag, the config or a prompt; used by `vulcan agents`, `vulcan sync` and `vulcan doctor`. */
10
11
  export class AgentSelection {
11
12
  private static fromList(opts: {
12
13
  value: string;
@@ -60,7 +60,7 @@ export type IBoardItem = IEventItem;
60
60
  export interface IBoardFlow {
61
61
  id: string;
62
62
  title: string;
63
- /** The title came from a `flow` line; a flow without one shows its first line and "no title yet". */
63
+ /** The title came from a `flow` line; a flow without one shows the words of its pull request or its first line, with no marker. */
64
64
  named: boolean;
65
65
  /** Why the flow exists, from the newest `flow` line that has one. */
66
66
  why?: string;
@@ -119,7 +119,7 @@ export interface IBoardData {
119
119
  shapes: Record<string, string>;
120
120
  /** The `board.agents` keys with no lane; absent when none is listed, and then every agent shows. */
121
121
  roster?: string[];
122
- /** A helper to the lane it rolls into. */
122
+ /** A helper to the listed name it works under; shown as a label on its own card. */
123
123
  lanes?: Record<string, string>;
124
124
  /** What `board.agents` says an agent is, by name: `Backend`. */
125
125
  roles?: Record<string, string>;
@@ -6,12 +6,15 @@ const SHAPE = z.custom<string>((value) => typeof value === 'string' && BoardShap
6
6
  message: `one of ${[...BoardShapes.SCHEME_SET].join(', ')}`,
7
7
  });
8
8
 
9
- /** A face, or `{ shape?, lane?, role? }`: the lane rolls the agent into the row of another listed agent; the role is what the card says it is. */
9
+ /** A face, or `{ shape?, lane?, role? }`: the lane labels the agent "under" another listed agent on its own card; the role is what the card says it is. */
10
10
  export const BOARD_AGENT = z.union([
11
11
  SHAPE,
12
12
  z.strictObject({
13
+ /** Face of the agent: `bun`, `flame`, `ember`, `rock` or `banana`. */
13
14
  shape: SHAPE.optional(),
15
+ /** Name of another listed agent this one is shown under on its card; at least one character, and that agent has no lane of its own. */
14
16
  lane: z.string().min(1).optional(),
17
+ /** What the card says the agent is; trimmed, 1 to 60 characters. */
15
18
  role: z.string().trim().min(1).max(BoardConstants.ROLE_MAX).optional(),
16
19
  }),
17
20
  ]);
@@ -17,7 +17,7 @@ export interface IBoardSettings {
17
17
  hostname: string;
18
18
  /** The listed `board.agents` keys with no lane; empty when none is listed, and then every agent shows. */
19
19
  roster: string[];
20
- /** A helper to the lane it rolls into. */
20
+ /** A helper to the listed name it works under; shown as a label on its own card. */
21
21
  lanes: Record<string, string>;
22
22
  /** What `board.agents` says each agent is. */
23
23
  roles: Record<string, string>;
@@ -1,69 +1,8 @@
1
1
  import { ExitCodes, VULCAN_VERSION } from '../common/index.ts';
2
-
3
- const HELP = `vulcan ${VULCAN_VERSION} - one setup, one workflow for every project
4
-
5
- Usage: bun x vulcan <command>
6
-
7
- init [--key <KEY>] Scaffold the project layer (never overwrites); --key is the project's flow key
8
- (2 to 8 uppercase letters or digits; a terminal asks, else it is made from the name)
9
- init --preset <name|file:path> --project <name> --app <name> [--backend-dir|--frontend-dir <path>]
10
- [--shared-dir <path>] [--scope <@scope>] [--key <KEY>]
11
- Create a monorepo with its first app, from a framework preset
12
- (a name missing from the flags is asked in a terminal)
13
- add --preset <name|file:path> (--app <name> | --lib <name> | --shared <name>) [--dir <folder>]
14
- [--scope <@scope>] [--backend-dir|--frontend-dir <path>] [--api <app> | --no-api]
15
- Add an app, a library other apps import (--lib) or a side-neutral package
16
- other apps import (--shared) to the monorepo (a frontend says which
17
- backend to proxy to; --dir is for a library or a shared package;
18
- --scope names the package @scope/<name>; a terminal asks for the kind
19
- and every name the flags leave out)
20
- preset diff <package> [--preset <name|file:path>] [--api <app> | --no-api] [--full] [--check]
21
- Read-only: set each file the preset makes now (for an app, a library or
22
- a shared package) against the file the package has (same, differs,
23
- missing); --full prints the unified diffs, --check exits 1 when
24
- anything differs or is missing
25
- sync [--agents <list>|list] [--dry-run]
26
- Write the adapters of the agents you chose (--agents claude,omp or none,
27
- stored in .agents/vulcan.local.json; --agents list shows the table)
28
- agents [list|add <ids>|remove <ids>|setup] [--dry-run]
29
- See, add, remove or re-choose the coding agents you use on this machine
30
- doctor Check the project follows VULCAN; exit 1 on any violation
31
- commit-check <message-file> | --range <revs> | --text <message>
32
- Check a commit message against the commit.message checks of the config (an
33
- agent in a trailer or a "generated with" line, the project's subject shape);
34
- sync installs it as the commit-msg hook; exit 1 on a problem, 2 on bad input
35
- board [--out <file>] [--open] [--since <date>] [--dir <events folder>] [--repo owner/name]... [--no-github]
36
- Fold the event log (and GitHub pull requests, checks and reviews when gh
37
- can read them) into flows and write one HTML file, by default
38
- .agents/local/reports/board.html; read-only; exit 2 on bad input
39
- ci affected --base <ref> [--head <ref>] [--check <check>] [--json | --names] | template <github|gitlab>
40
- List the workspace packages a change touches (changed ones and what
41
- depends on them) with the checks each has; template prints a CI file that
42
- runs exactly those; exit 2 on bad input
43
- event add --kind <k> --summary <text> [--flow <flow id>] [--ref <r>] [--status approve|park|reject] | add --kind flow [--flow <flow id>] --title <text> [--why <text>] [--context <text>] [--next <text>] [--step|--step-done <text>]... [--check|--check-done <text>]... [--app <name>]... [--due YYYY-MM-DD] | tail [--since <time>] [--json] [--dir <folder>]
44
- Write a line to the agent event log (.agents/local/events/<day>.jsonl) or
45
- read it; with events.log on, sync installs the Claude Code hooks that
46
- write it; exit 2 on bad input
47
- visualize <spec.json> [--out <name>] | --schema
48
- Make one small static HTML page (a flow, a status, a before and after) from
49
- a JSON spec, in .agents/local/prototypes/; --schema prints the spec's schema
50
- profile [show|edit|reset [--yes]]
51
- Tell VULCAN how you like to work (reply language, how to address you,
52
- tone, habits) in .agents/local/profile.json; no argument runs the form,
53
- show prints it, reset deletes it
54
- clean [--tmp|--worktrees|--clones|--cache|--all] [--reports|--prototypes|--events|--release-candidates|--profile] [--yes]
55
- List what an agent left under .agents/local/ (a dry run) and, with
56
- --yes, remove it; --tmp is the default, --worktrees takes merged or
57
- gone branches only, --all never touches reports, prototypes, events, release candidates or the profile
58
- upgrade [--stable | --nightly] [<version|tag>]
59
- Bump the pinned @venizia/vulcan, then sync; --stable (default)
60
- takes the latest tag, --nightly the newest of latest and next
61
- x <tool> [args...] Run a shipped tool at the pinned version: okf, atlas
62
- help · version
63
- `;
2
+ import { CommandTable } from './table.ts';
64
3
 
65
4
  export const runHelpCommand = async (): Promise<number> => {
66
- process.stdout.write(HELP);
5
+ process.stdout.write(CommandTable.helpText());
67
6
 
68
7
  return ExitCodes.OK;
69
8
  };