@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.
@@ -0,0 +1,348 @@
1
+ import { existsSync, readdirSync, statSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { ExitCodes, ProjectLayout, VULCAN_VERSION } from '../common/index.ts';
4
+ import { renderTemplate } from '../init/index.ts';
5
+ import { runAppChecks } from './checks.ts';
6
+ import { AppSides, CreateFlags } from './common/index.ts';
7
+ import type {
8
+ IAppsBlock,
9
+ ILocatedPreset,
10
+ INameField,
11
+ IPresetSpec,
12
+ TAppSide,
13
+ } from './common/index.ts';
14
+ import { today, writeFile } from './files.ts';
15
+ import { askWithPrompt, findFolderClash, readFlag, resolveNames, SIDE_FIELDS } from './names.ts';
16
+ import { copyPresetFiles, locatePreset, parsePresetSpec } from './preset.ts';
17
+ import { renderNext } from './next.ts';
18
+ import { isInstallSkipped, runBun, runGitInit } from './process.ts';
19
+ import { installNpmPreset, withScratch } from './scratch.ts';
20
+ import {
21
+ filePresetWarning,
22
+ renderAppConcept,
23
+ renderAppManifest,
24
+ renderKnowledgeIndex,
25
+ renderLogEntry,
26
+ renderRootManifest,
27
+ renderVulcanConfig,
28
+ } from './workspace.ts';
29
+
30
+ /** The VULCAN layer files; the knowledge index is rendered from the apps, not copied. */
31
+ const LAYER_FILES = [
32
+ { path: 'AGENTS.md', template: 'AGENTS.md' },
33
+ { path: '.agents/rules.md', template: 'rules.md' },
34
+ { path: '.mcp.json', template: 'mcp.json' },
35
+ { path: 'Makefile', template: 'Makefile' },
36
+ ];
37
+
38
+ /** `make dev` is the one command the Done message promises; the shipped Makefile has no such target. */
39
+ const DEV_TARGET = '\ndev:\n\t@bun run dev\n';
40
+
41
+ const BASE_IGNORES = ['node_modules/', 'dist/', '.env', '*.tsbuildinfo'];
42
+
43
+ const fail = (opts: { message: string }): number => {
44
+ process.stderr.write(`vulcan init: ${opts.message}\n`);
45
+
46
+ return ExitCodes.FAILURE;
47
+ };
48
+
49
+ /** A folder that holds anything, or is not a folder, is not a place to create a project. */
50
+ const isOccupied = (opts: { path: string }): boolean =>
51
+ existsSync(opts.path) &&
52
+ (!statSync(opts.path).isDirectory() || readdirSync(opts.path).length > 0);
53
+
54
+ const appFields = (opts: { side?: TAppSide }): INameField[] => [
55
+ ...(opts.side === undefined ? [] : [SIDE_FIELDS[opts.side]]),
56
+ {
57
+ key: 'app',
58
+ flag: CreateFlags.APP,
59
+ question: opts.side === undefined ? 'Name of the first app' : `Name of this ${opts.side} app`,
60
+ },
61
+ {
62
+ key: 'shared',
63
+ flag: CreateFlags.SHARED_DIR,
64
+ question: 'Shared code folder (empty to skip)',
65
+ optional: true,
66
+ },
67
+ ];
68
+
69
+ const writeMonorepo = (opts: {
70
+ root: string;
71
+ project: string;
72
+ spec: IPresetSpec;
73
+ located: ILocatedPreset;
74
+ folder: string;
75
+ app: string;
76
+ shared: string;
77
+ }): void => {
78
+ const { root, project, spec, located, folder, app, shared } = opts;
79
+ const { preset, packageName, packageVersion } = located;
80
+ const side = preset.side;
81
+ const catalog = {
82
+ ...preset.dependencies,
83
+ ...preset.devDependencies,
84
+ [packageName]: spec.packageName === undefined ? spec.range : packageVersion,
85
+ };
86
+
87
+ writeFile({
88
+ root,
89
+ path: 'package.json',
90
+ content: renderRootManifest({
91
+ project,
92
+ workspaces: [`${folder}/*`, ...(shared === '' ? [] : [`${shared}/*`])],
93
+ catalog,
94
+ vulcanVersion: VULCAN_VERSION,
95
+ }),
96
+ });
97
+ writeFile({
98
+ root,
99
+ path: '.gitignore',
100
+ content: `${[...BASE_IGNORES, ...ProjectLayout.GITIGNORE_ENTRIES].join('\n')}\n`,
101
+ });
102
+ writeFile({ root, path: 'README.md', content: `# ${project}\n` });
103
+
104
+ if (shared !== '') {
105
+ writeFile({ root, path: `${shared}/.gitkeep`, content: '' });
106
+ }
107
+
108
+ // The first app: nothing uses a port yet, and a frontend has no backend to proxy to.
109
+ const appDirectory = join(root, folder, app);
110
+ const written = copyPresetFiles({
111
+ located,
112
+ target: appDirectory,
113
+ tokens: { project, app, devPort: String(preset.devPort), apiUrl: '' },
114
+ });
115
+
116
+ for (const path of written) {
117
+ process.stderr.write(` created ${folder}/${app}/${path}\n`);
118
+ }
119
+
120
+ writeFile({
121
+ root,
122
+ path: `${folder}/${app}/package.json`,
123
+ content: renderAppManifest({
124
+ app,
125
+ preset,
126
+ presetPackage: { name: packageName, version: packageVersion },
127
+ }),
128
+ });
129
+
130
+ for (const file of LAYER_FILES) {
131
+ const content = renderTemplate({ template: file.template, name: project });
132
+
133
+ writeFile({
134
+ root,
135
+ path: file.path,
136
+ content: file.path === 'Makefile' ? `${content}${DEV_TARGET}` : content,
137
+ });
138
+ }
139
+
140
+ const block: IAppsBlock = {
141
+ layout: { [side]: folder, ...(shared === '' ? {} : { shared }) },
142
+ packages: [{ dir: app, name: app, path: `${folder}/${app}` }],
143
+ sources: preset.atlas,
144
+ };
145
+
146
+ writeFile({
147
+ root,
148
+ path: '.configs/vulcan.config.mts',
149
+ content: renderVulcanConfig({ project, block }),
150
+ });
151
+ writeFile({
152
+ root,
153
+ path: '.agents/knowledge/index.md',
154
+ content: renderKnowledgeIndex({ project, apps: [{ name: app, summary: preset.summary }] }),
155
+ });
156
+ writeFile({
157
+ root,
158
+ path: `.agents/knowledge/packages/${app}.md`,
159
+ content: renderAppConcept({
160
+ app: { name: app, side, folder },
161
+ summary: preset.summary,
162
+ presetPackage: packageName,
163
+ }),
164
+ });
165
+ writeFile({
166
+ root,
167
+ path: '.agents/knowledge/log.md',
168
+ content: `# ${project} knowledge log\n\n${renderLogEntry({
169
+ date: today(),
170
+ text: `created from the ${packageName} ${packageVersion} preset: ${folder}/${app}`,
171
+ })}`,
172
+ });
173
+ };
174
+
175
+ const runCreate = async (opts: {
176
+ cwd: string;
177
+ args: string[];
178
+ scratch: string;
179
+ }): Promise<number> => {
180
+ const presetValue = readFlag({ args: opts.args, flag: CreateFlags.PRESET });
181
+
182
+ if (presetValue === undefined) {
183
+ return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
184
+ }
185
+
186
+ const spec = parsePresetSpec({ value: presetValue, cwd: opts.cwd });
187
+ const interactive = process.stdin.isTTY === true;
188
+ const first = resolveNames({
189
+ fields: [
190
+ { key: 'project', flag: CreateFlags.PROJECT, question: 'Project name (the monorepo folder)' },
191
+ ],
192
+ args: opts.args,
193
+ interactive,
194
+ ask: askWithPrompt,
195
+ });
196
+
197
+ if (!first.ok) {
198
+ return fail({ message: first.error });
199
+ }
200
+
201
+ const project = first.names.project;
202
+ const root = join(opts.cwd, project);
203
+
204
+ // Before any write: init only ever creates a project, so a folder with content is the user's.
205
+ if (isOccupied({ path: root })) {
206
+ return fail({
207
+ message: `${project} exists and is not empty - init --preset only creates a new project`,
208
+ });
209
+ }
210
+
211
+ const isNpm = spec.packageName !== undefined;
212
+
213
+ if (isNpm && isInstallSkipped()) {
214
+ return fail({ message: 'an npm preset needs an install - use file: in tests' });
215
+ }
216
+
217
+ let located: ILocatedPreset;
218
+ let names: Record<string, string>;
219
+
220
+ if (isNpm) {
221
+ // The side is known only once the package is read, so its folder is asked after the install.
222
+ const early = resolveNames({
223
+ fields: appFields({}),
224
+ args: opts.args,
225
+ interactive,
226
+ ask: askWithPrompt,
227
+ });
228
+
229
+ if (!early.ok) {
230
+ return fail({ message: early.error });
231
+ }
232
+
233
+ const installed = await installNpmPreset({ scratch: opts.scratch, spec });
234
+
235
+ if (installed !== ExitCodes.OK) {
236
+ return installed;
237
+ }
238
+
239
+ const result = locatePreset({ spec, root: opts.scratch });
240
+
241
+ if (!result.ok) {
242
+ return fail({ message: result.error });
243
+ }
244
+
245
+ located = result.located;
246
+
247
+ const folder = resolveNames({
248
+ fields: [SIDE_FIELDS[located.preset.side]],
249
+ args: opts.args,
250
+ interactive,
251
+ ask: askWithPrompt,
252
+ });
253
+
254
+ if (!folder.ok) {
255
+ return fail({ message: folder.error });
256
+ }
257
+
258
+ names = { ...early.names, ...folder.names };
259
+ } else {
260
+ const result = locatePreset({ spec, root });
261
+
262
+ if (!result.ok) {
263
+ return fail({ message: result.error });
264
+ }
265
+
266
+ located = result.located;
267
+
268
+ const rest = resolveNames({
269
+ fields: appFields({ side: located.preset.side }),
270
+ args: opts.args,
271
+ interactive,
272
+ ask: askWithPrompt,
273
+ });
274
+
275
+ if (!rest.ok) {
276
+ return fail({ message: rest.error });
277
+ }
278
+
279
+ names = rest.names;
280
+ }
281
+
282
+ const { folder, app, shared } = names;
283
+ const side = located.preset.side;
284
+ // The flag of the side this preset does not build still counts when given: it names a folder too.
285
+ const otherFlag =
286
+ SIDE_FIELDS[side === AppSides.BACKEND ? AppSides.FRONTEND : AppSides.BACKEND].flag;
287
+ const otherFolder = readFlag({ args: opts.args, flag: otherFlag });
288
+ const clash = findFolderClash({
289
+ folders: [
290
+ { flag: SIDE_FIELDS[side].flag, value: folder },
291
+ ...(otherFolder === undefined ? [] : [{ flag: otherFlag, value: otherFolder }]),
292
+ ...(shared === '' ? [] : [{ flag: CreateFlags.SHARED_DIR, value: shared }]),
293
+ ],
294
+ });
295
+
296
+ if (clash !== undefined) {
297
+ return fail({ message: clash });
298
+ }
299
+
300
+ const warning = filePresetWarning({
301
+ spec,
302
+ packageName: located.packageName,
303
+ });
304
+
305
+ if (warning !== undefined) {
306
+ process.stderr.write(`${warning}\n`);
307
+ }
308
+
309
+ writeMonorepo({ root, project, spec, located, folder, app, shared });
310
+
311
+ for (const step of [
312
+ () => runBun({ cwd: root, args: ['install'], label: 'bun install' }),
313
+ () => runGitInit({ cwd: root }),
314
+ // The installed CLI syncs, so the project is wired to the version it pins.
315
+ () =>
316
+ runBun({
317
+ cwd: root,
318
+ args: [join(root, 'node_modules', '.bin', 'vulcan'), 'sync'],
319
+ label: 'vulcan sync',
320
+ }),
321
+ () =>
322
+ runAppChecks({
323
+ root,
324
+ appDirectory: join(root, folder, app),
325
+ checks: located.preset.checks,
326
+ }),
327
+ ]) {
328
+ const code = await step();
329
+
330
+ if (code !== ExitCodes.OK) {
331
+ return code;
332
+ }
333
+ }
334
+
335
+ // The preset's own port: nothing else is in this project yet, so it is the one the app listens on.
336
+ process.stderr.write(
337
+ renderNext({
338
+ done: 'Done.',
339
+ command: `cd ${project} && make dev`,
340
+ apps: [{ port: located.preset.devPort, urls: located.preset.urls }],
341
+ }),
342
+ );
343
+
344
+ return ExitCodes.OK;
345
+ };
346
+
347
+ export const createMonorepo = async (opts: { cwd: string; args: string[] }): Promise<number> =>
348
+ withScratch({ run: scratch => runCreate({ ...opts, scratch }) });
@@ -0,0 +1,194 @@
1
+ import { readSync } from 'node:fs';
2
+
3
+ import { AppSides, CreateConstants, CreateFlags } from './common/index.ts';
4
+ import type { INameField, TAppSide, TAsk, TByteReader, TNamesResult } from './common/index.ts';
5
+
6
+ /** The folder holding every app of one side; `add` offers the one the config already holds. */
7
+ export const SIDE_FIELDS: Record<TAppSide, INameField> = {
8
+ [AppSides.BACKEND]: {
9
+ key: 'folder',
10
+ flag: CreateFlags.BACKEND_DIR,
11
+ question: 'Backend folder (holds every backend app)',
12
+ },
13
+ [AppSides.FRONTEND]: {
14
+ key: 'folder',
15
+ flag: CreateFlags.FRONTEND_DIR,
16
+ question: 'Frontend folder (holds every frontend app)',
17
+ },
18
+ };
19
+
20
+ export const readFlag = (opts: { args: string[]; flag: string }): string | undefined => {
21
+ const index = opts.args.indexOf(opts.flag);
22
+
23
+ return index === -1 ? undefined : opts.args[index + 1];
24
+ };
25
+
26
+ const isValidName = (opts: { name: string }): boolean =>
27
+ CreateConstants.NAME_PATTERN.test(opts.name);
28
+
29
+ const NEWLINE = 0x0a;
30
+ const CARRIAGE_RETURN = 0x0d;
31
+ const RETRY_PAUSE_MILLISECONDS = 5;
32
+
33
+ const readFromDescriptor: TByteReader = opts => readSync(opts.descriptor, opts.buffer, 0, 1, null);
34
+
35
+ /** A sleep that does not burn the CPU: nothing else runs on this thread while a prompt waits. */
36
+ const pauseBriefly = (): void => {
37
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, RETRY_PAUSE_MILLISECONDS);
38
+ };
39
+
40
+ const isWouldBlock = (opts: { error: unknown }): boolean =>
41
+ opts.error instanceof Error && 'code' in opts.error && opts.error.code === 'EAGAIN';
42
+
43
+ /**
44
+ * One line from a file descriptor, read byte by byte so nothing past the newline is consumed.
45
+ * Not Bun's prompt(): it returns null for an empty line, which is not end of input. An empty line
46
+ * is '' here; null is only end of input (Ctrl-D, closed stdin) with nothing read. `read` and `pause`
47
+ * are replaceable so a test can drive the non-blocking retry without a real pipe.
48
+ */
49
+ export const readLine = (opts: {
50
+ descriptor: number;
51
+ read?: TByteReader;
52
+ pause?: () => void;
53
+ }): string | null => {
54
+ const { descriptor, read = readFromDescriptor, pause = pauseBriefly } = opts;
55
+ const buffer = Buffer.alloc(1);
56
+ const bytes: number[] = [];
57
+
58
+ for (;;) {
59
+ let count = 0;
60
+
61
+ try {
62
+ count = read({ descriptor, buffer });
63
+ } catch (error) {
64
+ // A non-blocking pipe with nothing buffered yet: wait for the writer instead of failing.
65
+ if (isWouldBlock({ error })) {
66
+ pause();
67
+ continue;
68
+ }
69
+
70
+ throw error;
71
+ }
72
+
73
+ if (count === 0) {
74
+ return bytes.length === 0 ? null : Buffer.from(bytes).toString('utf8');
75
+ }
76
+
77
+ const value = buffer.readUInt8(0);
78
+
79
+ if (value === NEWLINE) {
80
+ break;
81
+ }
82
+
83
+ bytes.push(value);
84
+ }
85
+
86
+ if (bytes.at(-1) === CARRIAGE_RETURN) {
87
+ bytes.pop();
88
+ }
89
+
90
+ return Buffer.from(bytes).toString('utf8');
91
+ };
92
+
93
+ /** The shown default is the user's own earlier choice, never one VULCAN made up. */
94
+ export const askWithPrompt: TAsk = opts => {
95
+ process.stdout.write(
96
+ opts.previous === undefined
97
+ ? `? ${opts.question} > `
98
+ : `? ${opts.question} (${opts.previous}) > `,
99
+ );
100
+
101
+ return readLine({ descriptor: CreateConstants.STDIN_DESCRIPTOR });
102
+ };
103
+
104
+ const askUntilValid = (opts: { field: INameField; ask: TAsk }): string | null => {
105
+ for (;;) {
106
+ const answer = opts.ask({ question: opts.field.question, previous: opts.field.previous });
107
+
108
+ if (answer === null) {
109
+ return null;
110
+ }
111
+
112
+ const name = answer.trim() === '' ? (opts.field.previous ?? '') : answer.trim();
113
+
114
+ if (name === '' && opts.field.optional === true) {
115
+ return '';
116
+ }
117
+
118
+ if (isValidName({ name })) {
119
+ return name;
120
+ }
121
+
122
+ process.stderr.write(
123
+ ` '${name}' is not a name: lowercase letters, digits and '-', starting with a letter or digit\n`,
124
+ );
125
+ }
126
+ };
127
+
128
+ /** Every name from its flag; a missing one is asked in a TTY and an error otherwise. */
129
+ export const resolveNames = (opts: {
130
+ fields: INameField[];
131
+ args: string[];
132
+ interactive: boolean;
133
+ ask: TAsk;
134
+ }): TNamesResult => {
135
+ const names: Record<string, string> = {};
136
+
137
+ for (const field of opts.fields) {
138
+ const flagged = readFlag({ args: opts.args, flag: field.flag });
139
+
140
+ if (flagged !== undefined) {
141
+ if (!isValidName({ name: flagged })) {
142
+ return {
143
+ ok: false,
144
+ error: `${field.flag} '${flagged}' is not a name: lowercase letters, digits and '-'`,
145
+ };
146
+ }
147
+
148
+ names[field.key] = flagged;
149
+ continue;
150
+ }
151
+
152
+ if (!opts.interactive) {
153
+ if (field.optional === true) {
154
+ names[field.key] = '';
155
+ continue;
156
+ }
157
+
158
+ if (field.previous !== undefined) {
159
+ names[field.key] = field.previous;
160
+ continue;
161
+ }
162
+
163
+ return {
164
+ ok: false,
165
+ error: `missing ${field.flag} (${field.question}) - names are never chosen for you`,
166
+ };
167
+ }
168
+
169
+ const answer = askUntilValid({ field, ask: opts.ask });
170
+
171
+ if (answer === null) {
172
+ return { ok: false, error: 'aborted' };
173
+ }
174
+
175
+ names[field.key] = answer;
176
+ }
177
+
178
+ return { ok: true, names };
179
+ };
180
+
181
+ /** Two folders given the same name would mix kinds of code; the error names both flags. */
182
+ export const findFolderClash = (opts: {
183
+ folders: { flag: string; value: string }[];
184
+ }): string | undefined => {
185
+ for (const [index, first] of opts.folders.entries()) {
186
+ const second = opts.folders.slice(index + 1).find(other => other.value === first.value);
187
+
188
+ if (second !== undefined) {
189
+ return `${first.flag} and ${second.flag} both name '${first.value}' - each kind of code needs its own folder`;
190
+ }
191
+ }
192
+
193
+ return undefined;
194
+ };
@@ -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
+ };