@venizia/vulcan 0.4.9-2 → 0.4.9-4

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 (73) hide show
  1. package/README.md +5 -6
  2. package/base/claude/commit-attribution.json +7 -0
  3. package/base/commit-agents.json +41 -0
  4. package/base/make/vulcan.mk +1 -11
  5. package/base/rules.md +3 -8
  6. package/package.json +3 -3
  7. package/src/agents/atlas-block.ts +2 -2
  8. package/src/agents/common/constants.ts +1 -21
  9. package/src/agents/exclude.ts +2 -2
  10. package/src/agents/render.ts +2 -2
  11. package/src/agents/resolve.ts +1 -16
  12. package/src/commands/agents.command.ts +1 -1
  13. package/src/commands/commit-check.command.ts +5 -0
  14. package/src/commands/help.command.ts +7 -4
  15. package/src/commands/index.ts +25 -27
  16. package/src/commands/init.command.ts +2 -15
  17. package/src/commands/sync.command.ts +2 -5
  18. package/src/commands/x.command.ts +1 -1
  19. package/src/commit/agents.ts +32 -0
  20. package/src/commit/check.ts +160 -0
  21. package/src/commit/common/constants.ts +28 -0
  22. package/src/commit/common/index.ts +2 -0
  23. package/src/commit/common/types.ts +57 -0
  24. package/src/commit/hook.ts +187 -0
  25. package/src/commit/index.ts +8 -0
  26. package/src/commit/message.ts +74 -0
  27. package/src/commit/policy.ts +110 -0
  28. package/src/commit/signature.ts +94 -0
  29. package/src/commit/subject.ts +40 -0
  30. package/src/common/constants.ts +3 -22
  31. package/src/common/layout-folder.ts +1 -5
  32. package/src/common/types.ts +0 -5
  33. package/src/config/common/constants.ts +2 -23
  34. package/src/config/common/types.ts +1 -10
  35. package/src/config/loader.ts +15 -16
  36. package/src/config/schema.ts +69 -21
  37. package/src/create/add-app.ts +2 -10
  38. package/src/create/add-lib.ts +1 -8
  39. package/src/create/common/constants.ts +0 -14
  40. package/src/create/common/types.ts +1 -2
  41. package/src/create/preset.ts +0 -12
  42. package/src/create/workspace.ts +5 -5
  43. package/src/doctor/checks.ts +68 -85
  44. package/src/doctor/common/constants.ts +3 -33
  45. package/src/doctor/runner.ts +1 -1
  46. package/src/doctor/tags.ts +4 -5
  47. package/src/hooks/codex-patch.ts +0 -6
  48. package/src/hooks/common/constants.ts +0 -24
  49. package/src/hooks/guard-manifest.ts +1 -1
  50. package/src/hooks/subagent-card.ts +1 -4
  51. package/src/init/common/constants.ts +0 -11
  52. package/src/init/scaffold.ts +8 -16
  53. package/src/manifest/render.ts +25 -25
  54. package/src/owner/constants.ts +0 -4
  55. package/src/owner/violations.ts +1 -15
  56. package/src/router.ts +24 -9
  57. package/src/rules/base.ts +0 -4
  58. package/src/rules/parser.ts +0 -10
  59. package/src/sync/base-rules.ts +1 -2
  60. package/src/sync/common/constants.ts +1 -18
  61. package/src/sync/common/types.ts +1 -1
  62. package/src/sync/index.ts +0 -1
  63. package/src/sync/planner.ts +12 -18
  64. package/src/sync/settings.ts +0 -9
  65. package/src/visualize/assets.ts +1 -1
  66. package/src/visualize/compare-schema.ts +0 -4
  67. package/src/visualize/constants.ts +0 -24
  68. package/src/visualize/kinds-schema.ts +0 -8
  69. package/src/wiki/constants.ts +0 -4
  70. package/base/templates/vulcan.config.js +0 -5
  71. package/base/templates/vulcan.config.mjs +0 -5
  72. package/base/templates/vulcan.config.ts +0 -6
  73. package/src/sync/prune.ts +0 -142
