@venizia/vulcan 0.3.9 → 0.3.11

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.
@@ -1,12 +1,14 @@
1
1
  ---
2
2
  name: docs-writing
3
- description: Reader-first writing method for ALL of the project's documentation. Use this EVERY time you write or edit anything a human will read - wiki pages, READMEs, changelogs, references, guides, the knowledge bundle (.agents/knowledge), or when asked to "document" a feature - even when the request never says "docs". Also use it when reviewing or simplifying existing documentation.
3
+ description: Reader-first writing method for ALL of the project's documentation. Use when you write or edit anything a human will read - wiki pages, READMEs, changelogs, references, guides, the knowledge bundle (.agents/knowledge), or when asked to "document" a feature, even when the request never says "docs", and when reviewing or simplifying existing documentation.
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
6
6
  ---
7
7
 
8
8
  # Docs Writing - think like a reader, write like a writer
9
9
 
10
+ **Be extremely concise. Sacrifice grammar for the sake of concision.**
11
+
10
12
  One goal: a reader opens the page and knows within seconds what it is about, and can act on it after one read. We never prove that a topic is deep. We make it feel easy.
11
13
 
12
14
  The method has four steps. Do them in order.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.3.9",
3
+ "version": "0.3.11",
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": {
@@ -34,27 +34,28 @@
34
34
  "LICENSE.md",
35
35
  "src",
36
36
  "base",
37
- "!src/__tests__"
37
+ "!**/__tests__",
38
+ "!**/*.tsbuildinfo"
38
39
  ],
39
40
  "publishConfig": {
40
41
  "access": "public"
41
42
  },
42
43
  "scripts": {
43
44
  "force-update": "sh ../../scripts/force-update.sh",
44
- "test": "NODE_ENV=test bun test --env-file=.env.test"
45
+ "test": "bun test"
45
46
  },
46
47
  "dependencies": {
47
48
  "@clack/prompts": "1.8.1",
48
- "@venizia/vulcan-atlas": "0.3.9",
49
- "@venizia/vulcan-okf": "0.3.9",
50
- "zod": "^4.5.4"
49
+ "@venizia/vulcan-atlas": "0.3.11",
50
+ "@venizia/vulcan-okf": "0.3.11",
51
+ "zod": "^4.6.7"
51
52
  },
52
53
  "devDependencies": {
53
- "@types/bun": "1.4.1",
54
- "@venizia/dev-configs": "0.3.1-0",
55
- "eslint": "10.10.0",
56
- "oxfmt": "0.73.0",
57
- "oxlint": "1.88.0",
54
+ "@types/bun": "1.4.3",
55
+ "@venizia/dev-configs": "0.3.5",
56
+ "eslint": "10.13.0",
57
+ "oxfmt": "0.74.0",
58
+ "oxlint": "1.89.0",
58
59
  "oxlint-tsgolint": "7.0.2004",
59
60
  "typescript": "^6.0.3"
60
61
  },
@@ -6,13 +6,15 @@ Usage: bun x vulcan <command>
6
6
 
7
7
  init [--config ts|mts|mjs|js] Scaffold the project layer (never overwrites)
8
8
  init --preset <name|file:path> --project <name> --app <name> [--backend-dir|--frontend-dir <name>]
9
- [--shared-dir <name>] Create a monorepo with its first app, from a framework preset
9
+ [--shared-dir <name>] [--scope <@scope>]
10
+ Create a monorepo with its first app, from a framework preset
10
11
  (a name missing from the flags is asked in a terminal)
11
12
  add --preset <name|file:path> (--app <name> | --lib <name>) [--dir <folder>] [--scope <@scope>]
12
13
  [--backend-dir|--frontend-dir <name>] [--api <app> | --no-api]
13
14
  Add an app or a shared library to the monorepo (a frontend says which
14
- backend to proxy to; --dir and --scope are for a library; a terminal
15
- asks for the kind and every name the flags leave out)
15
+ backend to proxy to; --dir is for a library; --scope names the package
16
+ @scope/<name>, for an app or a library; a terminal asks for the kind
17
+ and every name the flags leave out)
16
18
  sync [--agents <list>|list] [--dry-run] [--prune]
