@venizia/vulcan 0.3.11 → 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/agents.json CHANGED
@@ -3,15 +3,9 @@
3
3
  "id": "claude",
4
4
  "name": "Claude Code",
5
5
  "detect": {
6
- "binaries": [
7
- "claude"
8
- ],
9
- "homeDirs": [
10
- "~/.claude"
11
- ],
12
- "projectDirs": [
13
- ".claude"
14
- ]
6
+ "binaries": ["claude"],
7
+ "homeDirs": ["~/.claude"],
8
+ "projectDirs": [".claude"]
15
9
  },
16
10
  "instructions": {
17
11
  "nativeAgentsMd": false,
@@ -35,15 +29,9 @@
35
29
  "id": "omp",
36
30
  "name": "omp (oh-my-pi)",
37
31
  "detect": {
38
- "binaries": [
39
- "omp"
40
- ],
41
- "homeDirs": [
42
- "~/.omp"
43
- ],
44
- "projectDirs": [
45
- ".omp"
46
- ]
32
+ "binaries": ["omp"],
33
+ "homeDirs": ["~/.omp"],
34
+ "projectDirs": [".omp"]
47
35
  },
48
36
  "instructions": {
49
37
  "nativeAgentsMd": true,
@@ -64,15 +52,9 @@
64
52
  "id": "codex",
65
53
  "name": "Codex",
66
54
  "detect": {
67
- "binaries": [
68
- "codex"
69
- ],
70
- "homeDirs": [
71
- "~/.codex"
72
- ],
73
- "projectDirs": [
74
- ".codex"
75
- ]
55
+ "binaries": ["codex"],
56
+ "homeDirs": ["~/.codex"],
57
+ "projectDirs": [".codex"]
76
58
  },
77
59
  "instructions": {
78
60
  "nativeAgentsMd": true,
@@ -95,16 +77,9 @@
95
77
  "id": "cursor",
96
78
  "name": "Cursor",
97
79
  "detect": {
98
- "binaries": [
99
- "cursor",
100
- "cursor-agent"
101
- ],
102
- "homeDirs": [
103
- "~/.cursor"
104
- ],
105
- "projectDirs": [
106
- ".cursor"
107
- ]
80
+ "binaries": ["cursor", "cursor-agent"],
81
+ "homeDirs": ["~/.cursor"],
82
+ "projectDirs": [".cursor"]
108
83
  },
109
84
  "instructions": {
110
85
  "nativeAgentsMd": true,
@@ -125,9 +100,7 @@
125
100
  "id": "copilot-cli",
126
101
  "name": "Copilot CLI",
127
102
  "detect": {
128
- "binaries": [
129
- "copilot"
130
- ],
103
+ "binaries": ["copilot"],
131
104
  "homeDirs": [],
132
105
  "projectDirs": []
133
106
  },
@@ -151,9 +124,7 @@
151
124
  "name": "Copilot in VS Code",
152
125
  "detect": {
153
126
  "binaries": [],
154
- "homeDirs": [
155
- "~/.vscode/extensions/github.copilot-chat-*"
156
- ],
127
+ "homeDirs": ["~/.vscode/extensions/github.copilot-chat-*"],
157
128
  "projectDirs": []
158
129
  },
159
130
  "instructions": {
@@ -175,12 +146,8 @@
175
146
  "id": "antigravity",
176
147
  "name": "Antigravity CLI",
177
148
  "detect": {
178
- "binaries": [
179
- "agy"
180
- ],
181
- "homeDirs": [
182
- "~/.gemini/antigravity-cli"
183
- ],
149
+ "binaries": ["agy"],
150
+ "homeDirs": ["~/.gemini/antigravity-cli"],
184
151
  "projectDirs": []
185
152
  },
186
153
  "instructions": {
@@ -202,15 +169,9 @@
202
169
  "id": "pi",
203
170
  "name": "Pi",
204
171
  "detect": {
205
- "binaries": [
206
- "pi"
207
- ],
208
- "homeDirs": [
209
- "~/.pi/agent"
210
- ],
211
- "projectDirs": [
212
- ".pi"
213
- ]
172
+ "binaries": ["pi"],
173
+ "homeDirs": ["~/.pi/agent"],
174
+ "projectDirs": [".pi"]
214
175
  },
215
176
  "instructions": {
216
177
  "nativeAgentsMd": true,
@@ -1,8 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
3
- "enabledMcpjsonServers": [
4
- "atlas"
5
- ],
3
+ "enabledMcpjsonServers": ["atlas"],
6
4
  "hooks": {
7
5
  "SessionStart": [
8
6
  {
@@ -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,34 +1,25 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.3.11",
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
- "repository": {
7
- "type": "git",
8
- "url": "git+https://github.com/VENIZIA-AI/vulcan.git",
9
- "directory": "packages/cli"
10
- },
11
6
  "bugs": {
12
7
  "url": "https://github.com/VENIZIA-AI/vulcan/issues"
13
8
  },
9
+ "license": "MIT",
14
10
  "author": {
15
11
  "name": "VENIZIA AI Developer",
16
12
  "email": "developer@venizia.ai",
17
13
  "url": "https://venizia.ai"
18
14
  },
19
- "license": "MIT",
20
- "type": "module",
21
- "engines": {
22
- "bun": ">=1.4"
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "git+https://github.com/VENIZIA-AI/vulcan.git",
18
+ "directory": "packages/cli"
23
19
  },
24
20
  "bin": {
25
21
  "vulcan": "./src/cli.ts"
26
22
  },
27
- "exports": {
28
- ".": "./src/index.ts",
29
- "./okf": "./src/okf.ts",
30
- "./package.json": "./package.json"
31
- },
32
23
  "files": [
33
24
  "README.md",
34
25
  "LICENSE.md",
@@ -37,27 +28,35 @@
37
28
  "!**/__tests__",
38
29
  "!**/*.tsbuildinfo"
39
30
  ],
31
+ "type": "module",
32
+ "sideEffects": false,
33
+ "exports": {
34
+ ".": "./src/index.ts",
35
+ "./okf": "./src/okf.ts",
36
+ "./package.json": "./package.json"
37
+ },
40
38
  "publishConfig": {
41
39
  "access": "public"
42
40
  },
43
41
  "scripts": {
44
- "force-update": "sh ../../scripts/force-update.sh",
42
+ "force-update": "sh ../../scripts/build/force-update.sh",
45
43
  "test": "bun test"
46
44
  },
47
45
  "dependencies": {
48
46
  "@clack/prompts": "1.8.1",
49
- "@venizia/vulcan-atlas": "0.3.11",
50
- "@venizia/vulcan-okf": "0.3.11",
47
+ "@venizia/vulcan-atlas": "0.3.13",
48
+ "@venizia/vulcan-okf": "0.3.13",
51
49
  "zod": "^4.6.7"
52
50
  },
53
51
  "devDependencies": {
54
52
  "@types/bun": "1.4.3",
55
53
  "@venizia/dev-configs": "0.3.5",
56
54
  "eslint": "10.13.0",
57
- "oxfmt": "0.74.0",
58
55
  "oxlint": "1.89.0",
59
56
  "oxlint-tsgolint": "7.0.2004",
60
57
  "typescript": "^6.0.3"
61
58
  },
62
- "sideEffects": false
59
+ "engines": {
60
+ "bun": ">=1.4.4"
61
+ }
63
62
  }
@@ -70,7 +70,7 @@ export class ProjectLayout {
70
70
  '.agents/vulcan.local.json',
71
71
  ];
72
72
  /** What the scaffolded lint configs run; optional peers of dev-configs, so bun never installs them alone. */
73
- static readonly LINT_TOOLS = ['oxlint', 'oxlint-tsgolint', 'oxfmt', 'eslint'];
73
+ static readonly LINT_TOOLS = ['oxlint', 'oxlint-tsgolint', 'eslint'];
74
74
  /** Written into a scaffolded file the project must fill in; doctor fails the file while it holds this. */
75
75
  static readonly SCAFFOLD_MARKER = 'vulcan:scaffold';
76
76
  }
@@ -0,0 +1,24 @@
1
+ /**
2
+ * `text` as `bun fmt` formats the file named `opts.file` (only the extension and name matter: the
3
+ * text goes in on stdin). A file VULCAN writes this way is what `bun fmt --check` accepts, so a
4
+ * regenerate never turns lint red, and no copy of Bun's rules (key order, array layout) lives here.
5
+ * `--no-script` keeps a `fmt` script from taking over. Bun is the runtime (`engines`), so
6
+ * `process.execPath` is it. When bun fmt fails the text comes back unchanged and the reason is
7
+ * printed: `make lint` flags the file.
8
+ */
9
+ export const formatWithBun = (opts: { text: string; file: string }): string => {
10
+ const result = Bun.spawnSync(
11
+ [process.execPath, 'fmt', '--no-script', '--stdin-filepath', opts.file],
12
+ { stdin: Buffer.from(opts.text), stdout: 'pipe', stderr: 'pipe' },
13
+ );
14
+
15
+ if (result.exitCode !== 0) {
16
+ console.error(
17
+ `[formatWithBun] bun fmt exited ${result.exitCode}, ${opts.file} is left as rendered | ${result.stderr.toString().trim()}`,
18
+ );
19
+
20
+ return opts.text;
21
+ }
22
+
23
+ return result.stdout.toString();
24
+ };
@@ -2,3 +2,4 @@ export * from './constants.ts';
2
2
  export * from './paths.ts';
3
3
  export * from './types.ts';
4
4
  export * from './json.ts';
5
+ export * from './format.ts';
@@ -8,8 +8,9 @@ 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
+ import { renderManifestJson } from './manifest-json.ts';
13
14
  import { menusAvailable, promptSelect } from '../ui/index.ts';
14
15
  import { askPresetSpec } from './preset-menu.ts';
15
16
  import { ABORTED, confirmWrite, planLines } from './plan.ts';
@@ -41,7 +42,6 @@ import {
41
42
  renderAppConcept,
42
43
  renderAppManifest,
43
44
  renderKnowledgeIndex,
44
- renderLogEntry,
45
45
  replaceAppsBlock,
46
46
  } from './workspace.ts';
47
47
 
@@ -602,7 +602,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
602
602
  writeFile({
603
603
  root: cwd,
604
604
  path: 'package.json',
605
- content: `${JSON.stringify(nextManifest, null, 2)}\n`,
605
+ content: renderManifestJson({ value: nextManifest }),
606
606
  });
607
607
  writeFile({ root: cwd, path: configPath, content: nextConfig });
608
608
  writeFile({
@@ -627,20 +627,6 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
627
627
  : renderKnowledgeIndex({ project, apps: [{ name: app, summary: preset.summary }] }),
628
628
  });
629
629
 
630
- const logPath = join(cwd, KNOWLEDGE_DIRECTORY, 'log.md');
631
- const logEntry = renderLogEntry({
632
- date: today(),
633
- text: `added ${folder}/${app} from the ${packageName} ${packageVersion} preset`,
634
- });
635
-
636
- writeFile({
637
- root: cwd,
638
- path: `${KNOWLEDGE_DIRECTORY}/log.md`,
639
- content: existsSync(logPath)
640
- ? `${readFileSync(logPath, 'utf8').trimEnd()}\n\n${logEntry}`
641
- : `# ${project} knowledge log\n\n${logEntry}`,
642
- });
643
-
644
630
  for (const step of [
645
631
  () => runBun({ cwd, args: ['install'], label: 'bun install' }),
646
632
  // The installed CLI syncs, so the project is wired to the version it pins.
@@ -6,8 +6,9 @@ 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
+ import { renderManifestJson } from './manifest-json.ts';
11
12
  import type { TLibPreset } from './lib-preset.ts';
12
13
  import { ABORTED, confirmWrite, planLines } from './plan.ts';
13
14
  import { askInTerminal, readFlag, SCOPE_PATTERN } from './names.ts';
@@ -21,7 +22,6 @@ import {
21
22
  renderKnowledgeIndex,
22
23
  renderLibConcept,
23
24
  renderLibManifest,
24
- renderLogEntry,
25
25
  replaceAppsBlock,
26
26
  } from './workspace.ts';
27
27
 
@@ -275,7 +275,7 @@ export const addLibrary = async (opts: {
275
275
  writeFile({
276
276
  root: cwd,
277
277
  path: 'package.json',
278
- content: `${JSON.stringify(nextManifest, null, 2)}\n`,
278
+ content: renderManifestJson({ value: nextManifest }),
279
279
  });
280
280
  writeFile({ root: cwd, path: opts.configPath, content: nextConfig });
281
281
  writeFile({
@@ -302,20 +302,6 @@ export const addLibrary = async (opts: {
302
302
  : renderKnowledgeIndex({ project, apps: [{ name: libName, summary: lib.summary }] }),
303
303
  });
304
304
 
305
- const logPath = join(cwd, KNOWLEDGE_DIRECTORY, 'log.md');
306
- const logEntry = renderLogEntry({
307
- date: today(),
308
- text: `added ${path} from the ${located.packageName} ${located.packageVersion} preset (lib kind)`,
309
- });
310
-
311
- writeFile({
312
- root: cwd,
313
- path: `${KNOWLEDGE_DIRECTORY}/log.md`,
314
- content: existsSync(logPath)
315
- ? `${readFileSync(logPath, 'utf8').trimEnd()}\n\n${logEntry}`
316
- : `# ${project} knowledge log\n\n${logEntry}`,
317
- });
318
-
319
305
  for (const step of [
320
306
  () => runBun({ cwd, args: ['install'], label: 'bun install' }),
321
307
  () =>
@@ -1,11 +1,23 @@
1
1
  /**
2
- * The root `bunfig.toml` `init` writes: Bun's telemetry off. No `minimumReleaseAge`: a gate of a few
3
- * days fails a fresh install whose version floors are the latest releases (measured on a real project: ten
4
- * packages), so it stays out; Phat's rule is floors at the latest.
2
+ * The root `bunfig.toml` `init` writes: Bun's telemetry off, and the `[fmt]` section `bun fmt` reads.
3
+ * The three options are the settings of the shared style (`@venizia/dev-configs`, formerly
4
+ * `oxfmtConfigs`); the rest is Bun's defaults (tab width 2, trailing commas, semicolons, bracket
5
+ * spacing). `flavor = "oxfmt"` pins the oxfmt output: without it `bun fmt` formats like Prettier
6
+ * whenever oxfmt is not a dependency (a union type's first member moves to its own line, for one).
7
+ * No `minimumReleaseAge`: a gate of a few days fails a fresh install whose version floors are the
8
+ * latest releases (measured on a real project: ten packages), so it stays out; Phat's rule is floors
9
+ * at the latest.
5
10
  */
6
11
  export const renderBunfig = (): string =>
7
12
  [
8
- '# Bun reads this file only from the directory a command runs in, so it sits at the root.',
13
+ '# Bun reads this file from the directory a command runs in, and bun fmt also inherits it from a parent.',
14
+ '# So it sits at the root, and [fmt] applies to every folder below it.',
9
15
  'telemetry = false',
10
16
  '',
17
+ '[fmt]',
18
+ 'printWidth = 100',
19
+ 'singleQuote = true',
20
+ 'arrowParens = "avoid"',
21
+ 'flavor = "oxfmt"',
22
+ '',
11
23
  ].join('\n');
@@ -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: {
@@ -0,0 +1,5 @@
1
+ import { formatWithBun } from '../common/index.ts';
2
+
3
+ /** A package.json as `bun fmt` wants it: Bun's own key order (name, version, ... scripts, dependencies A to Z). */
4
+ export const renderManifestJson = (opts: { value: unknown }): string =>
5
+ formatWithBun({ text: `${JSON.stringify(opts.value, null, 2)}\n`, file: 'package.json' });
@@ -1,6 +1,7 @@
1
1
  import { relative, resolve } from 'node:path';
2
2
  import { coversFolder } from '../init/index.ts';
3
3
  import { CreateConstants } from './common/index.ts';
4
+ import { renderManifestJson } from './manifest-json.ts';
4
5
  import type {
5
6
  IApp,
6
7
  IAppsBlock,
@@ -15,15 +16,13 @@ const ENV_PORT = /^[A-Z0-9_]*PORT=(\d+)\s*$/m;
15
16
  /** A newline inside a list item or a paragraph would split it. */
16
17
  const oneLine = (opts: { text: string }): string => opts.text.replace(/\s+/g, ' ').trim();
17
18
 
18
- const json = (opts: { value: unknown }): string => `${JSON.stringify(opts.value, null, 2)}\n`;
19
-
20
19
  export const renderRootManifest = (opts: {
21
20
  project: string;
22
21
  workspaces: string[];
23
22
  catalog: Record<string, string>;
24
23
  vulcanVersion: string;
25
24
  }): string =>
26
- json({
25
+ renderManifestJson({
27
26
  value: {
28
27
  name: opts.project,
29
28
  private: true,
@@ -158,7 +157,7 @@ export const renderAppManifest = (opts: {
158
157
  preset: IPreset;
159
158
  presetPackage: { name: string; version: string };
160
159
  }): string =>
161
- json({
160
+ renderManifestJson({
162
161
  value: {
163
162
  name: opts.name ?? opts.app,
164
163
  version: '0.0.0',
@@ -195,7 +194,7 @@ export const renderLibManifest = (opts: {
195
194
  const section = (value: Record<string, unknown>, key: string): Record<string, unknown> =>
196
195
  Object.keys(value).length === 0 ? {} : { [key]: value };
197
196
 
198
- return json({
197
+ return renderManifestJson({
199
198
  value: {
200
199
  name: opts.name,
201
200
  version: '0.0.0',
@@ -264,9 +263,14 @@ export const renderLibConcept = (opts: {
264
263
  ...renderAtlasLookups({ kind: 'lib' }),
265
264
  ].join('\n');
266
265
 
266
+ /**
267
+ * The block is JSON that `add` reads back with `JSON.parse`, so `bun fmt` must not rewrite it
268
+ * (it would drop the key quotes): `prettier-ignore` is honoured by both of its flavors.
269
+ */
267
270
  export const renderAppsBlock = (opts: { block: IAppsBlock }): string =>
268
271
  [
269
272
  CreateConstants.APPS_BLOCK_START,
273
+ '// prettier-ignore',
270
274
  `const apps = ${JSON.stringify(opts.block, null, 2)};`,
271
275
  CreateConstants.APPS_BLOCK_END,
272
276
  ].join('\n');
@@ -489,9 +493,6 @@ export const renderAppConcept = (opts: {
489
493
  ...renderAtlasLookups({ kind: opts.app.side }),
490
494
  ].join('\n');
491
495
 
492
- export const renderLogEntry = (opts: { date: string; text: string }): string =>
493
- `## ${opts.date}\n\n- ${opts.text}\n`;
494
-
495
496
  export const pickPort = (opts: { preferred: number; used: number[] }): number => {
496
497
  let port = opts.preferred;
497
498
 
@@ -794,6 +794,127 @@ export const checkDockerignore = (opts: ICheckContext): IViolation[] => {
794
794
  ];
795
795
  };
796
796
 
797
+ const FMT_SECTION_ADVICE =
798
+ 'add a [fmt] section (printWidth = 100, singleQuote = true, arrowParens = "avoid", flavor = "oxfmt"): without it bun fmt formats with Bun\'s defaults, not the shared style';
799
+ const FMT_FLAVOR_ADVICE =
800
+ 'without it bun fmt formats like Prettier when oxfmt is not a dependency, and the output changes';
801
+ const OXFMT_LOADED_ADVICE =
802
+ 'bun fmt loads it and it overrides the [fmt] section of bunfig.toml - delete it, or move its settings to [fmt]';
803
+
804
+ /** The folders that can hold a package.json and an oxfmt config: the root, `packages/*` and every configured package. */
805
+ const formatOwners = (opts: ICheckContext): string[] => [
806
+ ...new Set([
807
+ '.',
808
+ ...listDirectories({ directory: join(opts.root, 'packages') }).map(name =>
809
+ join('packages', name),
810
+ ),
811
+ ...resolvePackages({ config: opts.config })
812
+ .filter(entry => !entry.retired)
813
+ .map(entry => relative(opts.root, join(opts.root, entry.path)) || '.'),
814
+ ]),
815
+ ];
816
+
817
+ /**
818
+ * `bun fmt` reads the `[fmt]` section of `bunfig.toml`; without it, it formats with Bun's defaults
819
+ * (width 80, double quotes) and rewrites a tree the shared style formatted, and without
820
+ * `flavor = "oxfmt"` it formats like Prettier once oxfmt is not a dependency. A `fmt` script in a
821
+ * `package.json` runs instead of the formatter, and an oxfmt config `bun fmt` finds by itself
822
+ * overrides `[fmt]`; the `oxfmt.config.*` init used to write in `.configs/formatters/` is read by
823
+ * nothing. Warnings, never failures: a project made before `bun fmt` does not start failing.
824
+ */
825
+ export const checkFormat = (opts: ICheckContext): IViolation[] => {
826
+ const warnings: IViolation[] = [];
827
+ const bunfig = join(opts.root, 'bunfig.toml');
828
+ const bunfigText = readText({ file: bunfig });
829
+
830
+ if (!existsSync(bunfig)) {
831
+ warnings.push(
832
+ createViolation({
833
+ check: DoctorChecks.FORMAT,
834
+ file: 'bunfig.toml',
835
+ message: `missing - ${FMT_SECTION_ADVICE}`,
836
+ }),
837
+ );
838
+ } else if (!DoctorConstants.BUNFIG_FMT_SECTION.test(bunfigText)) {
839
+ warnings.push(
840
+ createViolation({
841
+ check: DoctorChecks.FORMAT,
842
+ file: 'bunfig.toml',
843
+ message: `no [fmt] section - ${FMT_SECTION_ADVICE}`,
844
+ }),
845
+ );
846
+ } else if (!DoctorConstants.BUNFIG_FMT_FLAVOR.test(bunfigText)) {
847
+ warnings.push(
848
+ createViolation({
849
+ check: DoctorChecks.FORMAT,
850
+ file: 'bunfig.toml',
851
+ message: `[fmt] has no flavor = "oxfmt" - ${FMT_FLAVOR_ADVICE}`,
852
+ }),
853
+ );
854
+ }
855
+
856
+ for (const owner of formatOwners(opts)) {
857
+ const manifest = join(owner, 'package.json');
858
+ const formatters = join(owner, '.configs', 'formatters');
859
+
860
+ if (readScriptNames({ file: join(opts.root, manifest) })?.includes('fmt')) {
861
+ warnings.push(
862
+ createViolation({
863
+ check: DoctorChecks.FORMAT,
864
+ file: manifest,
865
+ message:
866
+ 'defines a "fmt" script: bun fmt runs it instead of formatting - rename it (the standard names are lint and lint:fix)',
867
+ }),
868
+ );
869
+ }
870
+
871
+ const copy = join(owner, 'bunfig.toml');
872
+
873
+ if (
874
+ owner !== '.' &&
875
+ DoctorConstants.BUNFIG_FMT_SECTION.test(readText({ file: join(opts.root, copy) }))
876
+ ) {
877
+ warnings.push(
878
+ createViolation({
879
+ check: DoctorChecks.FORMAT,
880
+ file: copy,
881
+ message:
882
+ 'a [fmt] copy: bun fmt inherits the root bunfig.toml, and a copy here can drift from it - delete the section',
883
+ }),
884
+ );
885
+ }
886
+
887
+ for (const file of DoctorConstants.OXFMT_AUTOLOADED_FILES) {
888
+ if (existsSync(join(opts.root, owner, file))) {
889
+ warnings.push(
890
+ createViolation({
891
+ check: DoctorChecks.FORMAT,
892
+ file: join(owner, file),
893
+ message: OXFMT_LOADED_ADVICE,
894
+ }),
895
+ );
896
+ }
897
+ }
898
+
899
+ if (existsSync(join(opts.root, formatters))) {
900
+ for (const file of readdirSync(join(opts.root, formatters)).filter(name =>
901
+ DoctorConstants.OXFMT_CONFIG_FILE.test(name),
902
+ )) {
903
+ warnings.push(
904
+ createViolation({
905
+ check: DoctorChecks.FORMAT,
906
+ file: join(formatters, file),
907
+ message:
908
+ 'not used any more: bun fmt formats with the [fmt] section of bunfig.toml - delete it',
909
+ }),
910
+ );
911
+ }
912
+ }
913
+ }
914
+
915
+ return warnings;
916
+ };
917
+
797
918
  export const checkAtlasBlock = (opts: ICheckContext): IViolation[] => {
798
919
  const merged = mergedAtlasBlock({ root: opts.root, config: opts.config });
799
920
 
@@ -17,6 +17,7 @@ export class DoctorChecks {
17
17
  static readonly AGENTS = 'agents';
18
18
  static readonly DOCKERIGNORE = 'dockerignore';
19
19
  static readonly MCP = 'mcp';
20
+ static readonly FORMAT = 'format';
20
21
  static readonly SCHEME_SET = new Set<string>([
21
22
  this.CONFIG,
22
23
  this.LAYOUT,
@@ -36,6 +37,7 @@ export class DoctorChecks {
36
37
  this.AGENTS,
37
38
  this.DOCKERIGNORE,
38
39
  this.MCP,
40
+ this.FORMAT,
39
41
  ]);
40
42
  static isValid(value: string): boolean {
41
43
  return this.SCHEME_SET.has(value);
@@ -60,11 +62,17 @@ export class DoctorConstants {
60
62
  static readonly MAKE_INCLUDE_PATTERN =
61
63
  /^-?include\s+\S*@venizia\/vulcan\/base\/make\/vulcan\.mk\s*$/m;
62
64
  static readonly SHIPPED_HOOKS_PATH = '@venizia/vulcan/base/hooks/';
63
- static readonly LINT_CONFIG_FILE = /^(oxlint|eslint|oxfmt)\.config\.(mts|ts|mjs|js|cjs)$/;
65
+ /** The `[fmt]` table header of a `bunfig.toml`, on a line of its own, a trailing comment allowed. */
66
+ static readonly BUNFIG_FMT_SECTION = /^\s*\[fmt\]\s*(#.*)?$/m;
67
+ static readonly BUNFIG_FMT_FLAVOR = /^\s*flavor\s*=\s*["']oxfmt["']/m;
68
+ /** What init wrote before `[fmt]` decided the style; `bun fmt` no longer reads it. */
69
+ static readonly OXFMT_CONFIG_FILE = /^oxfmt\.config\.(mts|ts|mjs|js|cjs)$/;
70
+ /** The oxfmt config names `bun fmt` finds by itself, in a package folder or above it; they override `[fmt]`. */
71
+ static readonly OXFMT_AUTOLOADED_FILES = ['.oxfmtrc.json', '.oxfmtrc.jsonc', 'oxfmt.config.ts'];
72
+ static readonly LINT_CONFIG_FILE = /^(oxlint|eslint)\.config\.(mts|ts|mjs|js|cjs)$/;
64
73
  /** Where each tool's config lives under `.configs/`; a file left directly in `.configs/` is told where it belongs. */
65
74
  static readonly LINT_CONFIG_FOLDERS: Record<string, string> = {
66
75
  oxlint: 'lints',
67
76
  eslint: 'lints',
68
- oxfmt: 'formatters',
69
77
  };
70
78
  }
@@ -7,6 +7,7 @@ import {
7
7
  checkAtlasBlock,
8
8
  checkSkillTriggers,
9
9
  checkDockerignore,
10
+ checkFormat,
10
11
  checkMcpAtlas,
11
12
  checkApps,
12
13
  checkManifest,
@@ -95,5 +96,10 @@ export const runDoctorWarnings = async (opts: { root: string }): Promise<IViolat
95
96
  configFile: relative(opts.root, loaded.file),
96
97
  };
97
98
 
98
- return [...checkMcpAtlas(context), ...checkDockerignore(context), ...checkSkillTriggers(context)];
99
+ return [
100
+ ...checkMcpAtlas(context),
101
+ ...checkDockerignore(context),
102
+ ...checkSkillTriggers(context),
103
+ ...checkFormat(context),
104
+ ];
99
105
  };
@@ -23,7 +23,6 @@ const SCAFFOLD_FILES: IScaffoldFile[] = [
23
23
  const LINT_CONFIG_FILES: IScaffoldFile[] = [
24
24
  { path: '.configs/lints/oxlint.config.mts', template: 'oxlint.config.mts' },
25
25
  { path: '.configs/lints/eslint.config.mjs', template: 'eslint.config.mjs' },
26
- { path: '.configs/formatters/oxfmt.config.mts', template: 'oxfmt.config.mts' },
27
26
  ];
28
27
 
29
28
  export interface IScaffoldResult {
@@ -1,5 +1,6 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { basename, join } from 'node:path';
3
+ import { formatWithBun } from '../common/index.ts';
3
4
  import { resolvePackages } from '../config/index.ts';
4
5
  import type { TResolvedConfig } from '../config/index.ts';
5
6
  import { readBaseRules } from '../rules/index.ts';
@@ -85,7 +86,10 @@ export const renderManifest = (opts: { root: string; config: TResolvedConfig }):
85
86
  ...(config.remoteHosts === undefined ? {} : { remoteHosts: config.remoteHosts }),
86
87
  };
87
88
 
88
- return `${JSON.stringify(manifest, null, 2)}\n`;
89
+ return formatWithBun({
90
+ text: `${JSON.stringify(manifest, null, 2)}\n`,
91
+ file: ManifestConstants.FILE,
92
+ });
89
93
  };
90
94
 
91
95
  /**
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
  }
@@ -1,4 +0,0 @@
1
- import { defineConfig } from 'oxfmt';
2
- import { oxfmtConfigs } from '@venizia/dev-configs/formatters';
3
-
4
- export default defineConfig(oxfmtConfigs);