package/README.md CHANGED
@@ -16,10 +16,10 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
16
16
 
17
17
  | Command | What it does |
18
18
  |---|---|
19
- | `init [--config ts\|mts\|mjs\|js]` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.*`, 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 |
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 |
20
20
  | `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
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 |
22
- | `sync [--dry-run] [--prune]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`; the one `bun init` writes is replaced, any other hand-written 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. `--prune` also removes what sync proves stale and did not write: an old VULCAN or plugin-era hook command (a shipped hook exactly as an older VULCAN released it, or a `.agents/` hook whose file is gone) and a dead `.claude/skills` link - never a developer's own hook, a customised shipped command, a real directory or a symlinked `.claude/skills`. `--dry-run` writes nothing and labels each line `would create`, `would replace` or `would remove`. Idempotent |
22
+ | `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
23
  | `doctor` | Check the project follows VULCAN; exit 1 on any violation |
24
24
  | `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
25
  | `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 |
@@ -30,7 +30,7 @@ clean MCP stdio server.
30
30
 
31
31
  ## The project config
32
32
 
33
- `.configs/vulcan.config.<ext>`, `<ext>` one of `mts` (what `init` writes), `ts`, `mjs`, `js` (exactly one):
33
+ `.configs/vulcan.config.mts`:
34
34
 
35
35
  ```ts
36
36
  import type { VulcanConfig } from '@venizia/vulcan';
@@ -50,7 +50,7 @@ An unknown key is an error; every error names the file and the field.
50
50
 
51
51
  ## What ships (`base/`)
52
52
 
53
- - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (50 rules; it lists V-W-05, V-C-03 and V-C-05 as retired).
53
+ - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (50 rules).
54
54
  - `slots.json` - rules a project picks a wording for (V-W-01 today).
55
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
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).
@@ -62,11 +62,10 @@ or shadows a shipped one.
62
62
  ## `doctor` checks
63
63
 
64
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, not a retired one) · `rule-slots` (every slot chosen, valid option) · `skills` (no shipped skill
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
66
  shadowed) · `make` (includes `vulcan.mk`, no shipped target redefined) · `hooks` (shipped hooks are
67
67
  not re-registered) · `adapters` (sync is current, no hand-written `CLAUDE.md`, valid settings) ·
68
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
- `prune` (no stale hook command or dead skill link - `sync --prune` removes them) ·
70
69
  `apps` (every `layout` folder is a workspace and every package lives in one; skipped without `layout`) ·
