vyom-gaami 0.0.0-stage → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -2
- package/dist/cli/adapters/claude.js +76 -0
- package/dist/cli/adapters/codex.js +79 -0
- package/dist/cli/adapters/cursor.js +60 -0
- package/dist/cli/adapters/index.js +8 -0
- package/dist/cli/client.js +26 -0
- package/dist/cli/gather.js +108 -0
- package/dist/cli/hook.js +172 -0
- package/dist/cli/init.js +94 -0
- package/dist/cli/local.js +122 -0
- package/dist/cli/main.js +145 -0
- package/dist/cli/types.js +1 -0
- package/dist/gaami/contracts.js +149 -0
- package/dist/gaami/machine.js +233 -0
- package/dist/gaami/method.js +122 -0
- package/dist/gaami/pack.js +78 -0
- package/dist/gaami/policy.js +94 -0
- package/dist/gaami/types.js +1 -0
- package/package.json +20 -4
package/README.md
CHANGED
|
@@ -1,3 +1,15 @@
|
|
|
1
|
-
#
|
|
1
|
+
# vyom-gaami
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Holds coding agents to the vyom-gaami method through their own hooks: triage → discover →
|
|
4
|
+
design → plan → sketch → build → validate → harden → reflect. Each phase may only change
|
|
5
|
+
certain files, and the agent can't stop until the phase's checks pass. A person approves the
|
|
6
|
+
gates in Matrix. Works with Claude Code, Codex and Cursor.
|
|
7
|
+
|
|
8
|
+
```sh
|
|
9
|
+
npm i -g vyom-gaami
|
|
10
|
+
vyom-gaami login # then send the code to @vyom in Matrix
|
|
11
|
+
cd your-repo && vyom-gaami init # onboard the repo (once)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
After that, just prompt your agent. Design and decisions: GnosisHub/vyom-factory
|
|
15
|
+
(`docs/architecture/enforcement.md`).
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Claude Code hooks: UserPromptSubmit, PreToolUse, Stop (docs/architecture/enforcement.md).
|
|
3
|
+
* Payload in on stdin, JSON decision out on stdout. Pure.
|
|
4
|
+
*/
|
|
5
|
+
const WRITE_TOOLS = {
|
|
6
|
+
Write: 'file_path',
|
|
7
|
+
Edit: 'file_path',
|
|
8
|
+
MultiEdit: 'file_path',
|
|
9
|
+
NotebookEdit: 'notebook_path',
|
|
10
|
+
};
|
|
11
|
+
const READ_TOOLS = new Set(['Read', 'Glob', 'Grep', 'LS', 'WebFetch', 'WebSearch', 'TodoWrite']);
|
|
12
|
+
const record = (value) => typeof value === 'object' && value !== null ? value : {};
|
|
13
|
+
const text = (value) => (typeof value === 'string' ? value : '');
|
|
14
|
+
export function toAction(tool, input) {
|
|
15
|
+
const pathField = WRITE_TOOLS[tool];
|
|
16
|
+
if (pathField !== undefined)
|
|
17
|
+
return { kind: 'write', paths: [text(input[pathField])] };
|
|
18
|
+
if (tool === 'Bash')
|
|
19
|
+
return { kind: 'shell', command: text(input['command']) };
|
|
20
|
+
if (READ_TOOLS.has(tool))
|
|
21
|
+
return { kind: 'read' };
|
|
22
|
+
return { kind: 'other', tool };
|
|
23
|
+
}
|
|
24
|
+
export function parseClaude(event, payload) {
|
|
25
|
+
const p = record(payload);
|
|
26
|
+
const session = text(p['session_id']);
|
|
27
|
+
const cwd = text(p['cwd']);
|
|
28
|
+
if (session === '' || cwd === '')
|
|
29
|
+
return undefined;
|
|
30
|
+
if (event === 'prompt')
|
|
31
|
+
return { event, session, cwd, prompt: text(p['prompt']) };
|
|
32
|
+
if (event === 'tool') {
|
|
33
|
+
return { event, session, cwd, action: toAction(text(p['tool_name']), record(p['tool_input'])) };
|
|
34
|
+
}
|
|
35
|
+
if (event === 'stop')
|
|
36
|
+
return { event, session, cwd };
|
|
37
|
+
return undefined;
|
|
38
|
+
}
|
|
39
|
+
export function renderClaude(output) {
|
|
40
|
+
switch (output.kind) {
|
|
41
|
+
case 'none':
|
|
42
|
+
return '';
|
|
43
|
+
case 'context':
|
|
44
|
+
return JSON.stringify({
|
|
45
|
+
hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: output.text },
|
|
46
|
+
});
|
|
47
|
+
case 'deny':
|
|
48
|
+
return JSON.stringify({
|
|
49
|
+
hookSpecificOutput: {
|
|
50
|
+
hookEventName: 'PreToolUse',
|
|
51
|
+
permissionDecision: 'deny',
|
|
52
|
+
permissionDecisionReason: output.reason,
|
|
53
|
+
},
|
|
54
|
+
});
|
|
55
|
+
case 'block':
|
|
56
|
+
// UserPromptSubmit and Stop both take a top-level block decision.
|
|
57
|
+
return JSON.stringify({ decision: 'block', reason: output.reason });
|
|
58
|
+
case 'notice':
|
|
59
|
+
return JSON.stringify({ systemMessage: output.text });
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
/** The fixed hook config `vyom-gaami init` writes to .claude/settings.json; it never changes. */
|
|
63
|
+
export const CLAUDE_HOOKS = {
|
|
64
|
+
UserPromptSubmit: [
|
|
65
|
+
{ hooks: [{ type: 'command', command: 'vyom-gaami hook prompt --tool claude', timeout: 30 }] },
|
|
66
|
+
],
|
|
67
|
+
PreToolUse: [
|
|
68
|
+
{
|
|
69
|
+
matcher: '*',
|
|
70
|
+
hooks: [{ type: 'command', command: 'vyom-gaami hook tool --tool claude', timeout: 10 }],
|
|
71
|
+
},
|
|
72
|
+
],
|
|
73
|
+
Stop: [
|
|
74
|
+
{ hooks: [{ type: 'command', command: 'vyom-gaami hook stop --tool claude', timeout: 900 }] },
|
|
75
|
+
],
|
|
76
|
+
};
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Codex CLI hooks (UserPromptSubmit, PreToolUse, Stop), from the official hooks reference
|
|
3
|
+
* (work/0005-enforced-method/research.md). Shell and unified exec arrive as `Bash`;
|
|
4
|
+
* `apply_patch` carries the patch text in `tool_input.command`.
|
|
5
|
+
*/
|
|
6
|
+
const record = (value) => typeof value === 'object' && value !== null ? value : {};
|
|
7
|
+
const text = (value) => (typeof value === 'string' ? value : '');
|
|
8
|
+
/** Files an apply_patch touches: added, updated, deleted and move targets. */
|
|
9
|
+
export function patchPaths(patch) {
|
|
10
|
+
const paths = [
|
|
11
|
+
...patch.matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$|^\*\*\* Move to: (.+)$/gm),
|
|
12
|
+
].map((m) => (m[1] ?? m[2] ?? '').trim());
|
|
13
|
+
return [...new Set(paths.filter((p) => p !== ''))];
|
|
14
|
+
}
|
|
15
|
+
export function codexAction(tool, input) {
|
|
16
|
+
if (tool === 'apply_patch' || tool === 'Edit' || tool === 'Write') {
|
|
17
|
+
const paths = patchPaths(text(input['command']));
|
|
18
|
+
return { kind: 'write', paths: paths.length > 0 ? paths : [text(input['file_path'])] };
|
|
19
|
+
}
|
|
20
|
+
if (tool === 'Bash')
|
|
21
|
+
return { kind: 'shell', command: text(input['command']) };
|
|
22
|
+
return { kind: 'other', tool };
|
|
23
|
+
}
|
|
24
|
+
export function parseCodex(event, payload) {
|
|
25
|
+
const p = record(payload);
|
|
26
|
+
const session = text(p['session_id']);
|
|
27
|
+
const cwd = text(p['cwd']);
|
|
28
|
+
if (session === '' || cwd === '')
|
|
29
|
+
return undefined;
|
|
30
|
+
if (event === 'prompt')
|
|
31
|
+
return { event, session, cwd, prompt: text(p['prompt']) };
|
|
32
|
+
if (event === 'tool')
|
|
33
|
+
return {
|
|
34
|
+
event,
|
|
35
|
+
session,
|
|
36
|
+
cwd,
|
|
37
|
+
action: codexAction(text(p['tool_name']), record(p['tool_input'])),
|
|
38
|
+
};
|
|
39
|
+
if (event === 'stop')
|
|
40
|
+
return { event, session, cwd };
|
|
41
|
+
return undefined;
|
|
42
|
+
}
|
|
43
|
+
export function renderCodex(output) {
|
|
44
|
+
switch (output.kind) {
|
|
45
|
+
case 'context':
|
|
46
|
+
return JSON.stringify({
|
|
47
|
+
hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: output.text },
|
|
48
|
+
});
|
|
49
|
+
case 'deny':
|
|
50
|
+
return JSON.stringify({
|
|
51
|
+
hookSpecificOutput: {
|
|
52
|
+
hookEventName: 'PreToolUse',
|
|
53
|
+
permissionDecision: 'deny',
|
|
54
|
+
permissionDecisionReason: output.reason,
|
|
55
|
+
},
|
|
56
|
+
});
|
|
57
|
+
case 'block':
|
|
58
|
+
return JSON.stringify({ decision: 'block', reason: output.reason });
|
|
59
|
+
case 'notice':
|
|
60
|
+
return JSON.stringify({ systemMessage: output.text });
|
|
61
|
+
case 'none':
|
|
62
|
+
// Stop hooks must print JSON when they exit 0.
|
|
63
|
+
return '{}';
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
/** `.codex/hooks.json`, written once by `vyom-gaami init`. */
|
|
67
|
+
export const CODEX_HOOKS = {
|
|
68
|
+
hooks: {
|
|
69
|
+
UserPromptSubmit: [
|
|
70
|
+
{ hooks: [{ type: 'command', command: 'vyom-gaami hook prompt --tool codex', timeout: 30 }] },
|
|
71
|
+
],
|
|
72
|
+
PreToolUse: [
|
|
73
|
+
{ hooks: [{ type: 'command', command: 'vyom-gaami hook tool --tool codex', timeout: 10 }] },
|
|
74
|
+
],
|
|
75
|
+
Stop: [
|
|
76
|
+
{ hooks: [{ type: 'command', command: 'vyom-gaami hook stop --tool codex', timeout: 900 }] },
|
|
77
|
+
],
|
|
78
|
+
},
|
|
79
|
+
};
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cursor hooks (beforeSubmitPrompt, preToolUse, stop), from cursor.com/docs/hooks. Cursor can't
|
|
3
|
+
* add context on a prompt, so the agent learns its phase from deny messages and stop follow-ups.
|
|
4
|
+
*/
|
|
5
|
+
const record = (value) => typeof value === 'object' && value !== null ? value : {};
|
|
6
|
+
const text = (value) => (typeof value === 'string' ? value : '');
|
|
7
|
+
export function cursorAction(tool, input) {
|
|
8
|
+
if (tool === 'Write' || tool === 'Delete' || tool === 'Edit') {
|
|
9
|
+
const path = text(input['file_path']) || text(input['path']) || text(input['target_file']);
|
|
10
|
+
return { kind: 'write', paths: [path] };
|
|
11
|
+
}
|
|
12
|
+
if (tool === 'Shell')
|
|
13
|
+
return { kind: 'shell', command: text(input['command']) };
|
|
14
|
+
if (tool === 'Read' || tool === 'Grep')
|
|
15
|
+
return { kind: 'read' };
|
|
16
|
+
return { kind: 'other', tool };
|
|
17
|
+
}
|
|
18
|
+
export function parseCursor(event, payload) {
|
|
19
|
+
const p = record(payload);
|
|
20
|
+
const session = text(p['conversation_id']);
|
|
21
|
+
const roots = Array.isArray(p['workspace_roots']) ? p['workspace_roots'] : [];
|
|
22
|
+
const cwd = text(p['cwd']) || text(roots[0]);
|
|
23
|
+
if (session === '' || cwd === '')
|
|
24
|
+
return undefined;
|
|
25
|
+
if (event === 'prompt')
|
|
26
|
+
return { event, session, cwd, prompt: text(p['prompt']) };
|
|
27
|
+
if (event === 'tool')
|
|
28
|
+
return {
|
|
29
|
+
event,
|
|
30
|
+
session,
|
|
31
|
+
cwd,
|
|
32
|
+
action: cursorAction(text(p['tool_name']), record(p['tool_input'])),
|
|
33
|
+
};
|
|
34
|
+
if (event === 'stop')
|
|
35
|
+
return { event, session, cwd };
|
|
36
|
+
return undefined;
|
|
37
|
+
}
|
|
38
|
+
export function renderCursor(event, output) {
|
|
39
|
+
if (event === 'prompt')
|
|
40
|
+
return JSON.stringify({ continue: true });
|
|
41
|
+
if (output.kind === 'deny') {
|
|
42
|
+
return JSON.stringify({
|
|
43
|
+
permission: 'deny',
|
|
44
|
+
agent_message: output.reason,
|
|
45
|
+
user_message: output.reason,
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
if (output.kind === 'block')
|
|
49
|
+
return JSON.stringify({ followup_message: output.reason });
|
|
50
|
+
return event === 'tool' ? JSON.stringify({ permission: 'allow' }) : '{}';
|
|
51
|
+
}
|
|
52
|
+
/** `.cursor/hooks.json`, written once by `vyom-gaami init`. failClosed: a broken hook denies. */
|
|
53
|
+
export const CURSOR_HOOKS = {
|
|
54
|
+
version: 1,
|
|
55
|
+
hooks: {
|
|
56
|
+
beforeSubmitPrompt: [{ command: 'vyom-gaami hook prompt --tool cursor', timeout: 30 }],
|
|
57
|
+
preToolUse: [{ command: 'vyom-gaami hook tool --tool cursor', timeout: 10, failClosed: true }],
|
|
58
|
+
stop: [{ command: 'vyom-gaami hook stop --tool cursor', timeout: 900, loop_limit: 20 }],
|
|
59
|
+
},
|
|
60
|
+
};
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { parseClaude, renderClaude } from './claude.js';
|
|
2
|
+
import { parseCodex, renderCodex } from './codex.js';
|
|
3
|
+
import { parseCursor, renderCursor } from './cursor.js';
|
|
4
|
+
export const ADAPTERS = {
|
|
5
|
+
claude: { parse: parseClaude, render: (_event, output) => renderClaude(output) },
|
|
6
|
+
codex: { parse: parseCodex, render: (_event, output) => renderCodex(output) },
|
|
7
|
+
cursor: { parse: parseCursor, render: renderCursor },
|
|
8
|
+
};
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/** HTTP client for the control plane. Never throws: callers decide what failure means. */
|
|
2
|
+
export async function call(server, method, path, body, token, timeoutMs = 20_000) {
|
|
3
|
+
try {
|
|
4
|
+
const response = await fetch(`${server.replace(/\/$/, '')}${path}`, {
|
|
5
|
+
method,
|
|
6
|
+
headers: {
|
|
7
|
+
'content-type': 'application/json',
|
|
8
|
+
...(token === undefined ? {} : { authorization: `Bearer ${token}` }),
|
|
9
|
+
},
|
|
10
|
+
body: method === 'GET' ? null : JSON.stringify(body ?? {}),
|
|
11
|
+
signal: AbortSignal.timeout(timeoutMs),
|
|
12
|
+
});
|
|
13
|
+
if (response.status === 401)
|
|
14
|
+
return { kind: 'logged-out' };
|
|
15
|
+
const parsed = (await response.json().catch(() => ({})));
|
|
16
|
+
return { kind: 'ok', status: response.status, body: parsed };
|
|
17
|
+
}
|
|
18
|
+
catch (error) {
|
|
19
|
+
return { kind: 'unreachable', message: error instanceof Error ? error.message : String(error) };
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
export function authed(credentials) {
|
|
23
|
+
return (method, path, body) => credentials === undefined
|
|
24
|
+
? Promise.resolve({ kind: 'logged-out' })
|
|
25
|
+
: call(credentials.server, method, path, body, credentials.token);
|
|
26
|
+
}
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
import { spawn } from 'node:child_process';
|
|
2
|
+
import { createHash } from 'node:crypto';
|
|
3
|
+
import { readFileSync } from 'node:fs';
|
|
4
|
+
import { join } from 'node:path';
|
|
5
|
+
import { RUNS_TESTS } from '../gaami/contracts.js';
|
|
6
|
+
import { artifactPath, PHASES } from '../gaami/method.js';
|
|
7
|
+
import { command } from '../gaami/pack.js';
|
|
8
|
+
import { classify } from '../gaami/policy.js';
|
|
9
|
+
import { git } from './local.js';
|
|
10
|
+
/** Collects the facts a phase contract needs: git state, artifacts, test exit codes. */
|
|
11
|
+
const TEST_TIMEOUT_MS = 10 * 60_000;
|
|
12
|
+
const STATUS = { A: 'added', D: 'deleted' };
|
|
13
|
+
const readText = (path) => {
|
|
14
|
+
try {
|
|
15
|
+
return readFileSync(path, 'utf8');
|
|
16
|
+
}
|
|
17
|
+
catch {
|
|
18
|
+
return undefined;
|
|
19
|
+
}
|
|
20
|
+
};
|
|
21
|
+
const lines = (text) => text.split('\n').filter((line) => line !== '');
|
|
22
|
+
/** Runs a shell command in the repo; returns its exit code and the last lines of output. */
|
|
23
|
+
function run(root, cmd) {
|
|
24
|
+
return new Promise((done) => {
|
|
25
|
+
const child = spawn('sh', ['-c', cmd], { cwd: root, stdio: ['ignore', 'pipe', 'pipe'] });
|
|
26
|
+
let out = '';
|
|
27
|
+
const keep = (chunk) => {
|
|
28
|
+
out = (out + chunk.toString('utf8')).slice(-20_000);
|
|
29
|
+
};
|
|
30
|
+
child.stdout.on('data', keep);
|
|
31
|
+
child.stderr.on('data', keep);
|
|
32
|
+
const timer = setTimeout(() => child.kill('SIGKILL'), TEST_TIMEOUT_MS);
|
|
33
|
+
child.on('close', (code) => {
|
|
34
|
+
clearTimeout(timer);
|
|
35
|
+
done({ code: code ?? 1, tail: out.split('\n').slice(-30).join('\n') });
|
|
36
|
+
});
|
|
37
|
+
});
|
|
38
|
+
}
|
|
39
|
+
function changes(root, since) {
|
|
40
|
+
const tracked = lines(git(root, ['diff', '--name-status', '--no-renames', since])).map((line) => {
|
|
41
|
+
const [status = 'M', path = ''] = line.split('\t');
|
|
42
|
+
return { path, status: STATUS[status] ?? 'modified' };
|
|
43
|
+
});
|
|
44
|
+
const untracked = lines(git(root, ['ls-files', '--others', '--exclude-standard'])).map((path) => ({ path, status: 'added' }));
|
|
45
|
+
return [...tracked, ...untracked];
|
|
46
|
+
}
|
|
47
|
+
async function tests(root, snapshot) {
|
|
48
|
+
const expectation = RUNS_TESTS[snapshot.item.phase];
|
|
49
|
+
if (expectation === undefined)
|
|
50
|
+
return {};
|
|
51
|
+
const { commands } = snapshot.pack;
|
|
52
|
+
const unit = await run(root, command(commands.unit, snapshot.item.slug));
|
|
53
|
+
const feature = commands.feature === undefined
|
|
54
|
+
? undefined
|
|
55
|
+
: await run(root, command(commands.feature, snapshot.item.slug));
|
|
56
|
+
const failed = unit.code !== 0 ? unit : feature !== undefined && feature.code !== 0 ? feature : undefined;
|
|
57
|
+
const result = {
|
|
58
|
+
testsExit: failed?.code ?? 0,
|
|
59
|
+
testTail: expectation === 'pass' ? failed?.tail : undefined,
|
|
60
|
+
};
|
|
61
|
+
if (snapshot.item.phase !== 'build' || commands.check === undefined)
|
|
62
|
+
return result;
|
|
63
|
+
const check = await run(root, commands.check);
|
|
64
|
+
return {
|
|
65
|
+
...result,
|
|
66
|
+
checkExit: check.code,
|
|
67
|
+
testTail: result.testTail ?? (check.code === 0 ? undefined : check.tail),
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
export async function gather(repo, snapshot) {
|
|
71
|
+
const { root } = repo;
|
|
72
|
+
const { item, pack } = snapshot;
|
|
73
|
+
const changed = changes(root, item.phaseStart);
|
|
74
|
+
const uncommitted = lines(git(root, ['status', '--porcelain'])).map((line) => line.slice(3));
|
|
75
|
+
const testFiles = changed.filter((c) => c.status !== 'deleted' && classify(c.path, pack, item.slug) === 'tests');
|
|
76
|
+
const addedTestLines = testFiles.flatMap((c) => c.status === 'added'
|
|
77
|
+
? lines(readText(join(root, c.path)) ?? '')
|
|
78
|
+
: lines(git(root, ['diff', '-U0', item.phaseStart, '--', c.path]))
|
|
79
|
+
.filter((l) => l.startsWith('+') && !l.startsWith('+++'))
|
|
80
|
+
.map((l) => l.slice(1)));
|
|
81
|
+
const deletedTests = lines(git(root, ['diff', '--name-only', '--diff-filter=D', item.baseCommit])).filter((path) => classify(path, pack, item.slug) === 'tests');
|
|
82
|
+
const artifacts = {};
|
|
83
|
+
for (const phase of PHASES) {
|
|
84
|
+
const path = artifactPath(phase, item.slug);
|
|
85
|
+
const content = path === undefined ? undefined : readText(join(root, path));
|
|
86
|
+
if (path !== undefined && content !== undefined)
|
|
87
|
+
artifacts[path] = createHash('sha256').update(content).digest('hex');
|
|
88
|
+
}
|
|
89
|
+
const own = artifactPath(item.phase, item.slug);
|
|
90
|
+
const testResult = await tests(root, snapshot);
|
|
91
|
+
const facts = {
|
|
92
|
+
phase: item.phase,
|
|
93
|
+
slug: item.slug,
|
|
94
|
+
changed,
|
|
95
|
+
uncommitted,
|
|
96
|
+
artifact: own === undefined ? undefined : readText(join(root, own)),
|
|
97
|
+
addedTestLines,
|
|
98
|
+
deletedTests,
|
|
99
|
+
...(testResult.testsExit === undefined ? {} : { testsExit: testResult.testsExit }),
|
|
100
|
+
...(testResult.checkExit === undefined ? {} : { checkExit: testResult.checkExit }),
|
|
101
|
+
};
|
|
102
|
+
return {
|
|
103
|
+
facts,
|
|
104
|
+
artifacts,
|
|
105
|
+
head: git(root, ['rev-parse', 'HEAD']),
|
|
106
|
+
testTail: testResult.testTail,
|
|
107
|
+
};
|
|
108
|
+
}
|
package/dist/cli/hook.js
ADDED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
import { checkPhase } from '../gaami/contracts.js';
|
|
2
|
+
import { lanePhases, PHASE_SPECS } from '../gaami/method.js';
|
|
3
|
+
import { parsePack } from '../gaami/pack.js';
|
|
4
|
+
import { checkAction } from '../gaami/policy.js';
|
|
5
|
+
/**
|
|
6
|
+
* The hook logic shared by every tool (decision 0009). Prompt: bind the session and load the
|
|
7
|
+
* item's state. Before a tool: check the action against the local snapshot, no network.
|
|
8
|
+
* Stop: run the phase contract and submit evidence; refuse to stop until the phase is done.
|
|
9
|
+
*/
|
|
10
|
+
const none = { kind: 'none' };
|
|
11
|
+
/** Steps to show the agent: where it is, what it may do, how to get on the item's branch. */
|
|
12
|
+
export function briefing(snapshot, branch) {
|
|
13
|
+
const { item } = snapshot;
|
|
14
|
+
const spec = PHASE_SPECS[item.phase];
|
|
15
|
+
const lines = [
|
|
16
|
+
`vyom-gaami: this session works on item ${item.id} "${item.title}" (method ${snapshot.pack.method}).`,
|
|
17
|
+
`Phase: ${item.phase}${item.lane === undefined ? '' : ` (lane ${item.lane}: ${lanePhases(item.lane).join(' → ')})`}.`,
|
|
18
|
+
];
|
|
19
|
+
if (item.status === 'ready')
|
|
20
|
+
lines.push('All phases are done. The PR is next; nothing more to change.');
|
|
21
|
+
else if (item.phaseStatus === 'awaiting') {
|
|
22
|
+
lines.push(`${item.phase} is waiting for a person's approval in Matrix. Don't change anything; tell the person and stop.`);
|
|
23
|
+
}
|
|
24
|
+
else {
|
|
25
|
+
lines.push(`Goal: ${spec.goal}`, `You may change: ${spec.writes.join(', ')}. Commit your work, then stop; the phase is checked when you stop.`);
|
|
26
|
+
}
|
|
27
|
+
if (branch !== item.branch) {
|
|
28
|
+
lines.push(`First switch to the item's branch: git switch ${item.branch} 2>/dev/null || git switch -c ${item.branch} ${item.baseCommit}`);
|
|
29
|
+
}
|
|
30
|
+
return lines.join('\n');
|
|
31
|
+
}
|
|
32
|
+
function pack(repo) {
|
|
33
|
+
if (repo.pack === undefined)
|
|
34
|
+
return undefined;
|
|
35
|
+
const parsed = parsePack(repo.pack);
|
|
36
|
+
return parsed.ok
|
|
37
|
+
? parsed.pack
|
|
38
|
+
: `.vyom-gaami/profile.json is invalid: ${parsed.errors.join('; ')}`;
|
|
39
|
+
}
|
|
40
|
+
async function onPrompt(deps, input) {
|
|
41
|
+
const repo = deps.repo(input.cwd);
|
|
42
|
+
const repoPack = repo === undefined ? undefined : pack(repo);
|
|
43
|
+
if (repo === undefined || repoPack === undefined)
|
|
44
|
+
return none;
|
|
45
|
+
if (typeof repoPack === 'string')
|
|
46
|
+
return {
|
|
47
|
+
kind: 'context',
|
|
48
|
+
text: `vyom-gaami: ${repoPack} Writes are blocked until it is fixed.`,
|
|
49
|
+
};
|
|
50
|
+
const base = await deps.base(repo, repoPack.base);
|
|
51
|
+
const itemRef = /#(\d{4,})\b/.exec(input.prompt)?.[1];
|
|
52
|
+
const result = await deps.bind({
|
|
53
|
+
repo: repo.name,
|
|
54
|
+
tool: deps.tool,
|
|
55
|
+
session: input.session,
|
|
56
|
+
title: input.prompt.slice(0, 200) || 'Untitled',
|
|
57
|
+
base,
|
|
58
|
+
pack: repo.pack,
|
|
59
|
+
...(itemRef === undefined ? {} : { itemRef }),
|
|
60
|
+
});
|
|
61
|
+
if (result.kind === 'logged-out') {
|
|
62
|
+
return {
|
|
63
|
+
kind: 'context',
|
|
64
|
+
text: 'vyom-gaami: not logged in, so changes are blocked. Ask the person to run: vyom-gaami login',
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
if (result.kind === 'unreachable') {
|
|
68
|
+
return {
|
|
69
|
+
kind: 'context',
|
|
70
|
+
text: `vyom-gaami: the control plane is unreachable (${result.message}). Changes are blocked; reading is fine.`,
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
if (result.status !== 200) {
|
|
74
|
+
return {
|
|
75
|
+
kind: 'context',
|
|
76
|
+
text: `vyom-gaami: ${String(result.body['error'] ?? 'refused')}. Changes are blocked.`,
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
const snapshot = result.body['snapshot'];
|
|
80
|
+
deps.writeSnapshot(repo, input.session, snapshot);
|
|
81
|
+
return { kind: 'context', text: briefing(snapshot, deps.branch(repo)) };
|
|
82
|
+
}
|
|
83
|
+
function onTool(deps, input) {
|
|
84
|
+
if (input.action.kind === 'read' || input.action.kind === 'other')
|
|
85
|
+
return none;
|
|
86
|
+
const repo = deps.repo(input.cwd);
|
|
87
|
+
if (repo === undefined || repo.pack === undefined)
|
|
88
|
+
return none;
|
|
89
|
+
const verdict = checkAction(deps.readSnapshot(repo, input.session), input.action, {
|
|
90
|
+
root: repo.root,
|
|
91
|
+
branch: deps.branch(repo),
|
|
92
|
+
home: deps.home,
|
|
93
|
+
now: deps.now(),
|
|
94
|
+
});
|
|
95
|
+
return verdict.allow ? none : { kind: 'deny', reason: `vyom-gaami: ${verdict.reason}` };
|
|
96
|
+
}
|
|
97
|
+
async function onStop(deps, input) {
|
|
98
|
+
const repo = deps.repo(input.cwd);
|
|
99
|
+
const snapshot = repo === undefined ? undefined : deps.readSnapshot(repo, input.session);
|
|
100
|
+
if (repo === undefined || snapshot === undefined)
|
|
101
|
+
return none;
|
|
102
|
+
const { item } = snapshot;
|
|
103
|
+
if (item.status === 'ready' || item.status === 'abandoned' || item.phaseStatus === 'awaiting')
|
|
104
|
+
return none;
|
|
105
|
+
if (deps.branch(repo) !== item.branch) {
|
|
106
|
+
// A question-only session never left its branch: let it end. Otherwise get onto the branch.
|
|
107
|
+
if (item.status === 'draft')
|
|
108
|
+
return none;
|
|
109
|
+
return {
|
|
110
|
+
kind: 'block',
|
|
111
|
+
reason: `vyom-gaami: work item ${item.id} lives on ${item.branch}. Switch: git switch ${item.branch}`,
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
const gathered = await deps.gather(repo, snapshot);
|
|
115
|
+
const contract = checkPhase(gathered.facts, snapshot.pack);
|
|
116
|
+
if (!contract.ok) {
|
|
117
|
+
const tail = gathered.testTail === undefined ? '' : `\nTest output (last lines):\n${gathered.testTail}`;
|
|
118
|
+
return {
|
|
119
|
+
kind: 'block',
|
|
120
|
+
reason: `vyom-gaami: ${item.phase} isn't done:\n- ${contract.findings.join('\n- ')}${tail}`,
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
const result = await deps.evidence(item.id, {
|
|
124
|
+
session: input.session,
|
|
125
|
+
phase: item.phase,
|
|
126
|
+
commit: gathered.head,
|
|
127
|
+
artifacts: gathered.artifacts,
|
|
128
|
+
contract,
|
|
129
|
+
pack: repo.pack,
|
|
130
|
+
...(gathered.facts.artifact === undefined ? {} : { artifactText: gathered.facts.artifact }),
|
|
131
|
+
});
|
|
132
|
+
if (result.kind !== 'ok') {
|
|
133
|
+
return {
|
|
134
|
+
kind: 'notice',
|
|
135
|
+
text: `vyom-gaami: couldn't record ${item.phase} (${result.kind}). Your commits are safe; send a prompt to retry.`,
|
|
136
|
+
};
|
|
137
|
+
}
|
|
138
|
+
if (result.status !== 200) {
|
|
139
|
+
const findings = result.body['findings'] ?? [];
|
|
140
|
+
return {
|
|
141
|
+
kind: 'block',
|
|
142
|
+
reason: `vyom-gaami: ${String(result.body['error'])}${findings.length > 0 ? `\n- ${findings.join('\n- ')}` : ''}`,
|
|
143
|
+
};
|
|
144
|
+
}
|
|
145
|
+
const next = result.body['snapshot'];
|
|
146
|
+
deps.writeSnapshot(repo, input.session, next);
|
|
147
|
+
if (next.item.status === 'ready')
|
|
148
|
+
return {
|
|
149
|
+
kind: 'notice',
|
|
150
|
+
text: `vyom-gaami: item ${item.id} finished every phase. Ready for the PR.`,
|
|
151
|
+
};
|
|
152
|
+
if (next.item.phaseStatus === 'awaiting') {
|
|
153
|
+
return {
|
|
154
|
+
kind: 'notice',
|
|
155
|
+
text: `vyom-gaami: ${item.phase} done; waiting for approval in Matrix (item ${item.id}).`,
|
|
156
|
+
};
|
|
157
|
+
}
|
|
158
|
+
return {
|
|
159
|
+
kind: 'block',
|
|
160
|
+
reason: `vyom-gaami: ${item.phase} accepted. Continue.\n${briefing(next, deps.branch(repo))}`,
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
export async function runHook(deps, input) {
|
|
164
|
+
switch (input.event) {
|
|
165
|
+
case 'prompt':
|
|
166
|
+
return onPrompt(deps, input);
|
|
167
|
+
case 'tool':
|
|
168
|
+
return onTool(deps, input);
|
|
169
|
+
case 'stop':
|
|
170
|
+
return onStop(deps, input);
|
|
171
|
+
}
|
|
172
|
+
}
|
package/dist/cli/init.js
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { METHOD_ID } from '../gaami/method.js';
|
|
2
|
+
import { CLAUDE_HOOKS } from './adapters/claude.js';
|
|
3
|
+
import { CODEX_HOOKS } from './adapters/codex.js';
|
|
4
|
+
import { CURSOR_HOOKS } from './adapters/cursor.js';
|
|
5
|
+
const START = '<!-- vyom-gaami:start -->';
|
|
6
|
+
const END = '<!-- vyom-gaami:end -->';
|
|
7
|
+
export const AGENTS_BLOCK = `${START}
|
|
8
|
+
## vyom-gaami
|
|
9
|
+
|
|
10
|
+
This repo follows the vyom-gaami method (\`${METHOD_ID}\`). Hooks in \`.claude/\`, \`.codex/\` and
|
|
11
|
+
\`.cursor/\` hold every coding agent to it. Each piece of work is a work item that moves through
|
|
12
|
+
phases (triage → … → harden). Each phase may only change certain files, and you can't stop until
|
|
13
|
+
its check passes. Read the hook messages: they say which phase you're in and what to do next.
|
|
14
|
+
Approvals happen in Matrix. Never edit \`.vyom-gaami/\`, hook files or CI to get around a check.
|
|
15
|
+
${END}`;
|
|
16
|
+
const OURS = (command) => typeof command === 'string' && command.startsWith('vyom-gaami hook');
|
|
17
|
+
/** Removes vyom-gaami's entries from one event's list, keeping everyone else's. */
|
|
18
|
+
function withoutOurs(entries) {
|
|
19
|
+
if (!Array.isArray(entries))
|
|
20
|
+
return [];
|
|
21
|
+
return entries
|
|
22
|
+
.map((entry) => Array.isArray(entry.hooks)
|
|
23
|
+
? { ...entry, hooks: entry.hooks.filter((h) => !OURS(h.command)) }
|
|
24
|
+
: entry)
|
|
25
|
+
.filter((entry) => !OURS(entry.command) && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
|
|
26
|
+
}
|
|
27
|
+
function mergeHooks(existing, ours, extra = {}) {
|
|
28
|
+
let parsed = {};
|
|
29
|
+
try {
|
|
30
|
+
parsed = existing === undefined ? {} : JSON.parse(existing);
|
|
31
|
+
}
|
|
32
|
+
catch {
|
|
33
|
+
throw new Error('an existing hook file is not valid JSON; fix it first');
|
|
34
|
+
}
|
|
35
|
+
const current = (parsed['hooks'] ?? {});
|
|
36
|
+
const hooks = { ...current };
|
|
37
|
+
for (const [event, entries] of Object.entries(ours))
|
|
38
|
+
hooks[event] = [...withoutOurs(current[event]), ...entries];
|
|
39
|
+
return `${JSON.stringify({ ...parsed, ...extra, hooks }, null, 2)}\n`;
|
|
40
|
+
}
|
|
41
|
+
/** The repo's unit-test command, guessed from its lockfile and package.json. */
|
|
42
|
+
export function guessUnit(files) {
|
|
43
|
+
const pkg = files['package.json'];
|
|
44
|
+
if (pkg === undefined)
|
|
45
|
+
return undefined;
|
|
46
|
+
const scripts = JSON.parse(pkg).scripts ?? {};
|
|
47
|
+
if (scripts['test'] === undefined)
|
|
48
|
+
return undefined;
|
|
49
|
+
if (files['pnpm-lock.yaml'] !== undefined)
|
|
50
|
+
return 'pnpm test';
|
|
51
|
+
if (files['yarn.lock'] !== undefined)
|
|
52
|
+
return 'yarn test';
|
|
53
|
+
return 'npm test';
|
|
54
|
+
}
|
|
55
|
+
function agents(existing) {
|
|
56
|
+
if (existing === undefined)
|
|
57
|
+
return `# AGENTS.md\n\n${AGENTS_BLOCK}\n`;
|
|
58
|
+
const start = existing.indexOf(START);
|
|
59
|
+
const end = existing.indexOf(END);
|
|
60
|
+
if (start !== -1 && end > start)
|
|
61
|
+
return `${existing.slice(0, start)}${AGENTS_BLOCK}${existing.slice(end + END.length)}`;
|
|
62
|
+
return `${existing.trimEnd()}\n\n${AGENTS_BLOCK}\n`;
|
|
63
|
+
}
|
|
64
|
+
export function planInit(files) {
|
|
65
|
+
const warnings = [];
|
|
66
|
+
const writes = {};
|
|
67
|
+
if (files['.vyom-gaami/profile.json'] === undefined) {
|
|
68
|
+
const unit = guessUnit(files);
|
|
69
|
+
if (unit === undefined)
|
|
70
|
+
warnings.push('No test script found: set commands.unit in .vyom-gaami/profile.json.');
|
|
71
|
+
writes['.vyom-gaami/profile.json'] =
|
|
72
|
+
`${JSON.stringify({ method: METHOD_ID, commands: { unit: unit ?? 'echo "set commands.unit" && exit 1' } }, null, 2)}\n`;
|
|
73
|
+
}
|
|
74
|
+
writes['.claude/settings.json'] = mergeHooks(files['.claude/settings.json'], CLAUDE_HOOKS);
|
|
75
|
+
writes['.codex/hooks.json'] = mergeHooks(files['.codex/hooks.json'], CODEX_HOOKS.hooks);
|
|
76
|
+
writes['.cursor/hooks.json'] = mergeHooks(files['.cursor/hooks.json'], CURSOR_HOOKS.hooks, {
|
|
77
|
+
version: 1,
|
|
78
|
+
});
|
|
79
|
+
writes['AGENTS.md'] = agents(files['AGENTS.md']);
|
|
80
|
+
for (const [path, content] of Object.entries(writes))
|
|
81
|
+
if (files[path] === content)
|
|
82
|
+
delete writes[path];
|
|
83
|
+
return { writes, warnings };
|
|
84
|
+
}
|
|
85
|
+
export const INIT_FILES = [
|
|
86
|
+
'.vyom-gaami/profile.json',
|
|
87
|
+
'.claude/settings.json',
|
|
88
|
+
'.codex/hooks.json',
|
|
89
|
+
'.cursor/hooks.json',
|
|
90
|
+
'AGENTS.md',
|
|
91
|
+
'package.json',
|
|
92
|
+
'pnpm-lock.yaml',
|
|
93
|
+
'yarn.lock',
|
|
94
|
+
];
|