@venizia/vulcan 0.4.9-3 → 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.
@@ -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
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.9-3",
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-3",
48
- "@venizia/vulcan-okf": "0.4.9-3",
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": {
@@ -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);
@@ -27,6 +27,10 @@ Usage: bun x vulcan <command>
27
27
  agents [list|add <ids>|remove <ids>|setup] [--dry-run]
28
28
  See, add, remove or re-choose the coding agents you use on this machine
29
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
30
34
  visualize <spec.json> [--out <name>] | --schema
31
35
  Make one small static HTML page (a flow, a status, a before and after) from
32
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
  };
@@ -21,6 +21,7 @@ import {
21
21
  SyncPlanner,
22
22
  SyncStatuses,
23
23
  } from '../sync/index.ts';
24
+ import { CommitHookPlan } from '../commit/index.ts';
24
25
 
25
26
  const DRY_RUN_FLAG = '--dry-run';
26
27
  const LABEL_WIDTH = 9;
@@ -119,6 +120,7 @@ export class SyncFlow {
119
120
  ...stored,
120
121
  ...LocalPlan.planWorkspace({ root: opts.cwd }),
121
122
  ...ExcludePlan.plan({ root: opts.cwd, agents: resolved.agents }),
123
+ ...CommitHookPlan.plan({ root: opts.cwd, config: loaded.config }),
122
124
  ];
123
125
  // Read before the manifest action rewrites the hashes it compares against.
124
126
  const changes = BaseRulesDiff.diff({ root: opts.cwd });