71
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`) ·
72
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).
@@ -0,0 +1,7 @@
1
+ {
2
+ "attribution": {
3
+ "commit": "",
4
+ "pr": "",
5
+ "sessionUrl": false
6
+ }
7
+ }
@@ -0,0 +1,41 @@
1
+ {
2
+ "products": [
3
+ "claude code",
4
+ "claude opus",
5
+ "claude sonnet",
6
+ "claude haiku",
7
+ "claude agent",
8
+ "chatgpt",
9
+ "gpt",
10
+ "openai codex",
11
+ "codex",
12
+ "github copilot",
13
+ "copilot",
14
+ "cursor agent",
15
+ "gemini code assist",
16
+ "gemini cli",
17
+ "google gemini"
18
+ ],
19
+ "mentions": [
20
+ "claude",
21
+ "anthropic",
22
+ "codex",
23
+ "openai",
24
+ "chatgpt",
25
+ "gpt",
26
+ "gemini",
27
+ "copilot",
28
+ "cursor"
29
+ ],
30
+ "addressNames": [
31
+ "claude",
32
+ "codex",
33
+ "copilot",
34
+ "chatgpt",
35
+ "cursoragent",
36
+ "gemini-code-assist[bot]"
37
+ ],
38
+ "addressDomains": ["anthropic.com", "openai.com", "google.com", "cursor.com", "github.com"],
39
+ "noreplyDomains": ["anthropic.com", "openai.com", "google.com"],
40
+ "generatedPhrases": ["generated with", "generated by"]
41
+ }
@@ -8,8 +8,7 @@ VULCAN_BASE ?= node_modules/@venizia/vulcan/base
8
8
  WIKI_REPO ?=
9
9
 
10
10
  .PHONY: vulcan-sync vulcan-doctor okf-check okf-check-strict okf-gen okf-coverage okf-viz \
11
- surface-gen surface-check atlas-symbols atlas-releases changelogs-migrate \
12
- knowledge-symbols-check wiki-links-check wiki-anchors-check
11
+ surface-gen surface-check atlas-symbols atlas-releases wiki-links-check wiki-anchors-check
13
12
 
14
13
  vulcan-sync: ## Write the agent adapters, settings, skill links and manifest from the config
15
14
  @$(VULCAN) sync
@@ -51,15 +50,6 @@ atlas-symbols: ## Print the symbols atlas reads from the built or installed .d.t
51
50
  atlas-releases: ## Print the release table atlas computes from the tags
52
51
  @$(VULCAN) x atlas releases
53
52
 
54
- # Writes the packages: list into every changelog entry that declares none - once, then review it.
55
- changelogs-migrate: ## Write the packages: list into changelog entries that declare none
56
- @$(VULCAN) x atlas changelogs migrate
57
-
58
- # A concept may name code (`symbols:` in its frontmatter); this fails when a named symbol is gone or its
59
- # signature changed since `vulcan x atlas concepts stamp`. It reads the built .d.ts - run it after build.
60
- knowledge-symbols-check: ## Fail when a symbol a concept names is gone or its signature changed
61
- @$(VULCAN) x atlas concepts check
62
-
63
53
  # The wiki link gates. Set WIKI_REPO (owner/name) in the project's Makefile before the include. Flags go in
64
54
  # WIKI_LINKS_FLAGS (--dirs, --skip-prose, --skip) and WIKI_ANCHORS_FLAGS (--content, --dist).
65
55
  wiki-links-check: ## Fail when the wiki or the knowledge bundle names a source path git does not track
package/base/rules.md CHANGED
@@ -1,20 +1,15 @@
1
1
  # Rules - VULCAN base
2
2
 
3
3
  <!-- Shipped by @venizia/vulcan. Never edit in a project: add extensions in .agents/rules.md.
4
- W, S, P, B are INTERIM until the base-rules work reconciles the rules the projects share.
5
4
  C is the shared coding style, shipped to every project; a rule that binds one project's own stack
6
5
  lives in that project. -->
7
6
 
8
7
  Cite by ID. Every rule has "Enforced by". Base IDs carry the `V-` namespace (`V-W-01`, `V-C-04`).
9
8
  A project extends this set in its own `.agents/rules.md` with bare IDs (`W-06`, `C-19`), which can
10
9
  never collide with a base ID. A `V-` ID there points at a base rule (`Extends V-W-01`); `vulcan doctor`
11
- fails one the base does not carry or has retired.
10
+ fails one the base does not carry.
12
11
 
13
- Retired IDs are never reused (2026-10-17):
14
-
15
- - `V-W-05` - the task-manager loop
16
- - `V-C-03` - `@inject` on container-built classes, moved to the project whose stack it binds
17
- - `V-C-05` - `getError` / `ApplicationError`, moved to the project whose stack it binds, with the hard stack once in `V-C-18`
12
+ An ID the base drops is never reused.
18
13
 
19
14
  ## W - Write boundaries
20
15
 
@@ -78,7 +73,7 @@ Retired IDs are never reused (2026-10-17):
78
73
  | V-C-04 | **Never abbreviate identifiers:** `ProductRepository` not `ProductRepo`, `ProductDocument` not `ProductDoc`; type parameters too (`TDocument`, not `TDoc`). A project lists its own exceptions in its rules (for example `tz` for a time zone). | SOFT |
79
74
  | 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 |
80
75
  | 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 |
81
- | V-C-08 | **Enumerable strings are a const class plus `TConstValue`,** never a raw string-literal union. Every such class 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). 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 |
76
+ | 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 |
82
77
  | V-C-09 | **Comments state only a constraint the code cannot show** - one to three lines; no history, no dates, no decision notes, no restating the code - the one exception is the `// SHORTCUT:` marker of V-B-07. Most code needs none. | SOFT |
