@venizia/vulcan 0.3.12 → 0.4.0

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.
@@ -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 and its log
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 and its log in the same change.
112
+ knowledge bundle in the same change.
113
113
 
114
- Done when the bundle and its log match the change.
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. Log entry written; reported
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 -G '^## [0-9-]+ - knowledge-sync' -- <bundle>/log.md)`.
44
- Empty: no sync yet - run `full`, or anchor on the commit that added `<bundle>/index.md`. A bare
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 full sync
54
- in `log.md` is over 30 days old. Build the targets and run the workflow as
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. Log and report
74
+ ## 6. Report
74
75
 
75
- 1. Prepend to `<bundle>/log.md`: `## YYYY-MM-DD - knowledge-sync (<mode>): <summary>` - the
76
- `knowledge-sync` word is what the next sync anchors on - then one line of method (verifiers,
77
- findings, confirmed, files touched) and bullets for the corrections that change how someone works.
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), read from log.md
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('args.since (YYYY-MM-DD, last sync date from log.md) is required');
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: '<YYYY-MM-DD of the last sync>', // a label in prompts and the log
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.12",
3
+ "version": "0.4.0",
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,18 +39,18 @@
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.12",
48
- "@venizia/vulcan-okf": "0.3.12",
47
+ "@venizia/vulcan-atlas": "0.4.0",
48
+ "@venizia/vulcan-okf": "0.4.0",
49
49
  "zod": "^4.6.7"
50
50
  },
51
51
  "devDependencies": {
52
52
  "@types/bun": "1.4.3",
53
- "@venizia/dev-configs": "0.3.5",
53
+ "@venizia/dev-configs": "0.4.0",
54
54
  "eslint": "10.13.0",
55
55
  "oxlint": "1.89.0",
56
56
  "oxlint-tsgolint": "7.0.2004",
@@ -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 { today, writeFile } from './files.ts';
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.
@@ -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 { today, writeFile } from './files.ts';
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
  () =>
@@ -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 { today, writeFile } from './files.ts';
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: {
@@ -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
- return handler({ args, cwd: opts.cwd });
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
  };
@@ -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 command with the way out: a refusal, not a hang.
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
- process.exit(1);
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
  }