@@ -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
+ }
@@ -0,0 +1,160 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ import { readFileSync } from 'node:fs';
3
+ import { ExitCodes } from '../common/index.ts';
4
+ import type { ICommandContext } from '../common/index.ts';
5
+ import { AgentSignaturePolicies, CommitCheckFlags } from './common/index.ts';
6
+ import type { ICommentStyle, ICommitPolicy } from './common/index.ts';
7
+ import { CommitMessage } from './message.ts';
8
+ import { CommitPolicy } from './policy.ts';
9
+ import { AgentSignature } from './signature.ts';
10
+ import { SubjectShape } from './subject.ts';
11
+
12
+ const USAGE = `usage: vulcan commit-check <message-file> | ${CommitCheckFlags.RANGE} <revs> | ${CommitCheckFlags.TEXT} <message>`;
13
+
14
+ interface ICheckedMessage {
15
+ label: string;
16
+ message: string;
17
+ }
18
+
19
+ type TSource =
20
+ | { kind: 'file'; value: string }
21
+ | { kind: 'text'; value: string }
22
+ | { kind: 'range'; value: string };
23
+
24
+ type TMessages = { ok: true; messages: ICheckedMessage[] } | { ok: false; error: string };
25
+
26
+ export class CommitCheck {
27
+ static async run(opts: ICommandContext): Promise<number> {
28
+ const source = CommitCheck.sourceOf({ args: opts.args });
29
+
30
+ if (source === undefined) {
31
+ process.stderr.write(`commit-check: ${USAGE}\n`);
32
+
33
+ return ExitCodes.USAGE;
34
+ }
35
+
36
+ const input = CommitCheck.readMessages({ cwd: opts.cwd, source });
37
+
38
+ if (!input.ok) {
39
+ process.stderr.write(`commit-check: ${input.error}\n`);
40
+
41
+ return ExitCodes.USAGE;
42
+ }
43
+
44
+ const policy = CommitPolicy.read({ root: opts.cwd });
45
+
46
+ if (policy === undefined) {
47
+ process.stderr.write(
48
+ 'commit-check: no commit check is configured (commit.message in .configs/vulcan.config.mts); nothing checked\n',
49
+ );
50
+
51
+ return ExitCodes.OK;
52
+ }
53
+
54
+ const comment = CommitMessage.commentStyleOf({ cwd: opts.cwd });
55
+ const problems = input.messages.flatMap((checked) =>
56
+ CommitCheck.problemsOf({ checked, policy, comment }),
57
+ );
58
+
59
+ if (problems.length === 0) {
60
+ return ExitCodes.OK;
61
+ }
62
+
63
+ process.stderr.write(
64
+ `commit-check: ${problems.length} problem(s) in the commit message:\n${problems.join('\n')}\n`,
65
+ );
66
+
67
+ return ExitCodes.FAILURE;
68
+ }
69
+
70
+ private static sourceOf(opts: { args: string[] }): TSource | undefined {
71
+ const [first, second, ...rest] = opts.args;
72
+
73
+ if (first === CommitCheckFlags.TEXT && second !== undefined && rest.length === 0) {
74
+ return { kind: 'text', value: second };
75
+ }
76
+
77
+ if (first === CommitCheckFlags.RANGE && second !== undefined && rest.length === 0) {
78
+ return { kind: 'range', value: second };
79
+ }
80
+
81
+ return first !== undefined && !first.startsWith('--') && second === undefined
82
+ ? { kind: 'file', value: first }
83
+ : undefined;
84
+ }
85
+
86
+ private static problemsOf(opts: {
87
+ checked: ICheckedMessage;
88
+ policy: ICommitPolicy;
89
+ comment: ICommentStyle;
90
+ }): string[] {
91
+ const { checked, policy, comment } = opts;
92
+ const signed =
93
+ policy.agentSignature === AgentSignaturePolicies.DENY
94
+ ? AgentSignature.find({ message: checked.message, agents: policy.agents, comment }).map(
95
+ (hit) =>
96
+ ` ${checked.label} line ${hit.line}: "${hit.text}" signs the commit as an agent; remove the line`,
97
+ )
98
+ : [];
99
+ const shape =
100
+ policy.subject === undefined
101
+ ? undefined
102
+ : SubjectShape.problemOf({ message: checked.message, subject: policy.subject, comment });
103
+
104
+ return shape === undefined
105
+ ? signed
106
+ : [
107
+ ...signed,
108
+ ` ${checked.label} line ${shape.line}: "${shape.text}" does not match the shape ${policy.subject?.pattern}${shape.hint === undefined ? '' : ` (${shape.hint})`}`,
109
+ ];
110
+ }
111
+
112
+ private static readMessages(opts: { cwd: string; source: TSource }): TMessages {
113
+ const { kind, value } = opts.source;
114
+
115
+ if (kind === 'text') {
116
+ return { ok: true, messages: [{ label: 'message,', message: value }] };
117
+ }
118
+
119
+ if (kind === 'range') {
120
+ return CommitCheck.readRange({ cwd: opts.cwd, range: value });
121
+ }
122
+
123
+ try {
124
+ return {
125
+ ok: true,
126
+ messages: [{ label: 'commit message,', message: readFileSync(value, 'utf8') }],
127
+ };
128
+ } catch (error) {
129
+ return {
130
+ ok: false,
131
+ error: `cannot read ${value}: ${error instanceof Error ? error.message : String(error)}`,
132
+ };
133
+ }
134
+ }
135
+
136
+ private static readRange(opts: { cwd: string; range: string }): TMessages {
137
+ const result = spawnSync(
138
+ 'git',
139
+ ['log', '--format=%h%x01%B%x00', '--end-of-options', opts.range],
140
+ { cwd: opts.cwd, encoding: 'utf8' },
141
+ );
142
+
143
+ if (result.status !== 0) {
144
+ return { ok: false, error: `git log ${opts.range} failed: ${result.stderr.trim()}` };
145
+ }
146
+
147
+ return {
148
+ ok: true,
149
+ messages: result.stdout
150
+ .split('\x00')
151
+ .map((chunk) => chunk.replace(/^\n/, ''))
152
+ .filter((chunk) => chunk.trim() !== '')
153
+ .map((chunk) => {
154
+ const [id, ...body] = chunk.split('\x01');
155
+
156
+ return { label: `commit ${id},`, message: body.join('\x01') };
157
+ }),
158
+ };
159
+ }
160
+ }
@@ -0,0 +1,28 @@
1
+ export class AgentSignaturePolicies {
2
+ static readonly ALLOW = 'allow';
3
+ static readonly DENY = 'deny';
4
+
5
+ static readonly SCHEME_SET = new Set<string>([this.ALLOW, this.DENY]);
6
+
7
+ static isValid(value: string): boolean {
8
+ return this.SCHEME_SET.has(value);
9
+ }
10
+ }
11
+
12
+ export class CommitCheckFlags {
13
+ static readonly RANGE = '--range';
14
+ static readonly TEXT = '--text';
15
+ }
16
+
17
+ export class CommitHookStates {
18
+ static readonly OFF = 'off';
19
+ static readonly NOT_GIT = 'not-git';
20
+ static readonly MISSING = 'missing';
21
+ /** The hook calls `vulcan commit-check`: ours and current, or the developer's own wiring. */
22
+ static readonly WIRED = 'wired';
23
+ static readonly STALE = 'stale';
24
+ /** A hook that is not ours and does not call the check: the developer adds the line. */
25
+ static readonly UNWIRED = 'unwired';
26
+ /** Our hook, and the project turned every check off: sync takes it back. */
27
+ static readonly LEFTOVER = 'leftover';
28
+ }
@@ -0,0 +1,2 @@
1
+ export * from './constants.ts';
2
+ export * from './types.ts';
@@ -0,0 +1,57 @@
1
+ import type { TConstValue } from '../../common/index.ts';
2
+ import type { AgentSignaturePolicies, CommitHookStates } from './constants.ts';
3
+
4
+ export type TAgentSignaturePolicy = TConstValue<typeof AgentSignaturePolicies>;
5
+
6
+ export interface ICommitAgents {
7
+ /** Names that begin a co-author's name when an agent made the commit: "Claude Code", "Cursor Agent". */
8
+ products: string[];
9
+ /** Words a "generated with" line names an agent by: "Claude", "Gemini". */
10
+ mentions: string[];
11
+ /** Local parts that name an agent: `cursoragent`, on an address at one of `addressDomains`. */
12
+ addressNames: string[];
13
+ addressDomains: string[];
14
+ noreplyDomains: string[];
15
+ generatedPhrases: string[];
16
+ /** Names the project says are never an agent (a person called Claude). */
17
+ allow: string[];
18
+ }
19
+
20
+ /** `line` counts from 1. */
21
+ export interface ISignatureHit {
22
+ line: number;
23
+ text: string;
24
+ }
25
+
26
+ /** `pattern` is a regular expression source. */
27
+ export interface ICommitSubject {
28
+ pattern: string;
29
+ hint?: string;
30
+ }
31
+
32
+ export interface ISubjectProblem {
33
+ line: number;
34
+ text: string;
35
+ hint: string | undefined;
36
+ }
37
+
38
+ export interface ICommitPolicy {
39
+ agentSignature: TAgentSignaturePolicy;
40
+ agents: ICommitAgents;
41
+ subject?: ICommitSubject;
42
+ }
43
+
44
+ export type TCommitHookState = TConstValue<typeof CommitHookStates>;
45
+
46
+ export interface ICommitHookStatus {
47
+ state: TCommitHookState;
48
+ /** Empty when the folder is not a git repository. */
49
+ path: string;
50
+ /** What the developer does when sync cannot: the line to add to a hook that is theirs. */
51
+ note?: string;
52
+ }
53
+
54
+ /** The prefixes git treats as comment lines, and as the start of the scissors line. */
55
+ export interface ICommentStyle {
56
+ prefixes: string[];
57
+ }
@@ -0,0 +1,187 @@
1
+ import { chmodSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
2
+ import { dirname, resolve } from 'node:path';
3
+ import type { TResolvedConfig } from '../config/index.ts';
4
+ import type { ISyncAction } from '../sync/common/index.ts';
5
+ import { SyncStatuses } from '../sync/common/index.ts';
6
+ import { AgentSignaturePolicies, CommitHookStates } from './common/index.ts';
7
+ import type { ICommitHookStatus } from './common/index.ts';
8
+
9
+ const HOOK_NAME = 'commit-msg';
10
+ const MARKER = '# vulcan:commit-msg';
11
+ const CALL = /vulcan\s+commit-check/;
12
+ const COMMAND = 'bun x --no-install vulcan commit-check "$1"';
13
+
14
+ const git = (opts: { root: string; args: string[] }): string | undefined => {
15
+ try {
16
+ const result = Bun.spawnSync(['git', ...opts.args], {
17
+ cwd: opts.root,
18
+ stdout: 'pipe',
19
+ stderr: 'ignore',
20
+ });
21
+
22
+ return result.exitCode === 0 ? result.stdout.toString().trim() : undefined;
23
+ } catch {
24
+ return undefined;
25
+ }
26
+ };
27
+
28
+ export class CommitHook {
29
+ static isWanted(opts: { config: TResolvedConfig }): boolean {
30
+ const { agent, subject } = opts.config.commit.message;
31
+
32
+ return agent.signature === AgentSignaturePolicies.DENY || subject !== undefined;
33
+ }
34
+
35
+ /**
36
+ * The hook file: a POSIX shell script that hands the message to `vulcan commit-check` from the
37
+ * project folder. A commit goes through, with a note on stderr, when bun is not installed, no
38
+ * `node_modules/@venizia/vulcan` is found from the project folder up to the git top level, or the installed vulcan has
39
+ * no `commit-check` command (an older branch).
40
+ */
41
+ static template(opts: { prefix: string }): string {
42
+ const folder = opts.prefix.replace(/\/$/, '');
43
+ const enter = folder === '' ? '' : `cd ${CommitHook.quote({ text: folder })} || exit 0\n`;
44
+
45
+ return `#!/bin/sh
46
+ ${MARKER} - written by vulcan sync from commit.message in .configs/vulcan.config.mts; do not edit
47
+ message="$1"
48
+ case "$message" in /*) ;; *) message="$PWD/$message" ;; esac
49
+ top="$(git rev-parse --show-toplevel)"
50
+ cd "$top" || exit 0
51
+ ${enter}if ! command -v bun >/dev/null 2>&1; then
52
+ echo "vulcan: the commit-msg hook is skipped - bun is not installed" >&2
53
+ exit 0
54
+ fi
55
+ dir="$PWD"
56
+ while [ ! -d "$dir/node_modules/@venizia/vulcan" ]; do
57
+ if [ "$dir" = "$top" ] || [ "$dir" = "/" ]; then
58
+ echo "vulcan: the commit-msg hook is skipped - run bun install" >&2
59
+ exit 0
60
+ fi
61
+ dir="$(dirname "$dir")"
62
+ done
63
+ output="$(${COMMAND.replace('"$1"', '"$message"')} 2>&1)"
64
+ status=$?
65
+ if [ "$status" -eq 1 ] && printf '%s\n' "$output" | grep -q "^vulcan: unknown command 'commit-check'"; then
66
+ echo "vulcan: the commit-msg hook is skipped - the installed vulcan has no commit-check command" >&2
67
+ exit 0
68
+ fi
69
+ [ -z "$output" ] || printf '%s\n' "$output" >&2
70
+ exit "$status"
71
+ `;
72
+ }
73
+
74
+ private static quote(opts: { text: string }): string {
75
+ return `'${opts.text.replaceAll("'", "'\\''")}'`;
76
+ }
77
+
78
+ /** A project that sets `core.hooksPath` owns its hooks: this only reads them. */
79
+ static stateOf(opts: { root: string; config: TResolvedConfig }): ICommitHookStatus {
80
+ const location = git({
81
+ root: opts.root,
82
+ args: ['rev-parse', '--git-path', `hooks/${HOOK_NAME}`],
83
+ });
84
+ const prefix = git({ root: opts.root, args: ['rev-parse', '--show-prefix'] });
85
+ const isWanted = CommitHook.isWanted({ config: opts.config });
86
+
87
+ if (location === undefined || location === '' || prefix === undefined) {
88
+ return { state: isWanted ? CommitHookStates.NOT_GIT : CommitHookStates.OFF, path: '' };
89
+ }
90
+
91
+ const path = resolve(opts.root, location);
92
+ const hooksPath = git({ root: opts.root, args: ['config', '--get', 'core.hooksPath'] });
93
+ const entry = lstatSync(path, { throwIfNoEntry: false });
94
+ const text = entry?.isFile() === true ? readFileSync(path, 'utf8') : undefined;
95
+ const isOurs = hooksPath === undefined && text?.split('\n')[1]?.startsWith(MARKER) === true;
96
+
97
+ if (!isWanted) {
98
+ return { state: isOurs ? CommitHookStates.LEFTOVER : CommitHookStates.OFF, path };
99
+ }
100
+
101
+ const addLine = `add '${COMMAND}' to its ${HOOK_NAME} hook`;
102
+
103
+ if (hooksPath !== undefined) {
104
+ return text !== undefined && CALL.test(text)
105
+ ? { state: CommitHookStates.WIRED, path }
106
+ : {
107
+ state: CommitHookStates.UNWIRED,
108
+ path,
109
+ note: `core.hooksPath is ${hooksPath}: ${addLine}`,
110
+ };
111
+ }
112
+
113
+ if (entry === undefined) {
114
+ return { state: CommitHookStates.MISSING, path };
115
+ }
116
+
117
+ if (text === undefined) {
118
+ return {
119
+ state: CommitHookStates.UNWIRED,
120
+ path,
121
+ note: `a symbolic link or folder, not touched: ${addLine}`,
122
+ };
123
+ }
124
+
125
+ if (isOurs) {
126
+ const isCurrent = text === CommitHook.template({ prefix }) && (entry.mode & 0o111) !== 0;
127
+
128
+ return { state: isCurrent ? CommitHookStates.WIRED : CommitHookStates.STALE, path };
129
+ }
130
+
131
+ return CALL.test(text)
132
+ ? { state: CommitHookStates.WIRED, path }
133
+ : {
134
+ state: CommitHookStates.UNWIRED,
135
+ path,
136
+ note: `a hook of yours is there, not touched: ${addLine}`,
137
+ };
138
+ }
139
+
140
+ static write(opts: { path: string; prefix: string }): void {
141
+ mkdirSync(dirname(opts.path), { recursive: true });
142
+ writeFileSync(opts.path, CommitHook.template({ prefix: opts.prefix }));
143
+ chmodSync(opts.path, 0o755);
144
+ }
145
+ }
146
+
147
+ export class CommitHookPlan {
148
+ static plan(opts: { root: string; config: TResolvedConfig }): ISyncAction[] {
149
+ const status = CommitHook.stateOf(opts);
150
+ const prefix = git({ root: opts.root, args: ['rev-parse', '--show-prefix'] }) ?? '';
151
+ const { path } = status;
152
+ const write = (): void => CommitHook.write({ path, prefix });
153
+
154
+ switch (status.state) {
155
+ case CommitHookStates.MISSING: {
156
+ return [{ path, status: SyncStatuses.CREATED, apply: write }];
157
+ }
158
+
159
+ case CommitHookStates.STALE: {
160
+ return [{ path, status: SyncStatuses.REPLACED, apply: write }];
161
+ }
162
+
163
+ case CommitHookStates.WIRED: {
164
+ return [{ path, status: SyncStatuses.UNCHANGED, apply: () => {} }];
165
+ }
166
+
167
+ case CommitHookStates.UNWIRED: {
168
+ return [{ path, status: SyncStatuses.SKIPPED, note: status.note, apply: () => {} }];
169
+ }
170
+
171
+ case CommitHookStates.LEFTOVER: {
172
+ return [
173
+ {
174
+ path,
175
+ status: SyncStatuses.REMOVED,
176
+ note: 'no commit check is turned on',
177
+ apply: () => rmSync(path),
178
+ },
179
+ ];
180
+ }
181
+
182
+ default: {
183
+ return [];
184
+ }
185
+ }
186
+ }
187
+ }
@@ -0,0 +1,8 @@
1
+ export * from './common/index.ts';
2
+ export * from './agents.ts';
3
+ export * from './signature.ts';
4
+ export * from './subject.ts';
5
+ export * from './policy.ts';
6
+ export * from './check.ts';
7
+ export * from './hook.ts';
8
+ export * from './message.ts';
@@ -0,0 +1,74 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ import { TextValue } from '../common/index.ts';
3
+ import type { ICommentStyle } from './common/index.ts';
4
+
5
+ const INVISIBLE = /[\p{Cf}︎️]/gu;
6
+ const DASHES = /[\p{Pd}−]/gu;
7
+ /** The characters git picks from when `core.commentChar` is `auto`. */
8
+ const AUTO_PREFIXES = ['#', ';', '@', '!', '$', '%', '^', '&', '|', ':'];
9
+ const DEFAULT_STYLE: ICommentStyle = { prefixes: ['#'] };
10
+ /** A camel-case word, an acronym, a number, or any other run of letters. */
11
+ const TOKEN = /\p{Lu}+(?!\p{Ll})|\p{Lu}?\p{Ll}+|\p{N}+|\p{L}+/gu;
12
+
13
+ export class CommitMessage {
14
+ /** The comment style of the repository at `cwd`: `core.commentString` or `core.commentChar`, `#` by default. */
15
+ static commentStyleOf(opts: { cwd: string }): ICommentStyle {
16
+ for (const key of ['core.commentString', 'core.commentChar']) {
17
+ const result = spawnSync('git', ['config', '--get', key], {
18
+ cwd: opts.cwd,
19
+ encoding: 'utf8',
20
+ });
21
+ const value = result.status === 0 ? result.stdout.replace(/\r?\n$/, '') : '';
22
+
23
+ if (value === 'auto') {
24
+ return { prefixes: AUTO_PREFIXES };
25
+ }
26
+
27
+ if (value !== '') {
28
+ return { prefixes: [value] };
29
+ }
30
+ }
31
+
32
+ return DEFAULT_STYLE;
33
+ }
34
+
35
+ static isComment(opts: { line: string; comment?: ICommentStyle }): boolean {
36
+ return (opts.comment ?? DEFAULT_STYLE).prefixes.some((prefix) => opts.line.startsWith(prefix));
37
+ }
38
+
39
+ /** A lone carriage return is a line break too. Nothing below the scissors line of `git commit -v` is the message. */
40
+ static linesOf(opts: { message: string; comment?: ICommentStyle }): string[] {
41
+ const lines = opts.message.split(/\r\n|\r|\n/);
42
+ const scissors = (opts.comment ?? DEFAULT_STYLE).prefixes.map(
43
+ (prefix) => new RegExp(`^${TextValue.escapeLiteral({ text: prefix })} -+ >8 -+$`),
44
+ );
45
+ const cut = lines.findIndex((text) => scissors.some((pattern) => pattern.test(text)));
46
+
47
+ return cut === -1 ? lines : lines.slice(0, cut);
48
+ }
49
+
50
+ static cleanOf(opts: { text: string }): string {
51
+ return opts.text.replace(INVISIBLE, '').replace(DASHES, '-');
52
+ }
53
+
54
+ /** Letters and digits only, lower case: "Claude Code", "ClaudeCode" and "claude-code" read alike. */
55
+ static compactOf(opts: { text: string }): string {
56
+ return opts.text
57
+ .normalize('NFKC')
58
+ .toLowerCase()
59
+ .replace(/[^\p{L}\p{N}]/gu, '');
60
+ }
61
+
62
+ /** The words of `text`, split at punctuation, at camel-case boundaries and between letters and digits. */
63
+ static tokensOf(opts: { text: string }): string[] {
64
+ return opts.text.normalize('NFKC').match(TOKEN) ?? [];
65
+ }
66
+
67
+ /** Whether the words of `text` begin with one of `forms`, whole words only: "Claude Code 4" does, "Claude Coderre" does not. */
68
+ static beginsWithForm(opts: { text: string; forms: string[] }): boolean {
69
+ const tokens = CommitMessage.tokensOf({ text: opts.text }).map((token) => token.toLowerCase());
70
+ const forms = new Set(opts.forms.map((form) => CommitMessage.compactOf({ text: form })));
71
+
72
+ return tokens.some((_, index) => forms.has(tokens.slice(0, index + 1).join('')));
73
+ }
74
+ }
@@ -0,0 +1,110 @@
1
+ import { existsSync, readFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { RecordValue } from '../common/record.ts';
4
+ import { CommitAgents } from './agents.ts';
5
+ import { AgentSignaturePolicies } from './common/index.ts';
6
+ import type { ICommitPolicy, ICommitSubject, TAgentSignaturePolicy } from './common/index.ts';
7
+
8
+ const MANIFEST_FILE = '.agents/vulcan.manifest.json';
9
+
10
+ export class CommitPolicy {
11
+ /**
12
+ * The checks the project turned on, from the manifest `vulcan sync` wrote; undefined when the
13
+ * project turned none on, or when the block is not what sync writes (a note says so, and nothing is checked).
14
+ */
15
+ static read(opts: { root: string }): ICommitPolicy | undefined {
16
+ const file = join(opts.root, MANIFEST_FILE);
17
+
18
+ if (!existsSync(file)) {
19
+ return undefined;
20
+ }
21
+
22
+ let manifest: unknown;
23
+
24
+ try {
25
+ manifest = JSON.parse(readFileSync(file, 'utf8'));
26
+ } catch (error) {
27
+ console.error(
28
+ `[CommitPolicy.read] ${MANIFEST_FILE} is not JSON | ${error instanceof Error ? error.message : String(error)}`,
29
+ );
30
+
31
+ return undefined;
32
+ }
33
+
34
+ const commit = RecordValue.isRecord(manifest) ? manifest.commit : undefined;
35
+ const block = RecordValue.isRecord(commit) ? commit.message : undefined;
36
+
37
+ if (block === undefined) {
38
+ return undefined;
39
+ }
40
+
41
+ const policy = CommitPolicy.parse({ block });
42
+
43
+ if (policy === undefined) {
44
+ console.error(
45
+ `[CommitPolicy.read] ignoring commit.message in ${MANIFEST_FILE}: not the shape vulcan sync writes - run vulcan sync`,
46
+ );
47
+ }
48
+
49
+ return policy;
50
+ }
51
+
52
+ private static parse(opts: { block: unknown }): ICommitPolicy | undefined {
53
+ if (!RecordValue.isRecord(opts.block) || !RecordValue.isRecord(opts.block.agent)) {
54
+ return undefined;
55
+ }
56
+
57
+ const { signature, names, allow } = opts.block.agent;
58
+ const { subject } = opts.block;
59
+
60
+ if (typeof signature !== 'string' || !AgentSignaturePolicies.isValid(signature)) {
61
+ return undefined;
62
+ }
63
+
64
+ const extra = CommitPolicy.namesOf({ value: names });
65
+ const allowed = CommitPolicy.namesOf({ value: allow });
66
+
67
+ if (extra === undefined || allowed === undefined) {
68
+ return undefined;
69
+ }
70
+
71
+ const shape = CommitPolicy.subjectOf({ value: subject });
72
+
73
+ if (subject !== undefined && shape === undefined) {
74
+ return undefined;
75
+ }
76
+
77
+ return {
78
+ agentSignature: CommitPolicy.policyOf({ value: signature }),
79
+ agents: CommitAgents.read({ extra, allow: allowed }),
80
+ ...(shape === undefined ? {} : { subject: shape }),
81
+ };
82
+ }
83
+
84
+ private static namesOf(opts: { value: unknown }): string[] | undefined {
85
+ if (opts.value === undefined) {
86
+ return [];
87
+ }
88
+
89
+ return Array.isArray(opts.value) &&
90
+ opts.value.every((name) => typeof name === 'string' && /[\p{L}\p{N}]/u.test(name))
91
+ ? opts.value
92
+ : undefined;
93
+ }
94
+
95
+ private static policyOf(opts: { value: string }): TAgentSignaturePolicy {
96
+ return opts.value === AgentSignaturePolicies.DENY
97
+ ? AgentSignaturePolicies.DENY
98
+ : AgentSignaturePolicies.ALLOW;
99
+ }
100
+
101
+ private static subjectOf(opts: { value: unknown }): ICommitSubject | undefined {
102
+ if (!RecordValue.isRecord(opts.value) || typeof opts.value.pattern !== 'string') {
103
+ return undefined;
104
+ }
105
+
106
+ const { pattern, hint } = opts.value;
107
+
108
+ return typeof hint === 'string' ? { pattern, hint } : { pattern };
109
+ }
110
+ }
@@ -0,0 +1,94 @@
1
+ import type { ICommentStyle, ICommitAgents, ISignatureHit } from './common/index.ts';
2
+ import { CommitMessage } from './message.ts';
3
+
4
+ /** Any `*-by:` trailer: Co-authored-by, Signed-off-by, Co-developed-by, Assisted-by, Reviewed-by. */
5
+ const TRAILER = /^\s*[A-Za-z][A-Za-z-]*-by\s*:\s*(.*)$/i;
6
+ const ADDRESS = /<([^>]+)>/;
7
+ /** `noreply`, `no-reply`, `no_reply`, or GitHub's `<id>+noreply`: the local part of an address no person reads. */
8
+ const NOREPLY_LOCAL = /^(?:\d+\+)?no[-_]?reply$/i;
9
+ const LEADING_PICTOGRAPH = /^\s*(?:\p{Extended_Pictographic}\s*)?/u;
10
+ /** Markup between "Generated with" and the name: `[`, `**`, a backtick, a space. */
11
+ const MARKUP = /^[\s[\]*_`(]+/;
12
+
13
+ export class AgentSignature {
14
+ static find(opts: {
15
+ message: string;
16
+ agents: ICommitAgents;
17
+ comment?: ICommentStyle;
18
+ }): ISignatureHit[] {
19
+ return CommitMessage.linesOf({ message: opts.message, comment: opts.comment }).flatMap(
20
+ (raw, index) => {
21
+ const text = CommitMessage.cleanOf({ text: raw });
22
+
23
+ if (CommitMessage.isComment({ line: text, comment: opts.comment })) {
24
+ return [];
25
+ }
26
+
27
+ const isSigned =
28
+ AgentSignature.isSigningTrailer({ text, agents: opts.agents }) ||
29
+ AgentSignature.isGeneratedLine({ text, agents: opts.agents });
30
+
31
+ return isSigned ? [{ line: index + 1, text: raw.trim() }] : [];
32
+ },
33
+ );
34
+ }
35
+
36
+ /** A name on the allow list clears a trailer only when it is the whole name and the address is not an agent's. */
37
+ private static isSigningTrailer(opts: { text: string; agents: ICommitAgents }): boolean {
38
+ const value = TRAILER.exec(opts.text)?.[1];
39
+
40
+ if (value === undefined) {
41
+ return false;
42
+ }
43
+
44
+ const address = ADDRESS.exec(value)?.[1] ?? '';
45
+ const display = value.replace(ADDRESS, ' ');
46
+ const isAgentAddress = AgentSignature.isAgentAddress({ address, agents: opts.agents });
47
+ const name = CommitMessage.compactOf({ text: display });
48
+ const isAllowed =
49
+ !isAgentAddress &&
50
+ opts.agents.allow.some((allowed) => CommitMessage.compactOf({ text: allowed }) === name);
51
+
52
+ return (
53
+ !isAllowed &&
54
+ (isAgentAddress ||
55
+ CommitMessage.beginsWithForm({ text: display, forms: opts.agents.products }))
56
+ );
57
+ }
58
+
59
+ /** `noreply` at a vendor's domain, or a local part that names an agent at a domain an agent uses. */
60
+ private static isAgentAddress(opts: { address: string; agents: ICommitAgents }): boolean {
61
+ const at = opts.address.lastIndexOf('@');
62
+
63
+ if (at === -1) {
64
+ return false;
65
+ }
66
+
67
+ const local = opts.address.slice(0, at);
68
+ const bare = local.replace(/^\d+\+/, '').toLowerCase();
69
+ const domain = opts.address.slice(at + 1).toLowerCase();
70
+ const isAt = (domains: string[]): boolean =>
71
+ domains.some((listed) => domain === listed || domain.endsWith(`.${listed}`));
72
+
73
+ return (
74
+ (NOREPLY_LOCAL.test(local) && isAt(opts.agents.noreplyDomains)) ||
75
+ (opts.agents.addressNames.some((name) => name.toLowerCase() === bare) &&
76
+ isAt(opts.agents.addressDomains))
77
+ );
78
+ }
79
+
80
+ /** At the start of a line, and only when an agent's name comes right after: "Generated by scripts/gen.ts from CLAUDE.md" is a note about a file. */
81
+ private static isGeneratedLine(opts: { text: string; agents: ICommitAgents }): boolean {
82
+ const body = opts.text.replace(LEADING_PICTOGRAPH, '').replace(MARKUP, '');
83
+ const lower = body.toLowerCase();
84
+ const phrase = opts.agents.generatedPhrases.find((listed) => lower.startsWith(listed));
85
+
86
+ return (
87
+ phrase !== undefined &&
88
+ CommitMessage.beginsWithForm({
89
+ text: body.slice(phrase.length).replace(MARKUP, ''),
90
+ forms: [...opts.agents.products, ...opts.agents.mentions],
91
+ })
92
+ );
93
+ }
94
+ }
@@ -0,0 +1,40 @@
1
+ import type { ICommentStyle, ICommitSubject, ISubjectProblem } from './common/index.ts';
2
+ import { CommitMessage } from './message.ts';
3
+
4
+ const GENERATED_SUBJECT = /^(?:Merge |Revert "|(?:fixup|squash|amend)! )/;
5
+
6
+ export class SubjectShape {
7
+ static problemOf(opts: {
8
+ message: string;
9
+ subject: ICommitSubject;
10
+ comment?: ICommentStyle;
11
+ }): ISubjectProblem | undefined {
12
+ const lines = CommitMessage.linesOf({ message: opts.message, comment: opts.comment });
13
+ const index = lines.findIndex(
14
+ (text) =>
15
+ text.trim() !== '' && !CommitMessage.isComment({ line: text, comment: opts.comment }),
16
+ );
17
+
18
+ if (index === -1) {
19
+ return undefined;
20
+ }
21
+
22
+ const text = lines[index].trim();
23
+
24
+ if (GENERATED_SUBJECT.test(text) || new RegExp(opts.subject.pattern).test(text)) {
25
+ return undefined;
26
+ }
27
+
28
+ return { line: index + 1, text, hint: opts.subject.hint };
29
+ }
30
+
31
+ static patternError(opts: { pattern: string }): string | undefined {
32
+ try {
33
+ new RegExp(opts.pattern);
34
+
35
+ return undefined;
36
+ } catch (error) {
37
+ return `not a regular expression: ${error instanceof Error ? error.message : String(error)}`;
38
+ }
39
+ }
40
+ }
@@ -9,6 +9,7 @@ export class VulcanCommands {
9
9
  static readonly PROFILE = 'profile';
10
10
  static readonly PRESET = 'preset';
11
11
  static readonly VISUALIZE = 'visualize';
12
+ static readonly COMMIT_CHECK = 'commit-check';
12
13
  static readonly X = 'x';
13
14
  static readonly HELP = 'help';
14
15
  static readonly VERSION = 'version';
@@ -25,6 +26,8 @@ export class UpgradeFlags {
25
26
  export class ExitCodes {
26
27
  static readonly OK = 0;
27
28
  static readonly FAILURE = 1;
29
+ /** A command that cannot run as asked: the arguments, a file or a range it cannot read. */
30
+ static readonly USAGE = 2;
28
31
  }
29
32
 
30
33
  /** The tools `vulcan x` runs; each is a dependency of @venizia/vulcan at the exact same version. */
@@ -2,6 +2,9 @@ import { isAbsolute } from 'node:path';
2
2
  import { z } from 'zod';
3
3
  import { LayoutFolder } from '../common/layout-folder.ts';
4
4
  import { OWNER_SCHEMA } from '../owner/schema.ts';
5
+ import { AgentSignaturePolicies } from '../commit/common/index.ts';
6
+ import type { TAgentSignaturePolicy } from '../commit/common/index.ts';
7
+ import { SubjectShape } from '../commit/subject.ts';
5
8
  import {
6
9
  CodingAgents,
7
10
  ConfigConstants,
@@ -110,6 +113,11 @@ const NPM_PACKAGE_NAME = z.string().superRefine((value, context) => {
110
113
  }
111
114
  });
112
115
 
116
+ /** A name that holds a letter or a digit: an entry of only punctuation or spaces would match everything. */
117
+ const AGENT_NAME = z
118
+ .string()
119
+ .regex(/[\p{L}\p{N}]/u, { message: 'a name with at least one letter or digit' });
120
+
113
121
  const PROJECT_PACKAGE = z.strictObject({
114
122
  dir: z.string().regex(/^[a-z0-9][a-z0-9.-]*$/),
115
123
  name: NPM_PACKAGE_NAME,
@@ -407,6 +415,51 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
407
415
  writes: { trustedScripts: [], commands: [] },
408
416
  git: { askPush: [] },
409
417
  }),
418
+ /**
419
+ * What `vulcan commit-check` looks for in a commit message, and what `vulcan sync` installs the
420
+ * `commit-msg` hook for, nested by scope. Every check is off until the project turns it on:
421
+ * `message.agent.signature: 'deny'` rejects a trailer or a "generated with" line that names an agent
422
+ * (rule W-00 of a project that has one); `message.agent.names` adds names to the shipped list and
423
+ * `message.agent.allow` lists names never flagged; `message.subject` is the project's own one-line
424
+ * shape. Written to the manifest only when a check is on.
425
+ */
426
+ commit: z
427
+ .strictObject({
428
+ message: z
429
+ .strictObject({
430
+ agent: z
431
+ .strictObject({
432
+ signature: z
433
+ .custom<TAgentSignaturePolicy>(
434
+ (value) => typeof value === 'string' && AgentSignaturePolicies.isValid(value),
435
+ { message: `one of ${[...AgentSignaturePolicies.SCHEME_SET].join(', ')}` },
436
+ )
437
+ .default(AgentSignaturePolicies.ALLOW),
438
+ names: z.array(AGENT_NAME).default([]),
439
+ allow: z.array(AGENT_NAME).default([]),
440
+ })
441
+ .default({ signature: AgentSignaturePolicies.ALLOW, names: [], allow: [] }),
442
+ subject: z
443
+ .strictObject({
444
+ pattern: z
445
+ .string()
446
+ .min(1)
447
+ .superRefine((value, context) => {
448
+ const error = SubjectShape.patternError({ pattern: value });
449
+
450
+ if (error !== undefined) {
451
+ context.addIssue({ code: 'custom', message: error });
452
+ }
453
+ }),
454
+ hint: z.string().min(1).optional(),
455
+ })
456
+ .optional(),
457
+ })
458
+ .default({ agent: { signature: AgentSignaturePolicies.ALLOW, names: [], allow: [] } }),
459
+ })
460
+ .default({
461
+ message: { agent: { signature: AgentSignaturePolicies.ALLOW, names: [], allow: [] } },
462
+ }),
410
463
  });
411
464
 
412
465
  export type VulcanConfig = z.input<typeof VULCAN_CONFIG_SCHEMA>;
@@ -10,6 +10,7 @@ import type { TResolvedConfig } from '../config/index.ts';
10
10
  import { BaseRules, RuleParser, RuleSlots } from '../rules/index.ts';
11
11
  import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
12
12
  import { AgentScopes, AgentSelection, AgentTable, LocalChoice } from '../agents/index.ts';
13
+ import { CommitHook, CommitHookStates } from '../commit/index.ts';
13
14
  import { AgentFiles, AtlasBlockPlan, LocalPlan, SyncPlanner, SyncStatuses } from '../sync/index.ts';
14
15
  import { LocalConstants, LocalFormat, LocalScan, LocalStates } from '../local/index.ts';
15
16
  import {
@@ -670,6 +671,53 @@ export class ProjectContract {
670
671
  ];
671
672
  }
672
673
 
674
+ /**
675
+ * The `commit-msg` hook of this clone, when the project turned a commit check on: a missing or out-of-date
676
+ * one is fixed by `vulcan sync`; one that is not ours and does not call the check, or one a project with
677
+ * `core.hooksPath` owns, is told the line to add. Per clone, so a warning and never a violation.
678
+ */
679
+ static checkCommitHook(opts: ICheckContext): IViolation[] {
680
+ const status = CommitHook.stateOf({ root: opts.root, config: opts.config });
681
+ const file = relative(opts.root, status.path);
682
+ const fix = `run '${ProjectLayout.VULCAN_COMMAND} sync' (make vulcan-sync)`;
683
+
684
+ switch (status.state) {
685
+ case CommitHookStates.MISSING: {
686
+ return [
687
+ createViolation({
688
+ check: DoctorChecks.COMMIT_HOOK,
689
+ file,
690
+ message: `the commit-msg hook is not installed, so commit messages are not checked - ${fix}`,
691
+ }),
692
+ ];
693
+ }
694
+
695
+ case CommitHookStates.STALE: {
696
+ return [
697
+ createViolation({
698
+ check: DoctorChecks.COMMIT_HOOK,
699
+ file,
700
+ message: `the commit-msg hook is out of date - ${fix}`,
701
+ }),
702
+ ];
703
+ }
704
+
705
+ case CommitHookStates.UNWIRED: {
706
+ return [
707
+ createViolation({
708
+ check: DoctorChecks.COMMIT_HOOK,
709
+ file,
710
+ message: `the commit-msg hook does not run the commit check - ${status.note ?? fix}`,
711
+ }),
712
+ ];
713
+ }
714
+
715
+ default: {
716
+ return [];
717
+ }
718
+ }
719
+ }
720
+
673
721
  /**
674
722
  * The atlas server is registered the one way every project does: the root `.mcp.json` (a per-machine
675
723
  * file `sync` writes for the agents that read it) holds an `atlas` entry that runs the project's own
@@ -20,6 +20,7 @@ export class DoctorChecks {
20
20
  static readonly LOCAL = 'local';
21
21
  static readonly PROFILE = 'profile';
22
22
  static readonly GUARDS = 'guards';
23
+ static readonly COMMIT_HOOK = 'commit-hook';
23
24
  }
24
25
 
25
26
  /** The `package.json` scripts every app carries, and the names the standard retired. */
@@ -91,6 +91,7 @@ export class DoctorRunner {
91
91
 
92
92
  return [
93
93
  ...ProjectContract.checkMcpAtlas(context),
94
+ ...ProjectContract.checkCommitHook(context),
94
95
  ...ProjectContract.checkDockerignore(context),
95
96
  ...ProjectContract.checkSkillTriggers(context),
96
97
  ...ProjectContract.checkFormat(context),
@@ -1,6 +1,7 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { basename, join } from 'node:path';
3
3
  import { BunFormatter } from '../common/index.ts';
4
+ import { AgentSignaturePolicies } from '../commit/common/index.ts';
4
5
  import { ProjectPackages } from '../config/index.ts';
5
6
  import type { TResolvedConfig } from '../config/index.ts';
6
7
  import { BaseRules } from '../rules/index.ts';
@@ -47,6 +48,28 @@ const guardBlockOf = (opts: { config: TResolvedConfig }): { guard?: Record<strin
47
48
  return Object.keys(block).length === 0 ? {} : { guard: block };
48
49
  };
49
50
 
51
+ const commitBlockOf = (opts: { config: TResolvedConfig }): { commit?: Record<string, unknown> } => {
52
+ const { agent, subject } = opts.config.commit.message;
53
+ const isDenied = agent.signature === AgentSignaturePolicies.DENY;
54
+
55
+ if (!isDenied && subject === undefined) {
56
+ return {};
57
+ }
58
+
59
+ return {
60
+ commit: {
61
+ message: {
62
+ agent: {
63
+ signature: agent.signature,
64
+ ...(isDenied && agent.names.length > 0 ? { names: agent.names } : {}),
65
+ ...(isDenied && agent.allow.length > 0 ? { allow: agent.allow } : {}),
66
+ },
67
+ ...(subject === undefined ? {} : { subject }),
68
+ },
69
+ },
70
+ };
71
+ };
72
+
50
73
  /** The manifest's `atlas` block: only what the config sets (keys listed, the download turned off). */
51
74
  const atlasBlockOf = (opts: { config: TResolvedConfig }): { atlas?: Record<string, unknown> } => {
52
75
  const keys = opts.config.atlas.index?.keys ?? [];
@@ -140,6 +163,7 @@ export class ProjectManifest {
140
163
  ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
141
164
  // The colour `vulcan visualize` takes for its pages; a project without the key gets the neutral default.
142
165
  ...(config.theme === undefined ? {} : { theme: config.theme }),
166
+ ...commitBlockOf({ config }),
143
167
  };
144
168
 
145
169
  return BunFormatter.format({
package/src/router.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { AgentConstants } from './agents/index.ts';
2
- import { COMMAND_HANDLERS } from './commands/index.ts';
3
- import { runHelpCommand } from './commands/help.command.ts';
2
+ import { COMMAND_LOADERS } from './commands/index.ts';
3
+ import { CommitCheckFlags } from './commit/common/index.ts';
4
4
  import { ExitCodes, UpgradeFlags, VulcanCommands } from './common/index.ts';
5
5
  import { CreateFlags } from './create/common/index.ts';
6
6
  import { PipedInputRefusal } from './ui/keyboard.ts';
@@ -10,6 +10,8 @@ const VERSION_ALIASES = new Set(['--version', '-v']);
10
10
 
11
11
  interface IAcceptedArgs {
12
12
  flags: string[];
13
+ /** The exit code for an argument the command does not take; `1` when absent. */
14
+ unknownExit?: number;
13
15
  /** Flags that take the next argument as their value. */
14
16
  values: string[];
15
17
  positionals: number;
@@ -72,6 +74,12 @@ const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
72
74
  values: [],
73
75
  positionals: 0,
74
76
  },
77
+ [VulcanCommands.COMMIT_CHECK]: {
78
+ flags: [],
79
+ unknownExit: ExitCodes.USAGE,
80
+ values: [CommitCheckFlags.RANGE, CommitCheckFlags.TEXT],
81
+ positionals: 2,
82
+ },
75
83
  [VulcanCommands.DOCTOR]: { flags: [], values: [], positionals: 0 },
76
84
  [VulcanCommands.PROFILE]: { flags: ['--yes'], values: [], positionals: 1 },
77
85
  [VulcanCommands.VISUALIZE]: { flags: ['--schema'], values: ['--out'], positionals: 1 },
@@ -117,12 +125,18 @@ const findUnknownArg = (opts: { args: string[]; accepted: IAcceptedArgs }): stri
117
125
  return undefined;
118
126
  };
119
127
 
128
+ const runHelp = async (opts: { cwd: string }): Promise<number> => {
129
+ const help = await COMMAND_LOADERS[VulcanCommands.HELP]();
130
+
131
+ return help({ args: [], cwd: opts.cwd });
132
+ };
133
+
120
134
  export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<number> => {
121
135
  const [first, ...args] = opts.argv;
122
136
  const name = resolveCommandName({ first });
123
- const handler = COMMAND_HANDLERS[name];
137
+ const load = COMMAND_LOADERS[name];
124
138
 
125
- if (handler === undefined) {
139
+ if (load === undefined) {
126
140
  process.stderr.write(`vulcan: unknown command '${name}' - run 'bun x vulcan help'\n`);
127
141
 
128
142
  return ExitCodes.FAILURE;
@@ -130,14 +144,14 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
130
144
 
131
145
  // `x` hands its arguments to the tool, so only a help flag in the tool's place is vulcan's.
132
146
  if (name === VulcanCommands.X && HELP_ALIASES.has(args[0] ?? '')) {
133
- return runHelpCommand();
147
+ return runHelp({ cwd: opts.cwd });
134
148
  }
135
149
 
136
150
  const accepted = ACCEPTED_ARGS[name];
137
151
 
138
152
  if (accepted !== undefined) {
139
153
  if (args.some((arg) => HELP_ALIASES.has(arg))) {
140
- return runHelpCommand();
154
+ return runHelp({ cwd: opts.cwd });
141
155
  }
142
156
 
143
157
  const unknown = findUnknownArg({ args, accepted });
@@ -147,10 +161,12 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
147
161
  `vulcan ${name}: unknown argument '${unknown}' - run 'bun x vulcan help'\n`,
148
162
  );
149
163
 
150
- return ExitCodes.FAILURE;
164
+ return accepted.unknownExit ?? ExitCodes.FAILURE;
151
165
  }
152
166
  }
153
167
 
168
+ const handler = await load();
169
+
154
170
  try {
155
171
  const exitCode = await handler({ args, cwd: opts.cwd });
156
172
 
@@ -16,6 +16,7 @@ export class SyncConstants {
16
16
  static readonly SETTINGS_FILE = 'settings.json';
17
17
  /** The hook sync adds when the config sets `remoteHosts`; lives next to the shipped settings. */
18
18
  static readonly REMOTE_HOSTS_FILE = 'remote-hosts.json';
19
+ static readonly COMMIT_ATTRIBUTION_FILE = 'commit-attribution.json';
19
20
  /** What sync applied last time, so a later sync can take back what the project no longer asks for. */
20
21
  static readonly MANAGED_FILE = 'vulcan-managed.json';
21
22
  static readonly SKILLS_DIRECTORY = 'skills';
@@ -11,6 +11,7 @@ import {
11
11
  import { basename, dirname, join, resolve } from 'node:path';
12
12
  import { AgentTable } from '../agents/index.ts';
13
13
  import { BASE_DIRECTORY, BaseDirectory } from '../common/index.ts';
14
+ import { AgentSignaturePolicies } from '../commit/common/index.ts';
14
15
  import { CodingAgents } from '../config/index.ts';
15
16
  import type { TResolvedConfig } from '../config/index.ts';
16
17
  import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
@@ -63,7 +64,7 @@ const readSettingsFile = (opts: { path: string }): TSettings | undefined => {
63
64
  }
64
65
  };
65
66
 
66
- /** Shipped settings, the chosen slot options, the project's hooks and `claude.settings` - what sync owns. */
67
+ /** Shipped settings, the chosen slot options, the empty attribution of a project that denies agent signatures, the project's hooks and `claude.settings` - what sync owns. */
67
68
  const buildManagedOverlay = (opts: { config: TResolvedConfig }): TSettings => {
68
69
  let overlay: TSettings = JSON.parse(
69
70
  readFileSync(join(BASE_DIRECTORY, 'claude', SyncConstants.SETTINGS_FILE), 'utf8'),
@@ -87,6 +88,15 @@ const buildManagedOverlay = (opts: { config: TResolvedConfig }): TSettings => {
87
88
  });
88
89
  }
89
90
 
91
+ if (opts.config.commit.message.agent.signature === AgentSignaturePolicies.DENY) {
92
+ overlay = ProjectSettings.merge({
93
+ base: overlay,
94
+ overlay: JSON.parse(
95
+ readFileSync(join(BASE_DIRECTORY, 'claude', SyncConstants.COMMIT_ATTRIBUTION_FILE), 'utf8'),
96
+ ),
97
+ });
98
+ }
99
+
90
100
  overlay = ProjectSettings.merge({
91
101
  base: overlay,
92
102
  overlay: ProjectSettings.buildHook({ hooks: opts.config.hooks }),