17
19
  Write the adapters of the agents you chose (--agents claude,omp or none,
18
20
  stored in .agents/vulcan.local.json; --agents list shows the table);
@@ -15,9 +15,11 @@ import { askPresetSpec } from './preset-menu.ts';
15
15
  import { ABORTED, confirmWrite, planLines } from './plan.ts';
16
16
  import {
17
17
  askInTerminal,
18
+ askScope,
18
19
  askWithPrompt,
19
20
  nameProblem,
20
21
  readFlag,
22
+ readScope,
21
23
  resolveNames,
22
24
  SIDE_FIELDS,
23
25
  } from './names.ts';
@@ -329,6 +331,12 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
329
331
  return fail({ message: `${CreateFlags.APP} and ${CreateFlags.LIB} cannot be used together` });
330
332
  }
331
333
 
334
+ const flaggedScope = readScope({ args: opts.args });
335
+
336
+ if (!flaggedScope.ok) {
337
+ return fail({ message: flaggedScope.error });
338
+ }
339
+
332
340
  if (libFlag && libName === undefined) {
333
341
  return fail({ message: `${CreateFlags.LIB} needs a name` });
334
342
  }
@@ -452,9 +460,20 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
452
460
  });
453
461
  }
454
462
 
463
+ // Optional, asked only where menus are drawn; a plain terminal and a script give --scope.
464
+ const scope = flaggedScope.scope ?? (menusAvailable() ? await askScope() : undefined);
465
+
466
+ if (scope === null) {
467
+ return fail({ message: ABORTED });
468
+ }
469
+
470
+ const packageOfApp = scope === undefined ? app : `${scope}/${app}`;
455
471
  const packages = resolvePackages({ config });
456
472
 
457
- if (existsSync(join(cwd, folder, app)) || packages.some(entry => entry.dir === app)) {
473
+ if (
474
+ existsSync(join(cwd, folder, app)) ||
475
+ packages.some(entry => entry.dir === app || entry.name === packageOfApp)
476
+ ) {
458
477
  return fail({ message: `${folder}/${app} already exists` });
459
478
  }
460
479
 
@@ -478,7 +497,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
478
497
  }
479
498
 
480
499
  const source = readFileSync(loaded.file, 'utf8');
481
- const entry = { dir: app, name: app, path: `${folder}/${app}` };
500
+ const entry = { dir: app, name: packageOfApp, path: `${folder}/${app}` };
482
501
  const knownSources = new Set(config.atlas.sources.map(known => known.name));
483
502
  const newSources = preset.atlas.filter(candidate => !knownSources.has(candidate.name));
484
503
  const parsed = parseAppsBlock({ source });