83
78
  | 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 |
84
79
  | 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 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.9-2",
3
+ "version": "0.4.9-4",
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": {
@@ -44,8 +44,8 @@
44
44
  },
45
45
  "dependencies": {
46
46
  "@clack/prompts": "1.8.1",
47
- "@venizia/vulcan-atlas": "0.4.9-2",
48
- "@venizia/vulcan-okf": "0.4.9-2",
47
+ "@venizia/vulcan-atlas": "0.4.9-4",
48
+ "@venizia/vulcan-okf": "0.4.9-4",
49
49
  "zod": "^4.6.7"
50
50
  },
51
51
  "devDependencies": {
@@ -1,6 +1,6 @@
1
- export const ATLAS_BLOCK_START =
1
+ const ATLAS_BLOCK_START =
2
2
  '<!-- vulcan:atlas:start - generated by vulcan sync from .configs/vulcan.config.*; do not edit -->';
3
- export const ATLAS_BLOCK_END = '<!-- vulcan:atlas:end -->';
3
+ const ATLAS_BLOCK_END = '<!-- vulcan:atlas:end -->';
4
4
  const START_PREFIX = '<!-- vulcan:atlas:start';
5
5
  const MUST_READ = '## Must read first';
6
6
 
@@ -10,39 +10,19 @@ export class AgentScopes {
10
10
  }
11
11
  }
12
12
 
13
- /** Why an agent's list was chosen: a flag, the local file, the config, a migration, the question, or the default. */
13
+ /** Why an agent's list was chosen: a flag, the local file, the config, the question, or the default. */
14
14
  export class AgentSources {
15
15
  static readonly FLAG = 'flag';
16
16
  static readonly LOCAL = 'local';
17
17
  static readonly CONFIG = 'config';
18
- static readonly MIGRATION = 'migration';
19
18
  static readonly ASKED = 'asked';
20
19
  static readonly DEFAULT = 'default';
21
-
22
- static readonly SCHEME_SET = new Set<string>([
23
- this.FLAG,
24
- this.LOCAL,
25
- this.CONFIG,
26
- this.MIGRATION,
27
- this.ASKED,
28
- this.DEFAULT,
29
- ]);
30
-
31
- static isValid(value: string): boolean {
32
- return this.SCHEME_SET.has(value);
33
- }
34
20
  }
35
21
 
36
22
  /** What taking an entry out of an agent's file found: it was not there, or it was and is gone. */
37
23
  export class RemoveOutcomes {
38
24
  static readonly ABSENT = 'absent';
39
25
  static readonly REMOVED = 'removed';
40
-
41
- static readonly SCHEME_SET = new Set<string>([this.ABSENT, this.REMOVED]);
42
-
43
- static isValid(value: string): boolean {
44
- return this.SCHEME_SET.has(value);
45
- }
46
26
  }
47
27
 
48
28
  /** How a guard reaches an agent that has no Claude-style hook commands: a file the agent loads. */
@@ -2,9 +2,9 @@ import { AgentConstants, AgentScopes } from './common/index.ts';
2
2
  import { LOCAL_AGENTS_FILE } from './local.ts';
3
3
  import { AgentTable } from './table.ts';
4
4
 
5
- export const EXCLUDE_BLOCK_START =
5
+ const EXCLUDE_BLOCK_START =
6
6
  '# vulcan:start - written by vulcan sync for the agents you chose; do not edit';
7
- export const EXCLUDE_BLOCK_END = '# vulcan:end';
7
+ const EXCLUDE_BLOCK_END = '# vulcan:end';
8
8
  const START_PREFIX = '# vulcan:start';
