@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,462 @@
1
+ import { existsSync, readFileSync } from 'node:fs';
2
+ import { join, relative } from 'node:path';
3
+ import { ExitCodes } from '../common/index.ts';
4
+ import { loadConfig, resolvePackages } from '../config/index.ts';
5
+ import type { IProjectPackage, TResolvedConfig } from '../config/index.ts';
6
+ import { readWorkspaceGlobs } from '../init/index.ts';
7
+ import { runAppChecks } from './checks.ts';
8
+ import { AppSides, CreateFlags } from './common/index.ts';
9
+ import type { IAppsBlock, ILocatedPreset, IPresetSpec, TAppSide } from './common/index.ts';
10
+ import { today, writeFile } from './files.ts';
11
+ import { askWithPrompt, readFlag, resolveNames, SIDE_FIELDS } from './names.ts';
12
+ import { readExistingApps, renderNext } from './next.ts';
13
+ import { copyPresetFiles, locatePreset, parsePresetSpec } from './preset.ts';
14
+ import { isInstallSkipped, runBun } from './process.ts';
15
+ import { installNpmPreset, withScratch } from './scratch.ts';
16
+ import {
17
+ addAppBullet,
18
+ checkPeers,
19
+ filePresetWarning,
20
+ parseAppsBlock,
21
+ pickPort,
22
+ planRootManifest,
23
+ readCatalog,
24
+ readPort,
25
+ renderAppConcept,
26
+ renderAppManifest,
27
+ renderKnowledgeIndex,
28
+ renderLogEntry,
29
+ replaceAppsBlock,
30
+ } from './workspace.ts';
31
+
32
+ type TRootManifest = Record<string, unknown>;
33
+
34
+ const KNOWLEDGE_DIRECTORY = '.agents/knowledge';
35
+ const ROOT_HINT =
36
+ 'run it at the root of a monorepo vulcan init created (no layout in .configs/vulcan.config.*)';
37
+
38
+ const MISSING_API = `missing ${CreateFlags.API} <app> or ${CreateFlags.NO_API}`;
39
+
40
+ const fail = (opts: { message: string }): number => {
41
+ process.stderr.write(`vulcan add: ${opts.message}\n`);
42
+
43
+ return ExitCodes.FAILURE;
44
+ };
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
+
96
+ const readRootManifest = (opts: { path: string }): TRootManifest | undefined => {
97
+ if (!existsSync(opts.path)) {
98
+ return undefined;
99
+ }
100
+
101
+ try {
102
+ return JSON.parse(readFileSync(opts.path, 'utf8'));
103
+ } catch (error) {
104
+ console.error(
105
+ `[readRootManifest] ${opts.path} | ${error instanceof Error ? error.message : String(error)}`,
106
+ );
107
+
108
+ return undefined;
109
+ }
110
+ };
111
+
112
+ /** The lines a user adds by hand when the apps block cannot be extended: only what is new. */
113
+ const literal = (opts: {
114
+ side: string;
115
+ folder: string;
116
+ app: IAppsBlock['packages'][number];
117
+ sources: IAppsBlock['sources'];
118
+ }): string[] => [
119
+ ` layout: { ${opts.side}: '${opts.folder}' },`,
120
+ ` packages: { dir: '${opts.app.dir}', name: '${opts.app.name}', path: '${opts.app.path}' },`,
121
+ ...opts.sources.map(
122
+ source =>
123
+ ` sources: { name: '${source.name}', repo: '${source.repo}', ref: '${source.ref}' },`,
124
+ ),
125
+ ];
126
+
127
+ /** A frontend's proxy target: the chosen backend app's port, or nothing when it has no backend. */
128
+ const resolveApiUrl = (opts: {
129
+ root: string;
130
+ args: string[];
131
+ interactive: boolean;
132
+ backendFolder: string | undefined;
133
+ packages: IProjectPackage[];
134
+ }): { ok: true; apiUrl: string } | { ok: false; error: string } => {
135
+ if (opts.args.includes(CreateFlags.NO_API)) {
136
+ return { ok: true, apiUrl: '' };
137
+ }
138
+
139
+ let chosen = readFlag({ args: opts.args, flag: CreateFlags.API });
140
+
141
+ if (chosen === undefined) {
142
+ if (!opts.interactive) {
143
+ return { ok: false, error: MISSING_API };
144
+ }
145
+
146
+ chosen =
147
+ askWithPrompt({ question: 'Backend app to proxy /api to (empty for none)' })?.trim() ?? '';
148
+
149
+ if (chosen === '') {
150
+ return { ok: true, apiUrl: '' };
151
+ }
152
+ }
153
+
154
+ const backend = opts.packages.find(
155
+ entry =>
156
+ entry.dir === chosen &&
157
+ opts.backendFolder !== undefined &&
158
+ entry.path.startsWith(`${opts.backendFolder}/`),
159
+ );
160
+
161
+ if (backend === undefined) {
162
+ return {
163
+ ok: false,
164
+ error: `${CreateFlags.API} '${chosen}' is not a backend app of this monorepo`,
165
+ };
166
+ }
167
+
168
+ const envFile = join(opts.root, backend.path, '.env.example');
169
+ const port = existsSync(envFile)
170
+ ? readPort({ envExample: readFileSync(envFile, 'utf8') })
171
+ : undefined;
172
+
173
+ if (port === undefined) {
174
+ return {
175
+ ok: false,
176
+ error: `no *PORT=<number> line in ${backend.path}/.env.example to proxy to`,
177
+ };
178
+ }
179
+
180
+ return { ok: true, apiUrl: `http://localhost:${port}` };
181
+ };
182
+
183
+ const usedPorts = (opts: { root: string; packages: IProjectPackage[] }): number[] =>
184
+ readExistingApps({ root: opts.root, paths: opts.packages.map(entry => entry.path) }).map(
185
+ app => app.port,
186
+ );
187
+
188
+ const locate = async (opts: {
189
+ cwd: string;
190
+ scratch: string;
191
+ spec: IPresetSpec;
192
+ }): Promise<{ ok: true; located: ILocatedPreset } | { ok: false; error: string }> => {
193
+ if (opts.spec.packageName === undefined) {
194
+ return locatePreset({ spec: opts.spec, root: opts.cwd });
195
+ }
196
+
197
+ if (isInstallSkipped()) {
198
+ return { ok: false, error: 'an npm preset needs an install - use file: in tests' };
199
+ }
200
+
201
+ const installed = await installNpmPreset({ scratch: opts.scratch, spec: opts.spec });
202
+
203
+ return installed === ExitCodes.OK
204
+ ? locatePreset({ spec: opts.spec, root: opts.scratch })
205
+ : { ok: false, error: `could not install ${opts.spec.packageName}@${opts.spec.range}` };
206
+ };
207
+
208
+ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): Promise<number> => {
209
+ const { cwd } = opts;
210
+ const presetValue = readFlag({ args: opts.args, flag: CreateFlags.PRESET });
211
+
212
+ if (presetValue === undefined) {
213
+ return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
214
+ }
215
+
216
+ const loaded = await loadConfig({ root: cwd });
217
+
218
+ if (!loaded.ok) {
219
+ return fail({ message: loaded.file === undefined ? ROOT_HINT : loaded.error });
220
+ }
221
+
222
+ const config: TResolvedConfig = loaded.config;
223
+ const configPath = relative(cwd, loaded.file);
224
+ const manifestPath = join(cwd, 'package.json');
225
+ const manifest = readRootManifest({ path: manifestPath });
226
+
227
+ if (config.layout === undefined || manifest === undefined) {
228
+ return fail({ message: ROOT_HINT });
229
+ }
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
+
238
+ const spec = parsePresetSpec({ value: presetValue, cwd });
239
+ const located = await locate({ cwd, scratch: opts.scratch, spec });
240
+
241
+ if (!located.ok) {
242
+ return fail({ message: located.error });
243
+ }
244
+
245
+ const { preset, packageName, packageVersion } = located.located;
246
+ // Before any question: a catalog the preset cannot live in is no reason to ask for names.
247
+ const peerProblem = checkPeers({
248
+ catalog: readCatalog({ manifest }),
249
+ peers: preset.peers,
250
+ });
251
+
252
+ if (peerProblem !== undefined) {
253
+ return fail({ message: peerProblem });
254
+ }
255
+
256
+ const side = preset.side;
257
+ const previous = config.layout[side];
258
+ const names = resolveNames({
259
+ fields: [
260
+ { ...SIDE_FIELDS[side], previous },
261
+ { key: 'app', flag: CreateFlags.APP, question: `Name of this ${side} app` },
262
+ ],
263
+ args: opts.args,
264
+ interactive,
265
+ ask: askWithPrompt,
266
+ });
267
+
268
+ if (!names.ok) {
269
+ return fail({ message: names.error });
270
+ }
271
+
272
+ const { folder, app } = names.names;
273
+
274
+ // layout holds one folder per side, so a different answer would strand the apps already there.
275
+ if (previous !== undefined && folder !== previous) {
276
+ return fail({
277
+ message: `the ${side} folder is '${previous}' in ${configPath}; apps of one side share it, not '${folder}'`,
278
+ });
279
+ }
280
+
281
+ const otherSide = Object.entries(config.layout).find(
282
+ ([key, value]) => key !== side && value === folder,
283
+ );
284
+
285
+ // One folder holds one kind of code: a folder another side already owns would mix them.
286
+ if (otherSide !== undefined) {
287
+ return fail({
288
+ message: `the ${side} folder '${folder}' is the ${otherSide[0]} folder in ${configPath}; each kind of code needs its own folder`,
289
+ });
290
+ }
291
+
292
+ const packages = resolvePackages({ config });
293
+
294
+ if (existsSync(join(cwd, folder, app)) || packages.some(entry => entry.dir === app)) {
295
+ return fail({ message: `${folder}/${app} already exists` });
296
+ }
297
+
298
+ const devPort = pickPort({ preferred: preset.devPort, used: usedPorts({ root: cwd, packages }) });
299
+ let apiUrl = '';
300
+
301
+ if (side === AppSides.FRONTEND) {
302
+ const api = resolveApiUrl({
303
+ root: cwd,
304
+ args: opts.args,
305
+ interactive,
306
+ backendFolder: config.layout.backend,
307
+ packages,
308
+ });
309
+
310
+ if (!api.ok) {
311
+ return fail({ message: api.error });
312
+ }
313
+
314
+ apiUrl = api.apiUrl;
315
+ }
316
+
317
+ const source = readFileSync(loaded.file, 'utf8');
318
+ const entry = { dir: app, name: app, path: `${folder}/${app}` };
319
+ const knownSources = new Set(config.atlas.sources.map(known => known.name));
320
+ const newSources = preset.atlas.filter(candidate => !knownSources.has(candidate.name));
321
+ const parsed = parseAppsBlock({ source });
322
+
323
+ // The user's config is theirs: with the block gone or no longer JSON it is never rewritten, only described.
324
+ if (!parsed.ok) {
325
+ return fail({
326
+ message: [
327
+ parsed.reason === 'missing'
328
+ ? `the vulcan:apps block is gone from ${configPath} - add by hand:`
329
+ : `the vulcan:apps block in ${configPath} is not the JSON vulcan wrote - add by hand:`,
330
+ ...literal({ side, folder, app: entry, sources: newSources }),
331
+ ].join('\n'),
332
+ });
333
+ }
334
+
335
+ // Extend what the markers hold: the resolved config also carries what the user added outside them.
336
+ const block: IAppsBlock = {
337
+ layout: { ...parsed.block.layout, [side]: folder },
338
+ packages: [...parsed.block.packages, entry],
339
+ sources: [
340
+ ...parsed.block.sources,
341
+ ...newSources.filter(
342
+ candidate => !parsed.block.sources.some(existing => existing.name === candidate.name),
343
+ ),
344
+ ],
345
+ };
346
+ const nextConfig = replaceAppsBlock({ source, block });
347
+
348
+ if (nextConfig === undefined) {
349
+ return fail({ message: ROOT_HINT });
350
+ }
351
+
352
+ const project = config.name ?? (typeof manifest.name === 'string' ? manifest.name : app);
353
+
354
+ const warning = filePresetWarning({ spec, packageName });
355
+
356
+ if (warning !== undefined) {
357
+ process.stderr.write(`${warning}\n`);
358
+ }
359
+
360
+ copyPresetFiles({
361
+ located: located.located,
362
+ target: join(cwd, folder, app),
363
+ tokens: { project, app, devPort: String(devPort), apiUrl },
364
+ });
365
+ writeFile({
366
+ root: cwd,
367
+ path: `${folder}/${app}/package.json`,
368
+ content: renderAppManifest({
369
+ app,
370
+ preset,
371
+ presetPackage: { name: packageName, version: packageVersion },
372
+ }),
373
+ });
374
+
375
+ const nextManifest = planRootManifest({
376
+ manifest,
377
+ globs: readWorkspaceGlobs({ root: cwd }),
378
+ folder,
379
+ additions: {
380
+ ...preset.dependencies,
381
+ ...preset.devDependencies,
382
+ [packageName]: spec.packageName === undefined ? spec.range : packageVersion,
383
+ },
384
+ });
385
+
386
+ writeFile({
387
+ root: cwd,
388
+ path: 'package.json',
389
+ content: `${JSON.stringify(nextManifest, null, 2)}\n`,
390
+ });
391
+ writeFile({ root: cwd, path: configPath, content: nextConfig });
392
+ writeFile({
393
+ root: cwd,
394
+ path: `${KNOWLEDGE_DIRECTORY}/packages/${app}.md`,
395
+ content: renderAppConcept({
396
+ app: { name: app, side, folder },
397
+ summary: preset.summary,
398
+ presetPackage: packageName,
399
+ }),
400
+ });
401
+ const indexPath = join(cwd, KNOWLEDGE_DIRECTORY, 'index.md');
402
+
403
+ writeFile({
404
+ root: cwd,
405
+ path: `${KNOWLEDGE_DIRECTORY}/index.md`,
406
+ content: existsSync(indexPath)
407
+ ? addAppBullet({
408
+ source: readFileSync(indexPath, 'utf8'),
409
+ app: { name: app, summary: preset.summary },
410
+ })
411
+ : renderKnowledgeIndex({ project, apps: [{ name: app, summary: preset.summary }] }),
412
+ });
413
+
414
+ const logPath = join(cwd, KNOWLEDGE_DIRECTORY, 'log.md');
415
+ const logEntry = renderLogEntry({
416
+ date: today(),
417
+ text: `added ${folder}/${app} from the ${packageName} ${packageVersion} preset`,
418
+ });
419
+
420
+ writeFile({
421
+ root: cwd,
422
+ path: `${KNOWLEDGE_DIRECTORY}/log.md`,
423
+ content: existsSync(logPath)
424
+ ? `${readFileSync(logPath, 'utf8').trimEnd()}\n\n${logEntry}`
425
+ : `# ${project} knowledge log\n\n${logEntry}`,
426
+ });
427
+
428
+ for (const step of [
429
+ () => runBun({ cwd, args: ['install'], label: 'bun install' }),
430
+ // The installed CLI syncs, so the project is wired to the version it pins.
431
+ () =>
432
+ runBun({
433
+ cwd,
434
+ args: [join(cwd, 'node_modules', '.bin', 'vulcan'), 'sync'],
435
+ label: 'vulcan sync',
436
+ }),
437
+ () => runAppChecks({ root: cwd, appDirectory: join(cwd, folder, app), checks: preset.checks }),
438
+ ]) {
439
+ const code = await step();
440
+
441
+ if (code !== ExitCodes.OK) {
442
+ return code;
443
+ }
444
+ }
445
+
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
+ );
457
+
458
+ return ExitCodes.OK;
459
+ };
460
+
461
+ export const addApp = async (opts: { cwd: string; args: string[] }): Promise<number> =>
462
+ withScratch({ run: scratch => runAdd({ ...opts, scratch }) });
@@ -0,0 +1,45 @@
1
+ import { join } from 'node:path';
2
+ import { ExitCodes, ProjectLayout } from '../common/index.ts';
3
+ import { runBun } from './process.ts';
4
+
5
+ /** The preset's own checks in the app, then the contract at the root; the first failure stops. */
6
+ export const runAppChecks = async (opts: {
7
+ root: string;
8
+ appDirectory: string;
9
+ checks: string[];
10
+ }): Promise<number> => {
11
+ for (const check of opts.checks) {
12
+ const code = await runBun({
13
+ cwd: opts.appDirectory,
14
+ args: ['run', check],
15
+ label: `bun run ${check} (${opts.appDirectory})`,
16
+ });
17
+
18
+ if (code !== ExitCodes.OK) {
19
+ process.stderr.write(
20
+ `vulcan: 'bun run ${check}' failed in ${opts.appDirectory} - the project is left as is for you to inspect\n`,
21
+ );
22
+
23
+ return code;
24
+ }
25
+ }
26
+
27
+ const bin = join(opts.root, 'node_modules', '.bin', 'vulcan');
28
+
29
+ for (const args of [
30
+ [bin, 'doctor'],
31
+ [bin, 'x', 'okf', 'check', '--strict'],
32
+ ]) {
33
+ const code = await runBun({
34
+ cwd: opts.root,
35
+ args,
36
+ label: `${ProjectLayout.VULCAN_COMMAND} ${args.slice(1).join(' ')}`,
37
+ });
38
+
39
+ if (code !== ExitCodes.OK) {
40
+ return code;
41
+ }
42
+ }
43
+
44
+ return ExitCodes.OK;
45
+ };
@@ -0,0 +1,51 @@
1
+ export class AppSides {
2
+ static readonly BACKEND = 'backend';
3
+ static readonly FRONTEND = 'frontend';
4
+ static readonly SCHEME_SET = new Set<string>([this.BACKEND, this.FRONTEND]);
5
+ static isValid(value: string): boolean {
6
+ return this.SCHEME_SET.has(value);
7
+ }
8
+ }
9
+
10
+ export class CreateConstants {
11
+ static readonly NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
12
+ /** A plain version with an optional prerelease and build part; ranges and URLs are not one. */
13
+ static readonly VERSION_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
14
+ static readonly PRERELEASE_PATTERN = /^\d+\.\d+\.\d+-/;
15
+ static readonly PRESET_FIELD = 'vulcan';
16
+ static readonly PRESET_VERSION = 1;
17
+ /** A preset named without a scope is a package in the framework scope. */
18
+ static readonly PRESET_SCOPE = '@venizia/';
19
+ static readonly PRESET_FILE_PREFIX = 'file:';
20
+ /**
21
+ * npm drops these dotfiles from a tarball, so a preset ships them under the `_` name. The list is
22
+ * explicit: a blanket `_` rule would rename `__root.tsx`, `_app.tsx` and `_redirects`.
23
+ */
24
+ static readonly PRESET_DOTFILE_NAMES: readonly string[] = [
25
+ '_gitignore',
26
+ '_npmrc',
27
+ '_env',
28
+ '_env.example',
29
+ ];
30
+ static readonly STDIN_DESCRIPTOR = 0;
31
+ /** Tests only: set to `1`, every install, git and check command is printed as skipped instead of run. */
32
+ static readonly NO_INSTALL_ENV = 'VULCAN_NO_INSTALL';
33
+ /** Tests only: a path that stands in for the `bun` executable, so a test fakes success or failure. */
34
+ static readonly BUN_ENV = 'VULCAN_BUN';
35
+ /** Tests only: a path that stands in for the `git` executable. */
36
+ static readonly GIT_ENV = 'VULCAN_GIT';
37
+ static readonly APPS_BLOCK_START =
38
+ '// vulcan:apps:start - written by vulcan init and add; edit outside this block';
39
+ static readonly APPS_BLOCK_END = '// vulcan:apps:end';
40
+ }
41
+
42
+ export class CreateFlags {
43
+ static readonly PRESET = '--preset';
44
+ static readonly PROJECT = '--project';
45
+ static readonly BACKEND_DIR = '--backend-dir';
46
+ static readonly FRONTEND_DIR = '--frontend-dir';
47
+ static readonly SHARED_DIR = '--shared-dir';
48
+ static readonly APP = '--app';
49
+ static readonly API = '--api';
50
+ static readonly NO_API = '--no-api';
51
+ }
@@ -0,0 +1,2 @@
1
+ export * from './constants.ts';
2
+ export * from './types.ts';
@@ -0,0 +1,78 @@
1
+ import type { TConstValue } from '../../common/index.ts';
2
+ import type { AppSides } from './constants.ts';
3
+
4
+ export type TAppSide = TConstValue<typeof AppSides>;
5
+
6
+ /** One name init or add needs: the flag that carries it, the question that asks it. */
7
+ export interface INameField {
8
+ key: string;
9
+ flag: string;
10
+ question: string;
11
+ /** Only the shared folder may be left empty. */
12
+ optional?: boolean;
13
+ /** A folder the user chose before, offered as the answer; never a name VULCAN made up. */
14
+ previous?: string;
15
+ }
16
+
17
+ export type TAsk = (opts: { question: string; previous?: string }) => string | null;
18
+
19
+ /** Reads at most one byte into `buffer` and returns how many were read; 0 is end of input. */
20
+ export type TByteReader = (opts: { descriptor: number; buffer: Buffer }) => number;
21
+
22
+ export type TNamesResult =
23
+ | { ok: true; names: Record<string, string> }
24
+ | { ok: false; error: string };
25
+
26
+ export interface IPresetAtlasSource {
27
+ name: string;
28
+ repo: string;
29
+ ref: string;
30
+ }
31
+
32
+ export interface IPreset {
33
+ presetVersion: number;
34
+ side: TAppSide;
35
+ summary: string;
36
+ devPort: number;
37
+ dependencies: Record<string, string>;
38
+ devDependencies: Record<string, string>;
39
+ /** Peer ranges the monorepo's existing catalog must satisfy (a framework's range on its base). */
40
+ peers: Record<string, string>;
41
+ scripts: Record<string, string>;
42
+ checks: string[];
43
+ /** Paths under the dev port worth opening (`/api/hello`); none means the root. */
44
+ urls: string[];
45
+ /** The folder holding the files to copy, absolute once the preset is located. */
46
+ files: string;
47
+ atlas: IPresetAtlasSource[];
48
+ }
49
+
50
+ export interface IPresetSpec {
51
+ /** The npm name, or undefined for a `file:` path. */
52
+ packageName?: string;
53
+ /** What goes after the name in a dependency: a version, a tag, or `file:<abs path>`. */
54
+ range: string;
55
+ }
56
+
57
+ export interface ILocatedPreset {
58
+ preset: IPreset;
59
+ /** The preset package's root directory. */
60
+ packageRoot: string;
61
+ packageName: string;
62
+ packageVersion: string;
63
+ }
64
+
65
+ export type TPresetResult = { ok: true; located: ILocatedPreset } | { ok: false; error: string };
66
+
67
+ export interface IApp {
68
+ name: string;
69
+ side: TAppSide;
70
+ folder: string;
71
+ }
72
+
73
+ /** What `init` and `add` own in the config: the layout, the package list and the atlas sources. */
74
+ export interface IAppsBlock {
75
+ layout: { backend?: string; frontend?: string; shared?: string };
76
+ packages: { dir: string; name: string; path: string }[];
77
+ sources: { name: string; repo: string; ref: string }[];
78
+ }
@@ -0,0 +1,10 @@
1
+ import { mkdirSync, writeFileSync } from 'node:fs';
2
+ import { dirname, join } from 'node:path';
3
+
4
+ export const today = (): string => new Date().toISOString().slice(0, 10);
5
+
6
+ export const writeFile = (opts: { root: string; path: string; content: string }): void => {
7
+ mkdirSync(dirname(join(opts.root, opts.path)), { recursive: true });
8
+ writeFileSync(join(opts.root, opts.path), opts.content);
9
+ process.stderr.write(` created ${opts.path}\n`);
10
+ };
@@ -0,0 +1,4 @@
1
+ export * from './common/index.ts';
2
+ export * from './names.ts';
3
+ export * from './preset.ts';
4
+ export * from './workspace.ts';