@@ -538,6 +557,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
538
557
  lines: planLines({
539
558
  rows: [
540
559
  ['app', `${folder}/${app}`],
560
+ ...(scope === undefined ? [] : [['package', packageOfApp] as [string, string]]),
541
561
  ['side', side],
542
562
  ['preset', `${packageName} ${packageVersion}`],
543
563
  ['port', String(devPort)],
@@ -562,6 +582,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
562
582
  path: `${folder}/${app}/package.json`,
563
583
  content: renderAppManifest({
564
584
  app,
585
+ name: packageOfApp,
565
586
  preset,
566
587
  presetPackage: { name: packageName, version: packageVersion },
567
588
  }),
@@ -10,7 +10,7 @@ import { today, writeFile } from './files.ts';
10
10
  import { readLibPreset } from './lib-preset.ts';
11
11
  import type { TLibPreset } from './lib-preset.ts';
12
12
  import { ABORTED, confirmWrite, planLines } from './plan.ts';
13
- import { askInTerminal, readFlag } from './names.ts';
13
+ import { askInTerminal, readFlag, SCOPE_PATTERN } from './names.ts';
14
14
  import { copyPresetFiles } from './preset.ts';
15
15
  import { runBun } from './process.ts';
16
16
  import {
@@ -26,7 +26,6 @@ import {
26
26
  } from './workspace.ts';
27
27
 
28
28
  const KNOWLEDGE_DIRECTORY = '.agents/knowledge';
29
- const SCOPE_PATTERN = /^@[a-z0-9][a-z0-9-]*$/;
30
29
  const DIRECTORY_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
31
30
 
32
31
  const fail = (opts: { message: string }): number => {
@@ -0,0 +1,11 @@
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.
5
+ */
6
+ export const renderBunfig = (): string =>
7
+ [
8
+ '# Bun reads this file only from the directory a command runs in, so it sits at the root.',
9
+ 'telemetry = false',
10
+ '',
11
+ ].join('\n');
@@ -72,7 +72,7 @@ export interface IPresetSpec {
72
72
 
73
73
  export interface ILocatedPreset {
74
74
  preset: IPreset;
75
- /** The lib preset file (`vulcan.lib`), absolute and inside the package; absent when the preset makes apps only. */
75
+ /** The lib preset file (`vulcan.presets.lib`), absolute and inside the package; absent when the preset makes apps only. */
76
76
  libFile?: string;
77
77
  /** The preset package's root directory. */
78
78
  packageRoot: string;
@@ -13,11 +13,20 @@ import type {
13
13
  } from './common/index.ts';
14
14
  import { today, writeFile } from './files.ts';
15
15
  import { recordedPresetOf } from './lib-preset.ts';
16
+ import { renderBunfig } from './bunfig.ts';
16
17
  import { renderDockerignore } from './dockerignore.ts';
17
18
  import { menusAvailable } from '../ui/index.ts';
18
19
  import { askPresetSpec } from './preset-menu.ts';
19
20
  import { ABORTED, confirmWrite, planLines } from './plan.ts';
20
- import { askInTerminal, findFolderClash, readFlag, resolveNames, SIDE_FIELDS } from './names.ts';
21
+ import {
22
+ askInTerminal,
23
+ askScope,
24
+ findFolderClash,
25
+ readFlag,
26
+ readScope,
27
+ resolveNames,
28
+ SIDE_FIELDS,
29
+ } from './names.ts';
21
30
  import { copyPresetFiles, locatePreset, parsePresetSpec } from './preset.ts';
22
31
  import { renderNext } from './next.ts';
23
32
  import { isInstallSkipped, runBun, runGitInit } from './process.ts';
@@ -80,9 +89,12 @@ const writeMonorepo = (opts: {
80
89
  located: ILocatedPreset;
81
90
  folder: string;
82
91
  app: string;
92
+ /** `@scope` for the app's package name; the folder stays bare. */
93
+ scope: string | undefined;
83
94
  shared: string;
84
95
  }): void => {
85
- const { root, project, spec, presetValue, located, folder, app, shared } = opts;
96
+ const { root, project, spec, presetValue, located, folder, app, shared, scope } = opts;
97
+ const packageOfApp = scope === undefined ? app : `${scope}/${app}`;
86
98
  const { preset, packageName, packageVersion } = located;
87
99
  const side = preset.side;
88
100
  const catalog = {
@@ -108,6 +120,7 @@ const writeMonorepo = (opts: {
108
120
  });
109
121
  writeFile({ root, path: 'README.md', content: `# ${project}\n` });
110
122
  writeFile({ root, path: '.dockerignore', content: renderDockerignore() });
123
+ writeFile({ root, path: 'bunfig.toml', content: renderBunfig() });
111
124
 
112
125
  if (shared !== '') {
113
126
  writeFile({ root, path: `${shared}/.gitkeep`, content: '' });
@@ -136,6 +149,7 @@ const writeMonorepo = (opts: {
136
149
  path: `${folder}/${app}/package.json`,
137
150
  content: renderAppManifest({
138
151
  app,
152
+ name: packageOfApp,
139
153
  preset,
140
154
  presetPackage: { name: packageName, version: packageVersion },
141
155
  }),
@@ -153,7 +167,7 @@ const writeMonorepo = (opts: {
153
167
 
154
168
  const block: IAppsBlock = {
155
169
  layout: { [side]: folder, ...(shared === '' ? {} : { shared }) },
156
- packages: [{ dir: app, name: app, path: `${folder}/${app}` }],
170
+ packages: [{ dir: app, name: packageOfApp, path: `${folder}/${app}` }],
157
171
  presets: [
158
172
  recordedPresetOf({
159
173
  spec: presetSpecOf({ value: presetValue, root, cwd: dirname(root) }),
@@ -210,6 +224,12 @@ const runCreate = async (opts: {
210
224
  return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
211
225
  }
212
226
 
227
+ const flaggedScope = readScope({ args: opts.args });
228
+
229
+ if (!flaggedScope.ok) {
230
+ return fail({ message: flaggedScope.error });
231
+ }
232
+
213
233
  const spec = parsePresetSpec({ value: presetValue, cwd: opts.cwd });
214
234
  const interactive = process.stdin.isTTY === true;
215
235
  const first = await resolveNames({
@@ -311,6 +331,13 @@ const runCreate = async (opts: {
311
331
  return fail({ message: clash });
312
332
  }
313
333
 
334
+ // Optional, asked only where menus are drawn; a plain terminal and a script give --scope.
335
+ const scope = flaggedScope.scope ?? (menusAvailable() ? await askScope() : undefined);
336
+
337
+ if (scope === null) {
338
+ return fail({ message: ABORTED });
339
+ }
340
+
314
341
  const warning = filePresetWarning({
315
342
  spec,
316
343
  packageName: located.packageName,
@@ -327,6 +354,7 @@ const runCreate = async (opts: {
327
354
  ['project', project],
328
355
  ['preset', `${located.packageName} ${located.packageVersion}`],
329
356
  [`${side} app`, `${folder}/${app}`],
357
+ ...(scope === undefined ? [] : [['package', `${scope}/${app}`] as [string, string]]),
330
358
  ['shared', shared === '' ? '(none)' : shared],
331
359
  ],
332
360
  }),
@@ -336,7 +364,7 @@ const runCreate = async (opts: {
336
364
  return fail({ message: ABORTED });
337
365
  }
338
366
 
339
- writeMonorepo({ root, project, spec, presetValue, located, folder, app, shared });
367
+ writeMonorepo({ root, project, spec, presetValue, located, folder, app, scope, shared });
340
368
 
341
369
  for (const step of [
342
370
  () => runBun({ cwd: root, args: ['install'], label: 'bun install' }),
@@ -25,12 +25,46 @@ export const SIDE_FIELDS: Record<TAppSide, INameField> = {
25
25
  },
26
26
  };
27
27
 
28
+ /** `@acme`: what `--scope` takes, for a library and for an app. */
29
+ export const SCOPE_PATTERN = /^@[a-z0-9][a-z0-9-]*$/;
30
+
31
+ /**
32
+ * The optional scope question of a menu: a package scope typed, or nothing for a bare name. Asked only
33
+ * where menus are drawn; a plain terminal and a script give `--scope`. `null` is a cancel.
34
+ */
35
+ export const askScope = async (): Promise<string | undefined | null> => {
36
+ const answer = await promptText({
37
+ message: 'Package scope (optional, like @acme; empty for none)',
38
+ validate: value =>
39
+ value.trim() === '' || SCOPE_PATTERN.test(value.trim())
40
+ ? undefined
41
+ : `'${value.trim()}' is not a scope like @acme`,
42
+ });
43
+
44
+ return answer === null ? null : answer.trim() === '' ? undefined : answer.trim();
45
+ };
46
+
28
47
  export const readFlag = (opts: { args: string[]; flag: string }): string | undefined => {
29
48
  const index = opts.args.indexOf(opts.flag);
30
49
 
31
50
  return index === -1 ? undefined : opts.args[index + 1];
32
51
  };
33
52
 
53
+ /** The scope the flag names, validated: none when absent, an error that names the flag when it is not `@scope`. */
54
+ export const readScope = (opts: {
55
+ args: string[];
56
+ }): { ok: true; scope: string | undefined } | { ok: false; error: string } => {
57
+ const given = readFlag({ args: opts.args, flag: CreateFlags.SCOPE });
58
+
59
+ if (given === undefined) {
60
+ return { ok: true, scope: undefined };
61
+ }
62
+
63
+ return SCOPE_PATTERN.test(given)
64
+ ? { ok: true, scope: given }
65
+ : { ok: false, error: `${CreateFlags.SCOPE} '${given}' is not a scope like @acme` };
66
+ };
67
+
34
68
  const isValidName = (opts: { name: string }): boolean =>
35
69
  CreateConstants.NAME_PATTERN.test(opts.name);
36
70
 
@@ -146,12 +146,30 @@ export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPreset
146
146
  const packageName = String(manifest.name);
147
147
  const packageVersion = String(manifest.version);
148
148
  const shown = `${packageName}@${packageVersion}`;
149
- const field = readProperty({ value: manifest[CreateConstants.PRESET_FIELD], key: 'preset' });
149
+ const vulcan = manifest[CreateConstants.PRESET_FIELD];
150
+ const oldKeys = ['preset', 'lib'].filter(
151
+ key => readProperty({ value: vulcan, key }) !== undefined,
152
+ );
153
+
154
+ // No fallback to the keys before `presets`: say what the contract is now.
155
+ if (oldKeys.length > 0) {
156
+ return {
157
+ ok: false,
158
+ error: `${shown} uses the old keys "vulcan": { ${oldKeys.map(key => `"${key}"`).join(', ')} }; the contract is now "vulcan": { "presets": { "app": "./path/preset.json", "lib": "./path/lib.json" } }`,
159
+ };
160
+ }
161
+
162
+ const presets = readProperty({ value: vulcan, key: 'presets' });
163
+ const field = readProperty({ value: presets, key: 'app' });
164
+ const libField = readProperty({ value: presets, key: 'lib' });
150
165
 
151
166
  if (typeof field !== 'string') {
152
167
  return {
153
168
  ok: false,
154
- error: `${shown} ships no VULCAN preset (no "vulcan": { "preset" } in its package.json)`,
169
+ error:
170
+ typeof libField === 'string'
171
+ ? `${shown}: vulcan.presets.lib needs vulcan.presets.app: a lib-only package is not supported`
172
+ : `${shown} ships no VULCAN preset (no "vulcan": { "presets": { "app" } } in its package.json)`,
155
173
  };
156
174
  }
157
175
 
@@ -160,7 +178,7 @@ export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPreset
160
178
  if (presetFile === undefined) {
161
179
  return {
162
180
  ok: false,
163
- error: `${shown}: vulcan.preset ${field} points outside the package`,
181
+ error: `${shown}: vulcan.presets.app ${field} points outside the package`,
164
182
  };
165
183
  }
166
184
 
@@ -201,14 +219,16 @@ export const locatePreset = (opts: { spec: IPresetSpec; root: string }): TPreset
201
219
  }
202
220
 
203
221
  const preset = { ...parsed.data, files: filesFolder };
204
- const libField = readProperty({ value: manifest[CreateConstants.PRESET_FIELD], key: 'lib' });
205
222
  const libFile =
206
223
  typeof libField === 'string'
207
224
  ? resolveInside({ root: packageRoot, from: packageRoot, path: libField })
208
225
  : undefined;
209
226
 
210
227
  if (typeof libField === 'string' && libFile === undefined) {
211
- return { ok: false, error: `${shown}: vulcan.lib ${libField} points outside the package` };
228
+ return {
229
+ ok: false,
230
+ error: `${shown}: vulcan.presets.lib ${libField} points outside the package`,
231
+ };
212
232
  }
213
233
 
214
234
  const located: ILocatedPreset = {
@@ -153,12 +153,14 @@ const toCatalog = (opts: { dependencies: Record<string, string> }): Record<strin
153
153
 
154
154
  export const renderAppManifest = (opts: {
155
155
  app: string;
156
+ /** The package name when it is not the app name: `@scope/<app>`. */
157
+ name?: string;
156
158
  preset: IPreset;
157
159
  presetPackage: { name: string; version: string };
158
160
  }): string =>
159
161
  json({
160
162
  value: {
161
- name: opts.app,
163
+ name: opts.name ?? opts.app,
162
164
  version: '0.0.0',
163
165
  private: true,
164
166
  // The preset's own text: no token is replaced here, a path pattern has no use for one.
@@ -37,6 +37,7 @@ import {
37
37
  planSync,
38
38
  SyncStatuses,
39
39
  } from '../sync/index.ts';
40
+ import { skillCatalogOf, triggerOf } from '@venizia/vulcan-atlas';
40
41
  import { AppScripts, DoctorChecks, DoctorConstants } from './common/index.ts';
41
42
  import type { IViolation, TDoctorCheck } from './common/index.ts';
42
43
  import { parseMakeIncludes, parseMakeTargets } from './makefile.ts';
@@ -806,3 +807,15 @@ export const checkAtlasBlock = (opts: ICheckContext): IViolation[] => {
806
807
  }),
807
808
  ];
808
809
  };
810
+
811
+ /** A skill with no "Use when" part gives the atlas server's instructions nothing to say when to load it: a warning, never a failure. */
812
+ export const checkSkillTriggers = (opts: ICheckContext): IViolation[] =>
813
+ skillCatalogOf({ root: opts.root })
814
+ .filter(entry => !triggerOf({ description: entry.description }).hasUseWhen)
815
+ .map(entry =>
816
+ createViolation({
817
+ check: DoctorChecks.SKILLS,
818
+ file: entry.source === 'project' ? `.agents/skills/${entry.name}/SKILL.md` : entry.name,
819
+ message: `'${entry.name}' has no "Use when" part in its description - atlas cannot say when to load it`,
820
+ }),
821
+ );
@@ -5,6 +5,7 @@ import {
5
5
  checkAgents,
6
6
  checkAppScripts,
7
7
  checkAtlasBlock,
8
+ checkSkillTriggers,
8
9
  checkDockerignore,
9
10
  checkMcpAtlas,
10
11
  checkApps,
@@ -94,5 +95,5 @@ export const runDoctorWarnings = async (opts: { root: string }): Promise<IViolat
94
95
  configFile: relative(opts.root, loaded.file),
95
96
  };
96
97
 
97
- return [...checkMcpAtlas(context), ...checkDockerignore(context)];
98
+ return [...checkMcpAtlas(context), ...checkDockerignore(context), ...checkSkillTriggers(context)];
98
99
  };
@@ -3,6 +3,7 @@ import { dirname, join, relative, resolve } from 'node:path';
3
3
  import type { ICheckContext } from './checks.ts';
4
4
  import { DoctorChecks } from './common/index.ts';
5
5
  import type { IViolation } from './common/index.ts';
6
+ import { frontmatterOf } from '../skills/index.ts';
6
7
 
7
8
  /**
8
9
  * Anthropic's skill-authoring rules (platform.claude.com, Agent Skills best practices), as checks:
@@ -33,48 +34,6 @@ const filesOf = (opts: { directory: string }): string[] =>
33
34
  const lineCountOf = (opts: { text: string }): number =>
34
35
  opts.text.replace(/\n$/, '').split('\n').length;
35
36
 
36
- const parseYaml = (opts: { text: string }): { value?: unknown; error?: string } => {
37
- try {
38
- return { value: Bun.YAML.parse(opts.text) };
39
- } catch (error) {
40
- return { error: error instanceof Error ? error.message : String(error) };
41
- }
42
- };
43
-
44
- /**
45
- * The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line
46
- * is the first one at which the block stops parsing - counted in the file, the opening `---` is 1.
47
- */
48
- const frontmatterOf = (opts: {
49
- text: string;
50
- }): { data: Record<string, unknown>; error?: string } => {
51
- const block = FRONTMATTER.exec(opts.text)?.[1];
52
-
53
- if (block === undefined) {
54
- return { data: {} };
55
- }
56
-
57
- const parsed = parseYaml({ text: block });
58
-
59
- if (parsed.error !== undefined) {
60
- const blockLines = block.split('\n');
61
- const failsAt = blockLines.findIndex(
62
- (_line, index) =>
63
- parseYaml({ text: blockLines.slice(0, index + 1).join('\n') }).error !== undefined,
64
- );
65
- const where = failsAt === -1 ? '' : ` at line ${failsAt + 2}`;
66
-
67
- return { data: {}, error: `the frontmatter is not valid YAML${where} (${parsed.error})` };
68
- }
69
-
70
- return {
71
- data:
72
- typeof parsed.value === 'object' && parsed.value !== null
73
- ? Object.fromEntries(Object.entries(parsed.value))
74
- : {},
75
- };
76
- };
77
-
78
37
  /** Every rule one skill directory breaks, each a message naming the file. */
79
38
  export const lintSkill = (opts: { directory: string }): string[] => {
80
39
  const skillFile = join(opts.directory, 'SKILL.md');
@@ -4,6 +4,7 @@ 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
+ import { renderBunfig } from '../create/bunfig.ts';
7
8
  import { renderDockerignore } from '../create/dockerignore.ts';
8
9
  import type { IInitEntry, IScaffoldFile } from './common/index.ts';
9
10
 
@@ -164,6 +165,7 @@ export const scaffoldProject = (opts: {
164
165
  }
165
166
 
166
167
  entries.push(writeIfAbsent({ root, path: '.dockerignore', content: renderDockerignore() }));
168
+ entries.push(writeIfAbsent({ root, path: 'bunfig.toml', content: renderBunfig() }));
167
169
 
168
170
  const makefile = join(root, 'Makefile');
169
171
 
package/src/router.ts CHANGED
@@ -27,6 +27,7 @@ const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
27
27
  CreateFlags.SHARED_DIR,
28
28
  CreateFlags.APP,
29
29
  CreateFlags.API,
30
+ CreateFlags.SCOPE,
30
31
  ],
31
32
  positionals: 0,
32
33
  },
@@ -0,0 +1,43 @@
1
+ const FRONTMATTER = /^---\n([\s\S]*?)\n---\n/;
2
+
3
+ const parseYaml = (opts: { text: string }): { value?: unknown; error?: string } => {
4
+ try {
5
+ return { value: Bun.YAML.parse(opts.text) };
6
+ } catch (error) {
7
+ return { error: error instanceof Error ? error.message : String(error) };
8
+ }
9
+ };
10
+
11
+ /**
12
+ * The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line
13
+ * is the first one at which the block stops parsing - counted in the file, the opening `---` is 1.
14
+ */
15
+ export const frontmatterOf = (opts: {
16
+ text: string;
17
+ }): { data: Record<string, unknown>; error?: string } => {
18
+ const block = FRONTMATTER.exec(opts.text)?.[1];
19
+
20
+ if (block === undefined) {
21
+ return { data: {} };
22
+ }
23
+
24
+ const parsed = parseYaml({ text: block });
25
+
26
+ if (parsed.error !== undefined) {
27
+ const blockLines = block.split('\n');
28
+ const failsAt = blockLines.findIndex(
29
+ (_line, index) =>
30
+ parseYaml({ text: blockLines.slice(0, index + 1).join('\n') }).error !== undefined,
31
+ );
32
+ const where = failsAt === -1 ? '' : ` at line ${failsAt + 2}`;
33
+
34
+ return { data: {}, error: `the frontmatter is not valid YAML${where} (${parsed.error})` };
35
+ }
36
+
37
+ return {
38
+ data:
39
+ typeof parsed.value === 'object' && parsed.value !== null
40
+ ? Object.fromEntries(Object.entries(parsed.value))
41
+ : {},
42
+ };
43
+ };
@@ -0,0 +1 @@
1
+ export * from './frontmatter.ts';
@@ -0,0 +1,39 @@
1
+ const LINE_FEED = 0x0a;
2
+ const SHOW_CURSOR = '\u001b[?25h';
3
+ const REFUSAL = [
4
+ 'vulcan: this menu reads key presses, not lines, and got a line of piped input (LF).',
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
+ ].join('\n');
7
+
8
+ /**
9
+ * A keyboard in raw mode sends CR for Enter, never LF. LF means the answers were piped in (a script
10
+ * 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.
12
+ */
13
+ export const guardAgainstPipedLines = async <TResult>(
14
+ run: () => Promise<TResult>,
15
+ ): Promise<TResult> => {
16
+ const refuse = (chunk: Buffer | string): void => {
17
+ const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
18
+
19
+ if (!bytes.includes(LINE_FEED)) {
20
+ return;
21
+ }
22
+
23
+ if (process.stdin.isTTY === true) {
24
+ process.stdin.setRawMode(false);
25
+ }
26
+
27
+ process.stdout.write(SHOW_CURSOR);
28
+ process.stderr.write(`\n${REFUSAL}\n`);
29
+ process.exit(1);
30
+ };
31
+
32
+ process.stdin.on('data', refuse);
33
+
34
+ try {
35
+ return await run();
36
+ } finally {
37
+ process.stdin.off('data', refuse);
38
+ }
39
+ };
package/src/ui/prompt.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { confirm, isCancel, multiselect, note, select, text } from '@clack/prompts';
2
+ import { guardAgainstPipedLines } from './keyboard.ts';
2
3
 
3
4
  /** One line of a menu: what it is called, and a short note beside it. */
4
5
  export interface IChoice {
@@ -18,13 +19,15 @@ export const promptText = async (opts: {
18
19
  defaultValue?: string;
19
20
  validate?: (value: string) => string | undefined;
20
21
  }): Promise<string | null> => {
21
- const value = await text({
22
- message: opts.message,
23
- ...(opts.defaultValue === undefined
24
- ? {}
25
- : { placeholder: opts.defaultValue, defaultValue: opts.defaultValue }),
26
- validate: input => opts.validate?.(input ?? ''),
27
- });
22
+ const value = await guardAgainstPipedLines(() =>
23
+ text({
24
+ message: opts.message,
25
+ ...(opts.defaultValue === undefined
26
+ ? {}
27
+ : { placeholder: opts.defaultValue, defaultValue: opts.defaultValue }),
28
+ validate: input => opts.validate?.(input ?? ''),
29
+ }),
30
+ );
28
31
 
29
32
  return isCancel(value) ? null : value;
30
33
  };
@@ -35,15 +38,17 @@ export const promptSelect = async (opts: {
35
38
  choices: IChoice[];
36
39
  initial?: string;
37
40
  }): Promise<string | null> => {
38
- const value = await select({
39
- message: opts.message,
40
- options: opts.choices.map(choice => ({
41
- value: choice.value,
42
- label: choice.label,
43
- ...(choice.hint === undefined ? {} : { hint: choice.hint }),
44
- })),
45
- initialValue: opts.initial,
46
- });
41
+ const value = await guardAgainstPipedLines(() =>
42
+ select({
43
+ message: opts.message,
44
+ options: opts.choices.map(choice => ({
45
+ value: choice.value,
46
+ label: choice.label,
47
+ ...(choice.hint === undefined ? {} : { hint: choice.hint }),
48
+ })),
49
+ initialValue: opts.initial,
50
+ }),
51
+ );
47
52
 
48
53
  return isCancel(value) ? null : value;
49
54
  };
@@ -54,16 +59,18 @@ export const promptMultiselect = async (opts: {
54
59
  choices: IChoice[];
55
60
  initial: string[];
56
61
  }): Promise<string[] | null> => {
57
- const value = await multiselect({
58
- message: opts.message,
59
- options: opts.choices.map(choice => ({
60
- value: choice.value,
61
- label: choice.label,
62
- ...(choice.hint === undefined ? {} : { hint: choice.hint }),
63
- })),
64
- initialValues: opts.initial,
65
- required: false,
66
- });
62
+ const value = await guardAgainstPipedLines(() =>
63
+ multiselect({
64
+ message: opts.message,
65
+ options: opts.choices.map(choice => ({
66
+ value: choice.value,
67
+ label: choice.label,
68
+ ...(choice.hint === undefined ? {} : { hint: choice.hint }),
69
+ })),
70
+ initialValues: opts.initial,
71
+ required: false,
72
+ }),
73
+ );
67
74
 
68
75
  return isCancel(value) ? null : value;
69
76
  };
@@ -72,7 +79,9 @@ export const promptConfirm = async (opts: {
72
79
  message: string;
73
80
  initial?: boolean;
74
81
  }): Promise<boolean | null> => {
75
- const value = await confirm({ message: opts.message, initialValue: opts.initial ?? true });
82
+ const value = await guardAgainstPipedLines(() =>
83
+ confirm({ message: opts.message, initialValue: opts.initial ?? true }),
84
+ );
76
85
 
77
86
  return isCancel(value) ? null : value;
78
87
  };