@venizia/vulcan 0.2.0 → 0.3.1

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.
@@ -2,7 +2,7 @@ import { Glob } from 'bun';
2
2
  import { existsSync, readdirSync, readFileSync } from 'node:fs';
3
3
  import { join, relative } from 'node:path';
4
4
  import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
5
- import { declaresWorkspaces } from '../init/index.ts';
5
+ import { coversFolder, declaresWorkspaces, readWorkspaceGlobs } from '../init/index.ts';
6
6
  import { resolvePackages } from '../config/index.ts';
7
7
  import type { TResolvedConfig } from '../config/index.ts';
8
8
  import {
@@ -398,3 +398,41 @@ export const checkScaffold = (opts: ICheckContext): IViolation[] => {
398
398
 
399
399
  return violations;
400
400
  };
401
+
402
+ /** Apps sit in the folders the user named, and every named folder is a workspace. */
403
+ export const checkApps = (opts: ICheckContext): IViolation[] => {
404
+ const layout = opts.config.layout;
405
+
406
+ if (layout === undefined) {
407
+ return [];
408
+ }
409
+
410
+ const globs = readWorkspaceGlobs({ root: opts.root });
411
+ const folders = Object.entries(layout).filter(
412
+ (entry): entry is [string, string] => entry[1] !== undefined,
413
+ );
414
+ const violations = folders
415
+ .filter(([, folder]) => !coversFolder({ globs, folder }))
416
+ .map(([side, folder]) =>
417
+ createViolation({
418
+ check: DoctorChecks.APPS,
419
+ file: 'package.json',
420
+ message: `layout.${side} '${folder}' is not in package.json workspaces - add '${folder}/*'`,
421
+ }),
422
+ );
423
+ const names = folders.map(([, folder]) => folder);
424
+
425
+ for (const entry of resolvePackages({ config: opts.config }).filter(item => !item.retired)) {
426
+ if (!names.some(folder => entry.path.startsWith(`${folder}/`))) {
427
+ violations.push(
428
+ createViolation({
429
+ check: DoctorChecks.APPS,
430
+ file: opts.configFile,
431
+ message: `package ${entry.dir} lives at ${entry.path}, outside every layout folder (${names.join(', ')})`,
432
+ }),
433
+ );
434
+ }
435
+ }
436
+
437
+ return violations;
438
+ };
@@ -12,6 +12,7 @@ export class DoctorChecks {
12
12
  static readonly TAGS = 'tags';
13
13
  static readonly PRUNE = 'prune';
14
14
  static readonly SCAFFOLD = 'scaffold';
15
+ static readonly APPS = 'apps';
15
16
  static readonly SCHEME_SET = new Set<string>([
16
17
  this.CONFIG,
17
18
  this.LAYOUT,
@@ -26,6 +27,7 @@ export class DoctorChecks {
26
27
  this.TAGS,
27
28
  this.PRUNE,
28
29
  this.SCAFFOLD,
30
+ this.APPS,
29
31
  ]);
30
32
  static isValid(value: string): boolean {
31
33
  return this.SCHEME_SET.has(value);
@@ -2,6 +2,7 @@ import { relative } from 'node:path';
2
2
  import { loadConfig } from '../config/index.ts';
3
3
  import {
4
4
  checkAdapters,
5
+ checkApps,
5
6
  checkManifest,
6
7
  checkPrune,
7
8
  checkHooks,
@@ -52,5 +53,6 @@ export const runDoctorChecks = async (opts: { root: string }): Promise<IViolatio
52
53
  ...checkSkillLint(context),
53
54
  ...checkStyle(context),
54
55
  ...checkScaffold(context),
56
+ ...checkApps(context),
55
57
  ];
56
58
  };
@@ -1,9 +1,16 @@
1
1
  export class InitStatuses {
2
2
  static readonly CREATED = 'created';
3
+ static readonly UPDATED = 'updated';
3
4
  static readonly KEPT = 'kept';
4
5
  static readonly ADD = 'add';
5
6
  static readonly SKIPPED = 'skipped';
6
- static readonly SCHEME_SET = new Set<string>([this.CREATED, this.KEPT, this.ADD, this.SKIPPED]);
7
+ static readonly SCHEME_SET = new Set<string>([
8
+ this.CREATED,
9
+ this.UPDATED,
10
+ this.KEPT,
11
+ this.ADD,
12
+ this.SKIPPED,
13
+ ]);
7
14
  static isValid(value: string): boolean {
8
15
  return this.SCHEME_SET.has(value);
9
16
  }
@@ -1,11 +1,36 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { basename, dirname, join, relative } from 'node:path';
3
- import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
3
+ import { BASE_DIRECTORY, ProjectLayout, readProperty } from '../common/index.ts';
4
4
  import { ConfigConstants, findConfigFiles } from '../config/index.ts';
5
5
  import type { TConfigExtension } from '../config/index.ts';
6
6
  import { InitConstants, InitStatuses } from './common/index.ts';
7
7
  import type { IInitEntry, IScaffoldFile } from './common/index.ts';
8
8
 
9
+ /**
10
+ * Whether a `.mcp.json` already serves atlas: a server named `atlas`, or any server whose arguments run
11
+ * `atlas mcp` under another name, as separate arguments or inside a `sh -c` string. A file that is not JSON falls back to looking for the name.
12
+ */
13
+ const runsAtlas = (opts: { text: string }): boolean => {
14
+ try {
15
+ const parsed: { mcpServers?: Record<string, { args?: unknown }> } = JSON.parse(opts.text);
16
+ const servers = parsed.mcpServers ?? {};
17
+
18
+ return (
19
+ 'atlas' in servers ||
20
+ Object.values(servers).some(server => {
21
+ const args = Array.isArray(server.args)
22
+ ? server.args.flatMap(arg => String(arg).split(/\s+/))
23
+ : [];
24
+ const atlas = args.indexOf('atlas');
25
+
26
+ return atlas !== -1 && args[atlas + 1] === 'mcp';
27
+ })
28
+ );
29
+ } catch {
30
+ return opts.text.includes('"atlas"');
31
+ }
32
+ };
33
+
9
34
  /** The entry for a `.mcp.json` that exists already: atlas serves the knowledge bundle alone, and the wiki when there is one. */
10
35
  const MCP_SERVER_HINT =
11
36
  '"atlas": { "command": "bun", "args": ["x", "--no-install", "vulcan", "x", "atlas", "mcp", "--root", "."] }';
@@ -25,6 +50,14 @@ const LINT_CONFIG_FILES: IScaffoldFile[] = [
25
50
  { path: '.configs/oxfmt.config.mts', template: 'oxfmt.config.mts' },
26
51
  ];
27
52
 
53
+ export interface IScaffoldResult {
54
+ entries: IInitEntry[];
55
+ /** Packages to `bun add -d`, empty when everything is declared. */
56
+ install: string[];
57
+ /** What is left for the user, in order. */
58
+ todo: string[];
59
+ }
60
+
28
61
  interface IPackageManifest {
29
62
  name?: unknown;
30
63
  workspaces?: unknown;
@@ -59,6 +92,30 @@ export const declaresWorkspaces = (opts: { root: string }): boolean => {
59
92
  return Array.isArray(workspaces) || (typeof workspaces === 'object' && workspaces !== null);
60
93
  };
61
94
 
95
+ /** The root workspace globs, from either form; empty when there are none. */
96
+ export const readWorkspaceGlobs = (opts: { root: string }): string[] => {
97
+ const workspaces = readManifest(opts)?.workspaces;
98
+
99
+ if (Array.isArray(workspaces)) {
100
+ return workspaces.map(String);
101
+ }
102
+
103
+ const packages = readProperty({ value: workspaces, key: 'packages' });
104
+
105
+ return Array.isArray(packages) ? packages.map(String) : [];
106
+ };
107
+
108
+ /**
109
+ * Whether a workspace glob list covers the packages directly under `folder`: `folder/*` or
110
+ * `folder/**`, with or without a leading `./`.
111
+ */
112
+ export const coversFolder = (opts: { globs: string[]; folder: string }): boolean =>
113
+ opts.globs.some(glob => {
114
+ const plain = glob.replace(/^\.\//, '');
115
+
116
+ return plain === `${opts.folder}/*` || plain === `${opts.folder}/**`;
117
+ });
118
+
62
119
  /** The `package.json` name, or the directory name when there is none. */
63
120
  export const resolveProjectName = (opts: { root: string }): string => {
64
121
  const name = readManifest(opts)?.name;
@@ -66,7 +123,7 @@ export const resolveProjectName = (opts: { root: string }): string => {
66
123
  return typeof name === 'string' && name !== '' ? name : basename(opts.root);
67
124
  };
68
125
 
69
- const renderTemplate = (opts: { template: string; name: string }): string =>
126
+ export const renderTemplate = (opts: { template: string; name: string }): string =>
70
127
  readFileSync(join(BASE_DIRECTORY, 'templates', opts.template), 'utf8').replaceAll(
71
128
  InitConstants.NAME_TOKEN,
72
129
  opts.name,
@@ -85,11 +142,11 @@ const writeIfAbsent = (opts: { root: string; path: string; content: string }): I
85
142
  return { status: InitStatuses.CREATED, subject: opts.path };
86
143
  };
87
144
 
88
- /** Scaffolds the project layer at `root`. Never overwrites: an existing file is kept and a needed edit becomes a hint. */
145
+ /** Scaffolds the project layer at `root`. Never overwrites: an existing file is kept and a needed edit becomes a hint; only `.gitignore` is appended to, line by line. */
89
146
  export const scaffoldProject = (opts: {
90
147
  root: string;
91
148
  extension: TConfigExtension;
92
- }): IInitEntry[] => {
149
+ }): IScaffoldResult => {
93
150
  const { root } = opts;
94
151
  const name = resolveProjectName({ root });
95
152
  const isWorkspaces = declaresWorkspaces({ root });
@@ -154,7 +211,7 @@ export const scaffoldProject = (opts: {
154
211
  ) {
155
212
  const servers = readFileSync(join(root, '.mcp.json'), 'utf8');
156
213
 
157
- if (!servers.includes('"atlas"')) {
214
+ if (!runsAtlas({ text: servers })) {
158
215
  entries.push({
159
216
  status: InitStatuses.ADD,
160
217
  subject: `.mcp.json: the atlas server, for the knowledge bundle (and the wiki, when there is one; --root pins the project): ${MCP_SERVER_HINT}`,
@@ -163,23 +220,33 @@ export const scaffoldProject = (opts: {
163
220
  }
164
221
 
165
222
  const gitignore = join(root, '.gitignore');
166
- const ignored = existsSync(gitignore) ? readFileSync(gitignore, 'utf8').split('\n') : [];
167
- const missingIgnores = ProjectLayout.GITIGNORE_ENTRIES.filter(entry => !ignored.includes(entry));
223
+ const existing = existsSync(gitignore) ? readFileSync(gitignore, 'utf8') : '';
224
+ const lines = existing.split('\n');
225
+ const missingIgnores = ProjectLayout.GITIGNORE_ENTRIES.filter(entry => !lines.includes(entry));
168
226
 
169
227
  if (missingIgnores.length > 0) {
170
- entries.push({ status: InitStatuses.ADD, subject: `.gitignore: ${missingIgnores.join(' ')}` });
171
- }
228
+ const separator = existing === '' || existing.endsWith('\n') ? '' : '\n';
172
229
 
173
- const manifest = readManifest({ root });
174
-
175
- if (
176
- !(ProjectLayout.STYLE_PACKAGE in { ...manifest?.dependencies, ...manifest?.devDependencies })
177
- ) {
230
+ writeFileSync(gitignore, `${existing}${separator}${missingIgnores.join('\n')}\n`);
178
231
  entries.push({
179
- status: InitStatuses.ADD,
180
- subject: `devDependency: bun add -d --exact ${ProjectLayout.STYLE_PACKAGE}`,
232
+ status: InitStatuses.UPDATED,
233
+ subject: `.gitignore: + ${missingIgnores.join(' ')}`,
181
234
  });
182
235
  }
183
236
 
184
- return entries;
237
+ const manifest = readManifest({ root });
238
+ const declared = { ...manifest?.dependencies, ...manifest?.devDependencies };
239
+ const needed = isWorkspaces
240
+ ? [ProjectLayout.STYLE_PACKAGE]
241
+ : [...ProjectLayout.LINT_TOOLS, ProjectLayout.STYLE_PACKAGE];
242
+ const install = needed.filter(packageName => !(packageName in declared));
243
+ const todo = [
244
+ `describe the project in ${ConfigConstants.DEFAULT_KNOWLEDGE_BUNDLE}/index.md, then delete the ${ProjectLayout.SCAFFOLD_MARKER} line`,
245
+ ...entries
246
+ .filter(entry => entry.status === InitStatuses.ADD)
247
+ .map(entry => `add ${entry.subject}`),
248
+ `${ProjectLayout.VULCAN_COMMAND} sync && ${ProjectLayout.VULCAN_COMMAND} doctor`,
249
+ ];
250
+
251
+ return { entries, install, todo };
185
252
  };
@@ -68,7 +68,6 @@ export const renderManifest = (opts: { root: string; config: TResolvedConfig }):
68
68
  },
69
69
  release: {
70
70
  tagPattern: config.atlas.tagPattern,
71
- legacyTagPrefixes: config.atlas.legacyTagPrefixes ?? [],
72
71
  ignoreTags: config.atlas.ignoreTags ?? [],
73
72
  },
74
73
  rules: { project: ManifestConstants.PROJECT_RULES, base: buildBaseRuleHashes() },
package/src/router.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { COMMAND_HANDLERS } from './commands/index.ts';
2
2
  import { runHelpCommand } from './commands/help.command.ts';
3
- import { ExitCodes, VulcanCommands } from './common/index.ts';
3
+ import { ExitCodes, UpgradeFlags, VulcanCommands } from './common/index.ts';
4
+ import { CreateFlags } from './create/common/index.ts';
4
5
 
5
6
  const HELP_ALIASES = new Set(['--help', '-h']);
6
7
  const VERSION_ALIASES = new Set(['--version', '-v']);
@@ -14,10 +15,38 @@ interface IAcceptedArgs {
14
15
 
15
16
  /** What each command takes; `x` hands everything to its tool, `help` and `version` take nothing. */
16
17
  const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
17
- [VulcanCommands.INIT]: { flags: [], values: ['--config'], positionals: 0 },
18
+ [VulcanCommands.INIT]: {
19
+ flags: [CreateFlags.NO_API],
20
+ values: [
21
+ '--config',
22
+ CreateFlags.PRESET,
23
+ CreateFlags.PROJECT,
24
+ CreateFlags.BACKEND_DIR,
25
+ CreateFlags.FRONTEND_DIR,
26
+ CreateFlags.SHARED_DIR,
27
+ CreateFlags.APP,
28
+ CreateFlags.API,
29
+ ],
30
+ positionals: 0,
31
+ },
32
+ [VulcanCommands.ADD]: {
33
+ flags: [CreateFlags.NO_API],
34
+ values: [
35
+ CreateFlags.PRESET,
36
+ CreateFlags.BACKEND_DIR,
37
+ CreateFlags.FRONTEND_DIR,
38
+ CreateFlags.APP,
39
+ CreateFlags.API,
40
+ ],
41
+ positionals: 0,
42
+ },
18
43
  [VulcanCommands.SYNC]: { flags: ['--dry-run', '--prune'], values: [], positionals: 0 },
19
44
  [VulcanCommands.DOCTOR]: { flags: [], values: [], positionals: 0 },
20
- [VulcanCommands.UPGRADE]: { flags: [], values: [], positionals: 1 },
45
+ [VulcanCommands.UPGRADE]: {
46
+ flags: [UpgradeFlags.STABLE, UpgradeFlags.NIGHTLY],
47
+ values: [],
48
+ positionals: 1,
49
+ },
21
50
  };
22
51
 
23
52
  /** The command name an argv asks for: no argument or a help flag means help. */
@@ -20,6 +20,10 @@ export class SyncStatuses {
20
20
  export class SyncConstants {
21
21
  static readonly CLAUDE_IMPORT_LINE = '@AGENTS.md';
22
22
  static readonly CLAUDE_TOOL_FILE = 'CLAUDE.md';
23
+
24
+ /** The first line of the CLAUDE.md `bun init` writes: Bun's tips, never the project's own words. */
25
+ static readonly BUN_INIT_CLAUDE_MARKER = 'Default to using Bun instead of Node.js.';
26
+
23
27
  static readonly CLAUDE_DIRECTORY = '.claude';
24
28
  static readonly SETTINGS_FILE = 'settings.json';
25
29
  /** The hook sync adds when the config sets `remoteHosts`; lives next to the shipped settings. */
@@ -30,7 +30,7 @@ const NO_CHANGE = (): void => {};
30
30
  const isSymlink = (opts: { path: string }): boolean =>
31
31
  lstatSync(opts.path, { throwIfNoEntry: false })?.isSymbolicLink() ?? false;
32
32
 
33
- /** `CLAUDE.md` holds only `@AGENTS.md`: an old symlink is replaced, a hand-written file is left alone. */
33
+ /** `CLAUDE.md` holds only `@AGENTS.md`: an old symlink or bun init's template is replaced, a hand-written file is left alone. */
34
34
  const planClaudeImport = (opts: { root: string }): ISyncAction => {
35
35
  const path = join(opts.root, SyncConstants.CLAUDE_TOOL_FILE);
36
36
  const write = (): void => writeFileSync(path, `${SyncConstants.CLAUDE_IMPORT_LINE}\n`);
@@ -51,14 +51,22 @@ const planClaudeImport = (opts: { root: string }): ISyncAction => {
51
51
  return { path, status: SyncStatuses.CREATED, apply: write };
52
52
  }
53
53
 
54
- return readFileSync(path, 'utf8').trim() === SyncConstants.CLAUDE_IMPORT_LINE
55
- ? { path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }
56
- : {
57
- path,
58
- status: SyncStatuses.SKIPPED,
59
- note: `hand-written - delete it to let sync write '${SyncConstants.CLAUDE_IMPORT_LINE}'`,
60
- apply: NO_CHANGE,
61
- };
54
+ const content = readFileSync(path, 'utf8');
55
+
56
+ if (content.trim() === SyncConstants.CLAUDE_IMPORT_LINE) {
57
+ return { path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE };
58
+ }
59
+
60
+ if (content.trimStart().startsWith(SyncConstants.BUN_INIT_CLAUDE_MARKER)) {
61
+ return { path, status: SyncStatuses.REPLACED, note: "bun init's template", apply: write };
62
+ }
63
+
64
+ return {
65
+ path,
66
+ status: SyncStatuses.SKIPPED,
67
+ note: `hand-written - delete it to let sync write '${SyncConstants.CLAUDE_IMPORT_LINE}'`,
68
+ apply: NO_CHANGE,
69
+ };
62
70
  };
63
71
 
64
72
  const readSettingsFile = (opts: { path: string }): TSettings | undefined => {