@venizia/vulcan 0.3.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
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
  "repository": {
@@ -44,8 +44,8 @@
44
44
  "test": "NODE_ENV=test bun test --env-file=.env.test"
45
45
  },
46
46
  "dependencies": {
47
- "@venizia/vulcan-atlas": "0.3.0",
48
- "@venizia/vulcan-okf": "0.3.0",
47
+ "@venizia/vulcan-atlas": "0.3.1",
48
+ "@venizia/vulcan-okf": "0.3.1",
49
49
  "zod": "^4.5.4"
50
50
  },
51
51
  "devDependencies": {
@@ -6,9 +6,10 @@ import type { IProjectPackage, TResolvedConfig } from '../config/index.ts';
6
6
  import { readWorkspaceGlobs } from '../init/index.ts';
7
7
  import { runAppChecks } from './checks.ts';
8
8
  import { AppSides, CreateFlags } from './common/index.ts';
9
- import type { IAppsBlock, ILocatedPreset, IPresetSpec } from './common/index.ts';
9
+ import type { IAppsBlock, ILocatedPreset, IPresetSpec, TAppSide } from './common/index.ts';
10
10
  import { today, writeFile } from './files.ts';
11
11
  import { askWithPrompt, readFlag, resolveNames, SIDE_FIELDS } from './names.ts';
12
+ import { readExistingApps, renderNext } from './next.ts';
12
13
  import { copyPresetFiles, locatePreset, parsePresetSpec } from './preset.ts';
13
14
  import { isInstallSkipped, runBun } from './process.ts';
14
15
  import { installNpmPreset, withScratch } from './scratch.ts';
@@ -34,12 +35,64 @@ const KNOWLEDGE_DIRECTORY = '.agents/knowledge';
34
35
  const ROOT_HINT =
35
36
  'run it at the root of a monorepo vulcan init created (no layout in .configs/vulcan.config.*)';
36
37
 
38
+ const MISSING_API = `missing ${CreateFlags.API} <app> or ${CreateFlags.NO_API}`;
39
+
37
40
  const fail = (opts: { message: string }): number => {
38
41
  process.stderr.write(`vulcan add: ${opts.message}\n`);
39
42
 
40
43
  return ExitCodes.FAILURE;
41
44
  };
42
45
 
46
+ /** The side the flags give away: a frontend flag, or only the backend folder; undefined when they do not say. */
47
+ const sideNamedBy = (opts: { args: string[] }): TAppSide | undefined => {
48
+ const frontend = [CreateFlags.FRONTEND_DIR, CreateFlags.API, CreateFlags.NO_API].some(flag =>
49
+ opts.args.includes(flag),
50
+ );
51
+ const backend = opts.args.includes(CreateFlags.BACKEND_DIR);
52
+
53
+ if (frontend === backend) {
54
+ return undefined;
55
+ }
56
+
57
+ return frontend ? AppSides.FRONTEND : AppSides.BACKEND;
58
+ };
59
+
60
+ /**
61
+ * What the command line already settles, checked before the preset is downloaded: without a terminal
62
+ * to ask, a missing --app, a side folder neither given nor held by the config, or a frontend with
63
+ * neither --api nor --no-api cannot be fixed by the download. The side is known from the flags when
64
+ * they name it; a preset whose side only its package says is checked after the download.
65
+ */
66
+ const missingFlag = (opts: {
67
+ args: string[];
68
+ layout: Partial<Record<TAppSide, string>>;
69
+ }): string | undefined => {
70
+ const side = sideNamedBy({ args: opts.args });
71
+
72
+ if (readFlag({ args: opts.args, flag: CreateFlags.APP }) === undefined) {
73
+ const kind = side === undefined ? '' : `${side} `;
74
+
75
+ return `missing ${CreateFlags.APP} (Name of this ${kind}app) - names are never chosen for you`;
76
+ }
77
+
78
+ if (side === undefined) {
79
+ return undefined;
80
+ }
81
+
82
+ const folder = SIDE_FIELDS[side];
83
+
84
+ if (
85
+ readFlag({ args: opts.args, flag: folder.flag }) === undefined &&
86
+ opts.layout[side] === undefined
87
+ ) {
88
+ return `missing ${folder.flag} (${folder.question}) - names are never chosen for you`;
89
+ }
90
+
91
+ const hasApi = opts.args.includes(CreateFlags.API) || opts.args.includes(CreateFlags.NO_API);
92
+
93
+ return side === AppSides.FRONTEND && !hasApi ? MISSING_API : undefined;
94
+ };
95
+
43
96
  const readRootManifest = (opts: { path: string }): TRootManifest | undefined => {
44
97
  if (!existsSync(opts.path)) {
45
98
  return undefined;
@@ -87,7 +140,7 @@ const resolveApiUrl = (opts: {
87
140
 
88
141
  if (chosen === undefined) {
89
142
  if (!opts.interactive) {
90
- return { ok: false, error: `missing ${CreateFlags.API} <app> or ${CreateFlags.NO_API}` };
143
+ return { ok: false, error: MISSING_API };
91
144
  }
92
145
 
93
146
  chosen =
@@ -128,14 +181,9 @@ const resolveApiUrl = (opts: {
128
181
  };
129
182
 
130
183
  const usedPorts = (opts: { root: string; packages: IProjectPackage[] }): number[] =>
131
- opts.packages.flatMap(entry => {
132
- const envFile = join(opts.root, entry.path, '.env.example');
133
- const port = existsSync(envFile)
134
- ? readPort({ envExample: readFileSync(envFile, 'utf8') })
135
- : undefined;
136
-
137
- return port === undefined ? [] : [port];
138
- });
184
+ readExistingApps({ root: opts.root, paths: opts.packages.map(entry => entry.path) }).map(
185
+ app => app.port,
186
+ );
139
187
 
140
188
  const locate = async (opts: {
141
189
  cwd: string;
@@ -180,6 +228,13 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
180
228
  return fail({ message: ROOT_HINT });
181
229
  }
182
230
 
231
+ const interactive = process.stdin.isTTY === true;
232
+ const early = interactive ? undefined : missingFlag({ args: opts.args, layout: config.layout });
233
+
234
+ if (early !== undefined) {
235
+ return fail({ message: early });
236
+ }
237
+
183
238
  const spec = parsePresetSpec({ value: presetValue, cwd });
184
239
  const located = await locate({ cwd, scratch: opts.scratch, spec });
185
240
 
@@ -198,7 +253,6 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
198
253
  return fail({ message: peerProblem });
199
254
  }
200
255
 
201
- const interactive = process.stdin.isTTY === true;
202
256
  const side = preset.side;
203
257
  const previous = config.layout[side];
204
258
  const names = resolveNames({
@@ -389,7 +443,17 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
389
443
  }
390
444
  }
391
445
 
392
- process.stderr.write(`Done. ${folder}/${app} is added.\n`);
446
+ // Every app `make dev` serves: those that were here, then the new one at the port it was given.
447
+ process.stderr.write(
448
+ renderNext({
449
+ done: `Done. ${folder}/${app} is added.`,
450
+ command: 'make dev',
451
+ apps: [
452
+ ...readExistingApps({ root: cwd, paths: packages.map(existing => existing.path) }),
453
+ { port: devPort, urls: preset.urls },
454
+ ],
455
+ }),
456
+ );
393
457
 
394
458
  return ExitCodes.OK;
395
459
  };
@@ -40,6 +40,8 @@ export interface IPreset {
40
40
  peers: Record<string, string>;
41
41
  scripts: Record<string, string>;
42
42
  checks: string[];
43
+ /** Paths under the dev port worth opening (`/api/hello`); none means the root. */
44
+ urls: string[];
43
45
  /** The folder holding the files to copy, absolute once the preset is located. */
44
46
  files: string;
45
47
  atlas: IPresetAtlasSource[];
@@ -14,6 +14,7 @@ import type {
14
14
  import { today, writeFile } from './files.ts';
15
15
  import { askWithPrompt, findFolderClash, readFlag, resolveNames, SIDE_FIELDS } from './names.ts';
16
16
  import { copyPresetFiles, locatePreset, parsePresetSpec } from './preset.ts';
17
+ import { renderNext } from './next.ts';
17
18
  import { isInstallSkipped, runBun, runGitInit } from './process.ts';
18
19
  import { installNpmPreset, withScratch } from './scratch.ts';
19
20
  import {
@@ -37,7 +38,7 @@ const LAYER_FILES = [
37
38
  /** `make dev` is the one command the Done message promises; the shipped Makefile has no such target. */
38
39
  const DEV_TARGET = '\ndev:\n\t@bun run dev\n';
39
40
 
40
- const BASE_IGNORES = ['node_modules/', 'dist/', '.env'];
41
+ const BASE_IGNORES = ['node_modules/', 'dist/', '.env', '*.tsbuildinfo'];
41
42
 
42
43
  const fail = (opts: { message: string }): number => {
43
44
  process.stderr.write(`vulcan init: ${opts.message}\n`);
@@ -333,7 +334,11 @@ const runCreate = async (opts: {
333
334
 
334
335
  // The preset's own port: nothing else is in this project yet, so it is the one the app listens on.
335
336
  process.stderr.write(
336
- `Done. Next:\n cd ${project} && make dev\n open http://localhost:${located.preset.devPort}\n`,
337
+ renderNext({
338
+ done: 'Done.',
339
+ command: `cd ${project} && make dev`,
340
+ apps: [{ port: located.preset.devPort, urls: located.preset.urls }],
341
+ }),
337
342
  );
338
343
 
339
344
  return ExitCodes.OK;
@@ -0,0 +1,53 @@
1
+ import { existsSync, readFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { readPort } from './workspace.ts';
4
+
5
+ /** One app of the monorepo as `make dev` serves it: its port, and the paths worth opening. */
6
+ export interface INextApp {
7
+ port: number;
8
+ urls: string[];
9
+ }
10
+
11
+ const readJson = (opts: { file: string }): Record<string, unknown> | undefined => {
12
+ try {
13
+ return JSON.parse(readFileSync(opts.file, 'utf8'));
14
+ } catch (error) {
15
+ console.error(
16
+ `[readJson] ${opts.file} | ${error instanceof Error ? error.message : String(error)}`,
17
+ );
18
+
19
+ return undefined;
20
+ }
21
+ };
22
+
23
+ /** The urls the preset recorded in the app's package.json at creation; none for an app made before. */
24
+ const readRecordedUrls = (opts: { directory: string }): string[] => {
25
+ const file = join(opts.directory, 'package.json');
26
+ const recorded = existsSync(file) ? readJson({ file })?.vulcan : undefined;
27
+ const urls = (recorded as { urls?: unknown } | undefined)?.urls;
28
+
29
+ return Array.isArray(urls) ? urls.filter(url => typeof url === 'string') : [];
30
+ };
31
+
32
+ /** The apps already in the monorepo: those with a `*PORT=` line in .env.example, as they were made. */
33
+ export const readExistingApps = (opts: { root: string; paths: string[] }): INextApp[] =>
34
+ opts.paths.flatMap(path => {
35
+ const directory = join(opts.root, path);
36
+ const envFile = join(directory, '.env.example');
37
+ const port = existsSync(envFile)
38
+ ? readPort({ envExample: readFileSync(envFile, 'utf8') })
39
+ : undefined;
40
+
41
+ return port === undefined ? [] : [{ port, urls: readRecordedUrls({ directory }) }];
42
+ });
43
+
44
+ /** The closing message: what ran, then one `open` line per url, or per app root when it has none. */
45
+ export const renderNext = (opts: { done: string; command: string; apps: INextApp[] }): string => {
46
+ const lines = opts.apps.flatMap(app =>
47
+ (app.urls.length === 0 ? [''] : app.urls).map(
48
+ path => ` open http://localhost:${app.port}${path}`,
49
+ ),
50
+ );
51
+
52
+ return `${opts.done} Next:\n ${opts.command}\n${lines.join('\n')}\n`;
53
+ };
@@ -28,6 +28,7 @@ const PRESET_SCHEMA = z
28
28
  peers: z.record(z.string(), z.string()).default({}),
29
29
  scripts: z.record(z.string(), z.string()).default({}),
30
30
  checks: z.array(z.string()).default([]),
31
+ urls: z.array(z.string().startsWith('/')).default([]),
31
32
  files: z.string(),
32
33
  atlas: z.array(z.object({ name: z.string(), repo: z.string(), ref: z.string() })).default([]),
33
34
  })
@@ -161,6 +161,8 @@ export const renderAppManifest = (opts: {
161
161
  },
162
162
  }),
163
163
  devDependencies: toCatalog({ dependencies: opts.preset.devDependencies }),
164
+ // What `add` prints later: this app's urls, since the preset is not at hand then.
165
+ ...(opts.preset.urls.length === 0 ? {} : { vulcan: { urls: opts.preset.urls } }),
164
166
  },
165
167
  });
166
168