@venizia/vulcan 0.3.12 → 0.3.13
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/base/skills/build-a-feature/SKILL.md +3 -3
- package/base/skills/knowledge-sync/SKILL.md +11 -13
- package/base/skills/knowledge-sync/knowledge-sync.workflow.js +4 -2
- package/base/skills/knowledge-sync/references/workflow.md +1 -1
- package/package.json +4 -4
- package/src/create/add-app.ts +1 -16
- package/src/create/add-lib.ts +1 -16
- package/src/create/files.ts +0 -2
- package/src/create/init-monorepo.ts +1 -10
- package/src/create/workspace.ts +0 -3
- package/src/router.ts +11 -1
- package/src/ui/keyboard.ts +12 -3
|
@@ -32,7 +32,7 @@ Copy it into your reply and tick each box when its criterion holds:
|
|
|
32
32
|
- [ ] 4. Slices planned - each slice names one behaviour, its seam, its files
|
|
33
33
|
- [ ] 5. Slices built - every slice went red, then green; every import came from `symbol`
|
|
34
34
|
- [ ] 6. Checks green - typecheck, lint, test, vulcan doctor passed; the real behaviour shown
|
|
35
|
-
- [ ] 7. Knowledge current - each changed fact is in the bundle
|
|
35
|
+
- [ ] 7. Knowledge current - each changed fact is in the bundle
|
|
36
36
|
- [ ] 8. Diff reviewed - the whole diff read once, findings fixed, summary given
|
|
37
37
|
```
|
|
38
38
|
|
|
@@ -109,9 +109,9 @@ Done when every check passed in this session and the behaviour is shown.
|
|
|
109
109
|
## 7. Update knowledge
|
|
110
110
|
|
|
111
111
|
Each fact about the project that changed - a new concept, a decision, a gotcha - goes into the
|
|
112
|
-
knowledge bundle
|
|
112
|
+
knowledge bundle in the same change.
|
|
113
113
|
|
|
114
|
-
Done when the bundle
|
|
114
|
+
Done when the bundle matches the change.
|
|
115
115
|
|
|
116
116
|
## 8. Review and hand over
|
|
117
117
|
|
|
@@ -26,7 +26,7 @@ Copy it into your reply and tick it off:
|
|
|
26
26
|
- [ ] 3. Targets built, workflow run
|
|
27
27
|
- [ ] 4. Gaps decided
|
|
28
28
|
- [ ] 5. Gates green (loop until they are)
|
|
29
|
-
- [ ] 6.
|
|
29
|
+
- [ ] 6. Reported
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
## 1. Prerequisites
|
|
@@ -39,9 +39,10 @@ Copy it into your reply and tick it off:
|
|
|
39
39
|
|
|
40
40
|
1. `bun x --no-install vulcan x okf gen`, then `vulcan x okf check --strict` - it must pass before
|
|
41
41
|
anything else, so no verifier chases a fact `gen` fixes.
|
|
42
|
-
2. Anchor the last sync by commit, never by date:
|
|
43
|
-
`LAST_SYNC=$(git log -1 --format=%H
|
|
44
|
-
|
|
42
|
+
2. Anchor the last sync by commit, never by date: the last commit that touched the bundle,
|
|
43
|
+
`LAST_SYNC=$(git log -1 --format=%H -- <bundle>)`, and its date `SINCE=$(git log -1 --format=%cs -- <bundle>)`
|
|
44
|
+
(a label for the workflow). The user may name another commit or date instead - use theirs. Empty:
|
|
45
|
+
no sync yet - run `full`, or anchor on the commit that added `<bundle>/index.md`. A bare
|
|
45
46
|
`--since=<date>` is wrong: git reads today's date as "now" and returns nothing.
|
|
46
47
|
3. Changed areas: `git log $LAST_SYNC..HEAD --no-merges --name-only --format= -- <package paths> Makefile make/ scripts/ .github/`,
|
|
47
48
|
plus `git diff HEAD --stat` for uncommitted code. Commits that touch only the bundle or `docs/` are
|
|
@@ -50,8 +51,8 @@ Copy it into your reply and tick it off:
|
|
|
50
51
|
|
|
51
52
|
## 3. Targets and the workflow
|
|
52
53
|
|
|
53
|
-
Mode: `delta` by default; `full` when asked (monthly, quarterly, "full") or when the last
|
|
54
|
-
|
|
54
|
+
Mode: `delta` by default; `full` when asked (monthly, quarterly, "full") or when the last commit
|
|
55
|
+
that touched the bundle (`SINCE`) is over 30 days old. Build the targets and run the workflow as
|
|
55
56
|
[references/workflow.md](references/workflow.md) describes - one target per changed area, from the
|
|
56
57
|
area map when the project has one, else from each concept's `resource`.
|
|
57
58
|
|
|
@@ -70,11 +71,8 @@ to it. Never lose a unique fact.
|
|
|
70
71
|
|
|
71
72
|
A gate that fails: fix what it names, run all three again. Stop only when all three pass.
|
|
72
73
|
|
|
73
|
-
## 6.
|
|
74
|
+
## 6. Report
|
|
74
75
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
2. Report in the user's language: gate status and scale first (findings applied, files, claims
|
|
79
|
-
confirmed), then each notable correction (was -> is, with its witness), new or merged concepts,
|
|
80
|
-
and anything an applier skipped, with the reason. Do not commit.
|
|
76
|
+
Report in the user's language: gate status and scale first (findings applied, files, claims
|
|
77
|
+
confirmed), then each notable correction (was -> is, with its witness), new or merged concepts, and
|
|
78
|
+
anything an applier skipped, with the reason. Do not commit.
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
// args = {
|
|
7
7
|
// repo: '/abs/path/to/project', // repo root - `git rev-parse --show-toplevel`
|
|
8
8
|
// mode: 'delta' | 'full',
|
|
9
|
-
// since: 'YYYY-MM-DD', // last sync date (display label only)
|
|
9
|
+
// since: 'YYYY-MM-DD', // last sync date (display label only): git log -1 --format=%cs -- <bundle>
|
|
10
10
|
// gitRange: '<hash>..HEAD', // commit range since the last sync - what verifiers actually diff
|
|
11
11
|
// bundle: '.agents/knowledge', // the manifest's knowledge.bundle
|
|
12
12
|
// brand: 'ACME', // the manifest's name, upper case - the spelling prose keeps
|
|
@@ -47,7 +47,9 @@ if (!REPO) {
|
|
|
47
47
|
throw new Error('args.repo (repo root, from `git rev-parse --show-toplevel`) is required');
|
|
48
48
|
}
|
|
49
49
|
if (!since) {
|
|
50
|
-
throw new Error(
|
|
50
|
+
throw new Error(
|
|
51
|
+
'args.since (YYYY-MM-DD, the date of the last commit that touched the bundle: git log -1 --format=%cs -- <bundle>) is required',
|
|
52
|
+
);
|
|
51
53
|
}
|
|
52
54
|
if (!gitRange) {
|
|
53
55
|
throw new Error(
|
|
@@ -26,7 +26,7 @@ Workflow({
|
|
|
26
26
|
args: {
|
|
27
27
|
repo: '<git rev-parse --show-toplevel>',
|
|
28
28
|
mode: '<delta|full>',
|
|
29
|
-
since: '<
|
|
29
|
+
since: '<git log -1 --format=%cs -- <bundle>>', // a label in prompts and the report
|
|
30
30
|
gitRange: '<LAST_SYNC hash>..HEAD', // what the verifiers diff
|
|
31
31
|
bundle: '<manifest knowledge.bundle>',
|
|
32
32
|
brand: '<manifest name, upper case>',
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.13",
|
|
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": {
|
|
@@ -39,13 +39,13 @@
|
|
|
39
39
|
"access": "public"
|
|
40
40
|
},
|
|
41
41
|
"scripts": {
|
|
42
|
-
"force-update": "sh ../../scripts/force-update.sh",
|
|
42
|
+
"force-update": "sh ../../scripts/build/force-update.sh",
|
|
43
43
|
"test": "bun test"
|
|
44
44
|
},
|
|
45
45
|
"dependencies": {
|
|
46
46
|
"@clack/prompts": "1.8.1",
|
|
47
|
-
"@venizia/vulcan-atlas": "0.3.
|
|
48
|
-
"@venizia/vulcan-okf": "0.3.
|
|
47
|
+
"@venizia/vulcan-atlas": "0.3.13",
|
|
48
|
+
"@venizia/vulcan-okf": "0.3.13",
|
|
49
49
|
"zod": "^4.6.7"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
package/src/create/add-app.ts
CHANGED
|
@@ -8,7 +8,7 @@ import { addLibrary } from './add-lib.ts';
|
|
|
8
8
|
import { runAppChecks } from './checks.ts';
|
|
9
9
|
import { AppSides, CreateFlags } from './common/index.ts';
|
|
10
10
|
import type { IAppsBlock, ILocatedPreset, IPresetSpec, TAppSide } from './common/index.ts';
|
|
11
|
-
import {
|
|
11
|
+
import { writeFile } from './files.ts';
|
|
12
12
|
import { recordedPresetOf } from './lib-preset.ts';
|
|
13
13
|
import { renderManifestJson } from './manifest-json.ts';
|
|
14
14
|
import { menusAvailable, promptSelect } from '../ui/index.ts';
|
|
@@ -42,7 +42,6 @@ import {
|
|
|
42
42
|
renderAppConcept,
|
|
43
43
|
renderAppManifest,
|
|
44
44
|
renderKnowledgeIndex,
|
|
45
|
-
renderLogEntry,
|
|
46
45
|
replaceAppsBlock,
|
|
47
46
|
} from './workspace.ts';
|
|
48
47
|
|
|
@@ -628,20 +627,6 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
|
|
|
628
627
|
: renderKnowledgeIndex({ project, apps: [{ name: app, summary: preset.summary }] }),
|
|
629
628
|
});
|
|
630
629
|
|
|
631
|
-
const logPath = join(cwd, KNOWLEDGE_DIRECTORY, 'log.md');
|
|
632
|
-
const logEntry = renderLogEntry({
|
|
633
|
-
date: today(),
|
|
634
|
-
text: `added ${folder}/${app} from the ${packageName} ${packageVersion} preset`,
|
|
635
|
-
});
|
|
636
|
-
|
|
637
|
-
writeFile({
|
|
638
|
-
root: cwd,
|
|
639
|
-
path: `${KNOWLEDGE_DIRECTORY}/log.md`,
|
|
640
|
-
content: existsSync(logPath)
|
|
641
|
-
? `${readFileSync(logPath, 'utf8').trimEnd()}\n\n${logEntry}`
|
|
642
|
-
: `# ${project} knowledge log\n\n${logEntry}`,
|
|
643
|
-
});
|
|
644
|
-
|
|
645
630
|
for (const step of [
|
|
646
631
|
() => runBun({ cwd, args: ['install'], label: 'bun install' }),
|
|
647
632
|
// The installed CLI syncs, so the project is wired to the version it pins.
|
package/src/create/add-lib.ts
CHANGED
|
@@ -6,7 +6,7 @@ import { readWorkspaceGlobs } from '../init/index.ts';
|
|
|
6
6
|
import { runAppChecks } from './checks.ts';
|
|
7
7
|
import { CreateConstants, CreateFlags } from './common/index.ts';
|
|
8
8
|
import type { IAppsBlock, ILocatedPreset, IPresetSpec } from './common/index.ts';
|
|
9
|
-
import {
|
|
9
|
+
import { writeFile } from './files.ts';
|
|
10
10
|
import { readLibPreset } from './lib-preset.ts';
|
|
11
11
|
import { renderManifestJson } from './manifest-json.ts';
|
|
12
12
|
import type { TLibPreset } from './lib-preset.ts';
|
|
@@ -22,7 +22,6 @@ import {
|
|
|
22
22
|
renderKnowledgeIndex,
|
|
23
23
|
renderLibConcept,
|
|
24
24
|
renderLibManifest,
|
|
25
|
-
renderLogEntry,
|
|
26
25
|
replaceAppsBlock,
|
|
27
26
|
} from './workspace.ts';
|
|
28
27
|
|
|
@@ -303,20 +302,6 @@ export const addLibrary = async (opts: {
|
|
|
303
302
|
: renderKnowledgeIndex({ project, apps: [{ name: libName, summary: lib.summary }] }),
|
|
304
303
|
});
|
|
305
304
|
|
|
306
|
-
const logPath = join(cwd, KNOWLEDGE_DIRECTORY, 'log.md');
|
|
307
|
-
const logEntry = renderLogEntry({
|
|
308
|
-
date: today(),
|
|
309
|
-
text: `added ${path} from the ${located.packageName} ${located.packageVersion} preset (lib kind)`,
|
|
310
|
-
});
|
|
311
|
-
|
|
312
|
-
writeFile({
|
|
313
|
-
root: cwd,
|
|
314
|
-
path: `${KNOWLEDGE_DIRECTORY}/log.md`,
|
|
315
|
-
content: existsSync(logPath)
|
|
316
|
-
? `${readFileSync(logPath, 'utf8').trimEnd()}\n\n${logEntry}`
|
|
317
|
-
: `# ${project} knowledge log\n\n${logEntry}`,
|
|
318
|
-
});
|
|
319
|
-
|
|
320
305
|
for (const step of [
|
|
321
306
|
() => runBun({ cwd, args: ['install'], label: 'bun install' }),
|
|
322
307
|
() =>
|
package/src/create/files.ts
CHANGED
|
@@ -1,8 +1,6 @@
|
|
|
1
1
|
import { mkdirSync, writeFileSync } from 'node:fs';
|
|
2
2
|
import { dirname, join } from 'node:path';
|
|
3
3
|
|
|
4
|
-
export const today = (): string => new Date().toISOString().slice(0, 10);
|
|
5
|
-
|
|
6
4
|
export const writeFile = (opts: { root: string; path: string; content: string }): void => {
|
|
7
5
|
mkdirSync(dirname(join(opts.root, opts.path)), { recursive: true });
|
|
8
6
|
writeFileSync(join(opts.root, opts.path), opts.content);
|
|
@@ -11,7 +11,7 @@ import type {
|
|
|
11
11
|
IPresetSpec,
|
|
12
12
|
TAppSide,
|
|
13
13
|
} from './common/index.ts';
|
|
14
|
-
import {
|
|
14
|
+
import { writeFile } from './files.ts';
|
|
15
15
|
import { recordedPresetOf } from './lib-preset.ts';
|
|
16
16
|
import { renderBunfig } from './bunfig.ts';
|
|
17
17
|
import { renderDockerignore } from './dockerignore.ts';
|
|
@@ -36,7 +36,6 @@ import {
|
|
|
36
36
|
renderAppConcept,
|
|
37
37
|
renderAppManifest,
|
|
38
38
|
renderKnowledgeIndex,
|
|
39
|
-
renderLogEntry,
|
|
40
39
|
renderRootManifest,
|
|
41
40
|
presetSpecOf,
|
|
42
41
|
renderVulcanConfig,
|
|
@@ -196,14 +195,6 @@ const writeMonorepo = (opts: {
|
|
|
196
195
|
presetPackage: packageName,
|
|
197
196
|
}),
|
|
198
197
|
});
|
|
199
|
-
writeFile({
|
|
200
|
-
root,
|
|
201
|
-
path: '.agents/knowledge/log.md',
|
|
202
|
-
content: `# ${project} knowledge log\n\n${renderLogEntry({
|
|
203
|
-
date: today(),
|
|
204
|
-
text: `created from the ${packageName} ${packageVersion} preset: ${folder}/${app}`,
|
|
205
|
-
})}`,
|
|
206
|
-
});
|
|
207
198
|
};
|
|
208
199
|
|
|
209
200
|
const runCreate = async (opts: {
|
package/src/create/workspace.ts
CHANGED
|
@@ -493,9 +493,6 @@ export const renderAppConcept = (opts: {
|
|
|
493
493
|
...renderAtlasLookups({ kind: opts.app.side }),
|
|
494
494
|
].join('\n');
|
|
495
495
|
|
|
496
|
-
export const renderLogEntry = (opts: { date: string; text: string }): string =>
|
|
497
|
-
`## ${opts.date}\n\n- ${opts.text}\n`;
|
|
498
|
-
|
|
499
496
|
export const pickPort = (opts: { preferred: number; used: number[] }): number => {
|
|
500
497
|
let port = opts.preferred;
|
|
501
498
|
|
package/src/router.ts
CHANGED
|
@@ -3,6 +3,7 @@ import { COMMAND_HANDLERS } from './commands/index.ts';
|
|
|
3
3
|
import { runHelpCommand } from './commands/help.command.ts';
|
|
4
4
|
import { ExitCodes, UpgradeFlags, VulcanCommands } from './common/index.ts';
|
|
5
5
|
import { CreateFlags } from './create/common/index.ts';
|
|
6
|
+
import { PipedInputRefusal } from './ui/keyboard.ts';
|
|
6
7
|
|
|
7
8
|
const HELP_ALIASES = new Set(['--help', '-h']);
|
|
8
9
|
const VERSION_ALIASES = new Set(['--version', '-v']);
|
|
@@ -128,5 +129,14 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
|
|
|
128
129
|
}
|
|
129
130
|
}
|
|
130
131
|
|
|
131
|
-
|
|
132
|
+
try {
|
|
133
|
+
return await handler({ args, cwd: opts.cwd });
|
|
134
|
+
} catch (error) {
|
|
135
|
+
// The refusal is already printed; every `finally` between the menu and here has run.
|
|
136
|
+
if (error instanceof PipedInputRefusal) {
|
|
137
|
+
return ExitCodes.FAILURE;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
throw error;
|
|
141
|
+
}
|
|
132
142
|
};
|
package/src/ui/keyboard.ts
CHANGED
|
@@ -5,14 +5,23 @@ const REFUSAL = [
|
|
|
5
5
|
'Pass the flags instead (for example --agents claude,omp; see --help of the command), or set TERM=dumb to keep the plain line questions.',
|
|
6
6
|
].join('\n');
|
|
7
7
|
|
|
8
|
+
/** The command was given piped lines where a menu needs key presses; the way out is already printed. */
|
|
9
|
+
export class PipedInputRefusal extends Error {}
|
|
10
|
+
|
|
8
11
|
/**
|
|
9
12
|
* A keyboard in raw mode sends CR for Enter, never LF. LF means the answers were piped in (a script
|
|
10
13
|
* feeding a pty), and a menu would wait for a key that never comes. So while a menu is open, the first
|
|
11
|
-
* LF restores the terminal and ends the
|
|
14
|
+
* LF restores the terminal, prints the way out and ends the menu with a `PipedInputRefusal`: a
|
|
15
|
+
* refusal, not a hang. It is thrown, not `process.exit`, so the `finally` blocks of the flow run (the
|
|
16
|
+
* scratch folder of a preset is removed) and the router turns it into exit code 1.
|
|
12
17
|
*/
|
|
13
18
|
export const guardAgainstPipedLines = async <TResult>(
|
|
14
19
|
run: () => Promise<TResult>,
|
|
15
20
|
): Promise<TResult> => {
|
|
21
|
+
let refuseMenu: (error: PipedInputRefusal) => void = () => {};
|
|
22
|
+
const refused = new Promise<never>((_resolve, reject) => {
|
|
23
|
+
refuseMenu = reject;
|
|
24
|
+
});
|
|
16
25
|
const refuse = (chunk: Buffer | string): void => {
|
|
17
26
|
const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
|
|
18
27
|
|
|
@@ -26,13 +35,13 @@ export const guardAgainstPipedLines = async <TResult>(
|
|
|
26
35
|
|
|
27
36
|
process.stdout.write(SHOW_CURSOR);
|
|
28
37
|
process.stderr.write(`\n${REFUSAL}\n`);
|
|
29
|
-
|
|
38
|
+
refuseMenu(new PipedInputRefusal(REFUSAL));
|
|
30
39
|
};
|
|
31
40
|
|
|
32
41
|
process.stdin.on('data', refuse);
|
|
33
42
|
|
|
34
43
|
try {
|
|
35
|
-
return await run();
|
|
44
|
+
return await Promise.race([run(), refused]);
|
|
36
45
|
} finally {
|
|
37
46
|
process.stdin.off('data', refuse);
|
|
38
47
|
}
|