9
9
  /** A block's start line: the project it belongs to sits in brackets after the marker, none for the git top level. */
10
10
  const START_PATTERN = /^# vulcan:start(?: \((.*)\))? - written/;
@@ -2,8 +2,8 @@ import { join } from 'node:path';
2
2
  import { RecordValue } from '../common/record.ts';
3
3
  import { RemoveOutcomes } from './common/index.ts';
4
4
 
5
- export const CODEX_BLOCK_START = '# vulcan:atlas:start';
6
- export const CODEX_BLOCK_END = '# vulcan:atlas:end';
5
+ const CODEX_BLOCK_START = '# vulcan:atlas:start';
6
+ const CODEX_BLOCK_END = '# vulcan:atlas:end';
7
7
  const CODEX_TABLE = '[mcp_servers.atlas]';
8
8
  const SERVER_NAME = 'atlas';
9
9
 
@@ -1,12 +1,8 @@
1
- import { existsSync } from 'node:fs';
2
- import { join } from 'node:path';
3
1
  import { AgentConstants, AgentSources } from './common/index.ts';
4
2
  import type { TAgentResolution, TAskAgents } from './common/index.ts';
5
3
  import { LocalChoice } from './local.ts';
6
4
  import { AgentTable } from './table.ts';
7
5
 
8
- const PROJECT_FILES = ['CLAUDE.md', '.claude'];
9
-
10
6
  export const NO_TTY_HINT = `vulcan sync: no agents chosen on this machine - wrote the Claude files as before; to choose, run: vulcan sync ${AgentConstants.FLAG} ${AgentConstants.EXAMPLE_LIST} (or ${AgentConstants.NONE})`;
11
7
 
12
8
  type TParsed = { ok: true; agents: string[] } | { ok: false; error: string };
@@ -54,8 +50,7 @@ export class AgentSelection {
54
50
 
55
51
  /**
56
52
  * Which agents this machine uses, in order: the flag, the stored choice, the committed config's
57
- * suggestion, a project that already has Claude files, then ask (terminal) or keep today's Claude
58
- * default (no terminal, with a hint and nothing stored).
53
+ * suggestion, then ask (terminal) or the Claude default (no terminal, with a hint and nothing stored).
59
54
  */
60
55
  static resolve(opts: {
61
56
  root: string;
@@ -127,16 +122,6 @@ export class AgentSelection {
127
122
  };
128
123
  }
129
124
 
130
- if (PROJECT_FILES.some((file) => existsSync(join(opts.root, file)))) {
131
- return {
132
- ok: true,
133
- agents: ['claude'],
134
- source: AgentSources.MIGRATION,
135
- writeLocal: true,
136
- hint: undefined,
137
- };
138
- }
139
-
140
125
  if (opts.interactive) {
141
126
  return askNow();
142
127
  }
@@ -21,7 +21,7 @@ const detected = (opts: { root: string }): string[] =>
21
21
  path: process.env.PATH ?? '',
22
22
  });
23
23
 
24
- /** What this machine uses now: the stored choice, the migration or the config's suggestion; nothing when it never chose. */
24
+ /** What this machine uses now: the stored choice or the config's suggestion; nothing when it never chose. */
25
25
  const currentAgents = async (opts: {
26
26
  root: string;
27
27
  }): Promise<{ ok: true; agents: string[]; chosen: boolean } | { ok: false; error: string }> => {
@@ -0,0 +1,5 @@
1
+ import type { ICommandContext } from '../common/index.ts';
2
+ import { CommitCheck } from '../commit/index.ts';
3
+
4
+ export const runCommitCheckCommand = async (opts: ICommandContext): Promise<number> =>
5
+ CommitCheck.run(opts);
@@ -4,7 +4,7 @@ const HELP = `vulcan ${VULCAN_VERSION} - one setup, one workflow for every proje
4
4
 
5
5
  Usage: bun x vulcan <command>
6
6
 
7
- init [--config ts|mts|mjs|js] Scaffold the project layer (never overwrites)
7
+ init Scaffold the project layer (never overwrites)
8
8
  init --preset <name|file:path> --project <name> --app <name> [--backend-dir|--frontend-dir <path>]
9
9
  [--shared-dir <path>] [--scope <@scope>]
10
10
  Create a monorepo with its first app, from a framework preset
@@ -21,13 +21,16 @@ Usage: bun x vulcan <command>
21
21
  a shared package) against the file the package has (same, differs,
22
22
  missing); --full prints the unified diffs, --check exits 1 when
23
23
  anything differs or is missing
24
- sync [--agents <list>|list] [--dry-run] [--prune]
24
+ sync [--agents <list>|list] [--dry-run]
25
25
  Write the adapters of the agents you chose (--agents claude,omp or none,
26
- stored in .agents/vulcan.local.json; --agents list shows the table);
27
- --prune also removes stale hooks and dead skill links
26
+ stored in .agents/vulcan.local.json; --agents list shows the table)
28
27
  agents [list|add <ids>|remove <ids>|setup] [--dry-run]
29
28
  See, add, remove or re-choose the coding agents you use on this machine
30
29
  doctor Check the project follows VULCAN; exit 1 on any violation
30
+ commit-check <message-file> | --range <revs> | --text <message>
31
+ Check a commit message against the commit.message checks of the config (an
32
+ agent in a trailer or a "generated with" line, the project's subject shape);
33
+ sync installs it as the commit-msg hook; exit 1 on a problem, 2 on bad input
31
34
  visualize <spec.json> [--out <name>] | --schema
32
35
  Make one small static HTML page (a flow, a status, a before and after) from
33
36
  a JSON spec, in .agents/local/prototypes/; --schema prints the spec's schema
@@ -1,31 +1,29 @@
1
1
  import { VulcanCommands } from '../common/index.ts';
2
2
  import type { TCommandHandler } from '../common/index.ts';
3
- import { runAddCommand } from './add.command.ts';
4
- import { runAgentsCommand } from './agents.command.ts';
5
- import { runCleanCommand } from './clean.command.ts';
6
- import { runDoctorCommand } from './doctor.command.ts';
7
- import { runHelpCommand, runVersionCommand } from './help.command.ts';
8
- import { runInitCommand } from './init.command.ts';
9
- import { runPresetCommand } from './preset.command.ts';
10
- import { runProfileCommand } from './profile.command.ts';
11
- import { runSyncCommand } from './sync.command.ts';
12
- import { runUpgradeCommand } from './upgrade.command.ts';
13
- import { runVisualizeCommand } from './visualize.command.ts';
14
- import { runXCommand } from './x.command.ts';
15
3
 
16
- /** The handler of every implemented command. */
17
- export const COMMAND_HANDLERS: Record<string, TCommandHandler> = {
18
- [VulcanCommands.ADD]: runAddCommand,
19
- [VulcanCommands.AGENTS]: runAgentsCommand,
20
- [VulcanCommands.CLEAN]: runCleanCommand,
21
- [VulcanCommands.DOCTOR]: runDoctorCommand,
22
- [VulcanCommands.HELP]: runHelpCommand,
23
- [VulcanCommands.INIT]: runInitCommand,
24
- [VulcanCommands.PRESET]: runPresetCommand,
25
- [VulcanCommands.PROFILE]: runProfileCommand,
26
- [VulcanCommands.SYNC]: runSyncCommand,
27
- [VulcanCommands.UPGRADE]: runUpgradeCommand,
28
- [VulcanCommands.VERSION]: runVersionCommand,
29
- [VulcanCommands.VISUALIZE]: runVisualizeCommand,
30
- [VulcanCommands.X]: runXCommand,
4
+ /** Each command is loaded when it runs: `commit-check` is called by a git hook and must not load the commands that need atlas. */
5
+ export const COMMAND_LOADERS: Record<string, () => Promise<TCommandHandler>> = {
6
+ [VulcanCommands.ADD]: () => import('./add.command.ts').then((module) => module.runAddCommand),
7
+ [VulcanCommands.AGENTS]: () =>
8
+ import('./agents.command.ts').then((module) => module.runAgentsCommand),
9
+ [VulcanCommands.CLEAN]: () =>
10
+ import('./clean.command.ts').then((module) => module.runCleanCommand),
11
+ [VulcanCommands.COMMIT_CHECK]: () =>
12
+ import('./commit-check.command.ts').then((module) => module.runCommitCheckCommand),
13
+ [VulcanCommands.DOCTOR]: () =>
14
+ import('./doctor.command.ts').then((module) => module.runDoctorCommand),
15
+ [VulcanCommands.HELP]: () => import('./help.command.ts').then((module) => module.runHelpCommand),
16
+ [VulcanCommands.INIT]: () => import('./init.command.ts').then((module) => module.runInitCommand),
17
+ [VulcanCommands.PRESET]: () =>
18
+ import('./preset.command.ts').then((module) => module.runPresetCommand),
19
+ [VulcanCommands.PROFILE]: () =>
20
+ import('./profile.command.ts').then((module) => module.runProfileCommand),
21
+ [VulcanCommands.SYNC]: () => import('./sync.command.ts').then((module) => module.runSyncCommand),
22
+ [VulcanCommands.UPGRADE]: () =>
23
+ import('./upgrade.command.ts').then((module) => module.runUpgradeCommand),
24
+ [VulcanCommands.VERSION]: () =>
25
+ import('./help.command.ts').then((module) => module.runVersionCommand),
26
+ [VulcanCommands.VISUALIZE]: () =>
27
+ import('./visualize.command.ts').then((module) => module.runVisualizeCommand),
28
+ [VulcanCommands.X]: () => import('./x.command.ts').then((module) => module.runXCommand),
31
29
  };
@@ -2,11 +2,10 @@ import { existsSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import { ExitCodes } from '../common/index.ts';
4
4
  import type { ICommandContext } from '../common/index.ts';
5
- import { ConfigExtensions } from '../config/index.ts';
6
5
  import { CreateFlags } from '../create/common/index.ts';
7
6
  import { Monorepo } from '../create/init-monorepo.ts';
8
7
  import { SubProcess } from '../create/process.ts';
9
- import { InitConstants, ProjectScaffold } from '../init/index.ts';
8
+ import { ProjectScaffold } from '../init/index.ts';
10
9
  import { ProfilePrompt } from './profile.command.ts';
11
10
 
12
11
  export const runInitCommand = async (opts: ICommandContext): Promise<number> => {
@@ -14,18 +13,6 @@ export const runInitCommand = async (opts: ICommandContext): Promise<number> =>
14
13
  return Monorepo.create({ cwd: opts.cwd, args: opts.args });
15
14
  }
16
15
 
17
- const flagIndex = opts.args.indexOf(InitConstants.CONFIG_FLAG);
18
- const requested = flagIndex === -1 ? ConfigExtensions.MTS : (opts.args[flagIndex + 1] ?? '');
19
- const extension = ConfigExtensions.LOOKUP_ORDER.find((value) => value === requested);
20
-
21
- if (extension === undefined) {
22
- process.stderr.write(
23
- `vulcan init: ${InitConstants.CONFIG_FLAG} takes one of ${ConfigExtensions.LOOKUP_ORDER.join(', ')}\n`,
24
- );
25
-
26
- return ExitCodes.FAILURE;
27
- }
28
-
29
16
  // Without it `bun add` walks up to a parent project and installs there.
30
17
  if (!existsSync(join(opts.cwd, 'package.json'))) {
31
18
  process.stderr.write(
@@ -35,7 +22,7 @@ export const runInitCommand = async (opts: ICommandContext): Promise<number> =>
35
22
  return ExitCodes.FAILURE;
36
23
  }
37
24
 
38
- const result = ProjectScaffold.scaffold({ root: opts.cwd, extension });
25
+ const result = ProjectScaffold.scaffold({ root: opts.cwd });
39
26
 
40
27
  for (const entry of result.entries) {
41
28
  process.stderr.write(` ${entry.status.padEnd(8)} ${entry.subject}\n`);
@@ -17,14 +17,13 @@ import {
17
17
  BaseRulesDiff,
18
18
  ExcludePlan,
19
19
  LocalPlan,
20
- PrunePlan,
21
20
  SyncConstants,
22
21
  SyncPlanner,
23
22
  SyncStatuses,
24
23
  } from '../sync/index.ts';
24
+ import { CommitHookPlan } from '../commit/index.ts';
25
25
 
26
26
  const DRY_RUN_FLAG = '--dry-run';
27
- const PRUNE_FLAG = '--prune';
28
27
  const LABEL_WIDTH = 9;
29
28
 
30
29
  /** Under --dry-run nothing is written, so a write is labelled as what it would do. */
@@ -106,8 +105,6 @@ export class SyncFlow {
106
105
  (id) => !resolved.agents.includes(id),
107
106
  );
108
107
  const dryRun = opts.args.includes(DRY_RUN_FLAG);
109
- // Planned before anything is written: prune reads the managed record of the previous sync.
110
- const pruned = opts.args.includes(PRUNE_FLAG) ? PrunePlan.plan({ root: opts.cwd }) : [];
111
108
  // The stored choice is listed whether it was just written or only read; a machine that has not chosen stores nothing.
112
109
  const stored =
113
110
  resolved.writeLocal || resolved.source === 'local'
@@ -123,7 +120,7 @@ export class SyncFlow {
123
120
  ...stored,
124
121
  ...LocalPlan.planWorkspace({ root: opts.cwd }),
125
122
  ...ExcludePlan.plan({ root: opts.cwd, agents: resolved.agents }),
126
- ...pruned,
123
+ ...CommitHookPlan.plan({ root: opts.cwd, config: loaded.config }),
127
124
  ];
128
125
  // Read before the manifest action rewrites the hashes it compares against.
129
126
  const changes = BaseRulesDiff.diff({ root: opts.cwd });
@@ -50,7 +50,7 @@ export class ToolRunner {
50
50
  static async buildEnvironment(opts: {
51
51
  root: string;
52
52
  }): Promise<{ ok: true; env: Record<string, string> } | { ok: false; error: string }> {
53
- if (ConfigLoader.findFiles({ root: opts.root }).length === 0) {
53
+ if (ConfigLoader.findFile({ root: opts.root }) === undefined) {
54
54
  return { ok: true, env: {} };
55
55
  }
56
56
 
@@ -0,0 +1,32 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { z } from 'zod';
4
+ import { BASE_DIRECTORY } from '../common/index.ts';
5
+ import type { ICommitAgents } from './common/index.ts';
6
+
7
+ const AGENTS_SCHEMA = z.strictObject({
8
+ products: z.array(z.string().min(1)).min(1),
9
+ mentions: z.array(z.string().min(1)).min(1),
10
+ addressNames: z.array(z.string().min(1)),
11
+ addressDomains: z.array(z.string().min(1)),
12
+ noreplyDomains: z.array(z.string().min(1)),
13
+ generatedPhrases: z.array(z.string().min(1)).min(1),
14
+ });
15
+
16
+ let cached: z.output<typeof AGENTS_SCHEMA> | undefined;
17
+
18
+ export class CommitAgents {
19
+ /** `extra` joins both `products` and `mentions`. A broken table throws. */
20
+ static read(opts: { extra: string[]; allow?: string[] }): ICommitAgents {
21
+ cached ??= AGENTS_SCHEMA.parse(
22
+ JSON.parse(readFileSync(join(BASE_DIRECTORY, 'commit-agents.json'), 'utf8')),
23
+ );
24
+
25
+ return {
26
+ ...cached,
27
+ products: [...new Set([...cached.products, ...opts.extra])],
28
+ mentions: [...new Set([...cached.mentions, ...opts.extra])],
29
+ allow: opts.allow ?? [],
30
+ };
31
+ }
32
+ }