@venizia/vulcan 0.4.9-0 → 0.4.9-2

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.
Files changed (141) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -82,78 +82,74 @@ export type TLibPreset = Omit<z.infer<typeof LIB_SCHEMA>, 'files'> & {
82
82
 
83
83
  type TLibPresetResult = { ok: true; lib: TLibPreset } | { ok: false; error: string };
84
84
 
85
- /**
86
- * The lib preset of a located preset package, validated; with `kind: 'shared'` it reads the shared kind,
87
- * which has the same schema. The app side is never touched by an error here.
88
- */
89
- export const readLibPreset = (opts: {
90
- located: ILocatedPreset;
91
- kind?: TLibraryKind;
92
- }): TLibPresetResult => {
93
- const { located } = opts;
94
- const kind = opts.kind ?? LibraryKinds.LIB;
95
- const shown = `${located.packageName}@${located.packageVersion}`;
96
- const file = kind === LibraryKinds.SHARED ? located.sharedFile : located.libFile;
97
-
98
- if (file === undefined) {
99
- return { ok: false, error: `preset ${located.packageName} has no ${kind} kind` };
100
- }
85
+ export class LibPreset {
86
+ /**
87
+ * The lib preset of a located preset package, validated; with `kind: 'shared'` it reads the shared kind,
88
+ * which has the same schema. The app side is never touched by an error here.
89
+ */
90
+ static read(opts: { located: ILocatedPreset; kind?: TLibraryKind }): TLibPresetResult {
91
+ const { located } = opts;
92
+ const kind = opts.kind ?? LibraryKinds.LIB;
93
+ const shown = `${located.packageName}@${located.packageVersion}`;
94
+ const file = kind === LibraryKinds.SHARED ? located.sharedFile : located.libFile;
95
+
96
+ if (file === undefined) {
97
+ return { ok: false, error: `preset ${located.packageName} has no ${kind} kind` };
98
+ }
101
99
 
102
- let raw: unknown;
100
+ let raw: unknown;
103
101
 
104
- try {
105
- raw = JSON.parse(readFileSync(file, 'utf8'));
106
- } catch {
107
- return { ok: false, error: `${shown}: ${file} is missing or not JSON` };
108
- }
102
+ try {
103
+ raw = JSON.parse(readFileSync(file, 'utf8'));
104
+ } catch {
105
+ return { ok: false, error: `${shown}: ${file} is missing or not JSON` };
106
+ }
109
107
 
110
- if (
111
- typeof raw !== 'object' ||
112
- raw === null ||
113
- !('presetVersion' in raw) ||
114
- raw.presetVersion !== CreateConstants.PRESET_VERSION
115
- ) {
116
- return {
117
- ok: false,
118
- error: `${shown}: the ${kind} preset has preset version ${String(typeof raw === 'object' && raw !== null && 'presetVersion' in raw ? raw.presetVersion : undefined)}; this VULCAN reads version ${CreateConstants.PRESET_VERSION} - upgrade @venizia/vulcan`,
119
- };
120
- }
108
+ if (
109
+ typeof raw !== 'object' ||
110
+ raw === null ||
111
+ !('presetVersion' in raw) ||
112
+ raw.presetVersion !== CreateConstants.PRESET_VERSION
113
+ ) {
114
+ return {
115
+ ok: false,
116
+ error: `${shown}: the ${kind} preset has preset version ${String(typeof raw === 'object' && raw !== null && 'presetVersion' in raw ? raw.presetVersion : undefined)}; this VULCAN reads version ${CreateConstants.PRESET_VERSION} - upgrade @venizia/vulcan`,
117
+ };
118
+ }
121
119
 
122
- const parsed = LIB_SCHEMA.safeParse(raw);
120
+ const parsed = LIB_SCHEMA.safeParse(raw);
123
121
 
124
- if (!parsed.success) {
125
- const issues = parsed.error.issues
126
- .map((issue) => `${issue.path.join('.')} ${issue.message}`)
127
- .join('; ');
122
+ if (!parsed.success) {
123
+ const issues = parsed.error.issues
124
+ .map((issue) => `${issue.path.join('.')} ${issue.message}`)
125
+ .join('; ');
128
126
 
129
- return { ok: false, error: `${shown}: ${kind} preset: ${issues}` };
127
+ return { ok: false, error: `${shown}: ${kind} preset: ${issues}` };
128
+ }
129
+
130
+ const files = resolve(dirname(file), parsed.data.files);
131
+
132
+ if (PresetPath.escapes({ root: located.packageRoot, path: files }) || !existsSync(files)) {
133
+ return {
134
+ ok: false,
135
+ error: `${shown}: ${kind} preset: files ${parsed.data.files} is missing or points outside the package`,
136
+ };
137
+ }
138
+
139
+ return { ok: true, lib: { ...parsed.data, files } };
130
140
  }
131
141
 
132
- const files = resolve(dirname(file), parsed.data.files);
142
+ /** What the preset records of itself: its side and summary, and the lib summary when it makes libraries. */
143
+ static recordedOf(opts: { spec: string; located: ILocatedPreset }): IRecordedPreset {
144
+ const lib = LibPreset.read({ located: opts.located });
145
+ const shared = LibPreset.read({ located: opts.located, kind: LibraryKinds.SHARED });
133
146
 
134
- if (PresetPath.escapes({ root: located.packageRoot, path: files }) || !existsSync(files)) {
135
147
  return {
136
- ok: false,
137
- error: `${shown}: ${kind} preset: files ${parsed.data.files} is missing or points outside the package`,
148
+ spec: opts.spec,
149
+ side: opts.located.preset.side,
150
+ summary: opts.located.preset.summary,
151
+ ...(lib.ok ? { lib: lib.lib.summary } : {}),
152
+ ...(shared.ok ? { shared: shared.lib.summary } : {}),
138
153
  };
139
154
  }
140
-
141
- return { ok: true, lib: { ...parsed.data, files } };
142
- };
143
-
144
- /** What the preset records of itself: its side and summary, and the lib summary when it makes libraries. */
145
- export const recordedPresetOf = (opts: {
146
- spec: string;
147
- located: ILocatedPreset;
148
- }): IRecordedPreset => {
149
- const lib = readLibPreset({ located: opts.located });
150
- const shared = readLibPreset({ located: opts.located, kind: LibraryKinds.SHARED });
151
-
152
- return {
153
- spec: opts.spec,
154
- side: opts.located.preset.side,
155
- summary: opts.located.preset.summary,
156
- ...(lib.ok ? { lib: lib.lib.summary } : {}),
157
- ...(shared.ok ? { shared: shared.lib.summary } : {}),
158
- };
159
- };
155
+ }
@@ -1,5 +1,11 @@
1
- import { formatWithBun } from '../common/index.ts';
1
+ import { BunFormatter } from '../common/index.ts';
2
2
 
3
- /** A package.json as `bun fmt` wants it: Bun's own key order (name, version, ... scripts, dependencies A to Z). */
4
- export const renderManifestJson = (opts: { value: unknown }): string =>
5
- formatWithBun({ text: `${JSON.stringify(opts.value, null, 2)}\n`, file: 'package.json' });
3
+ export class ManifestJson {
4
+ /** A package.json as `bun fmt` wants it: Bun's own key order (name, version, ... scripts, dependencies A to Z). */
5
+ static render(opts: { value: unknown }): string {
6
+ return BunFormatter.format({
7
+ text: `${JSON.stringify(opts.value, null, 2)}\n`,
8
+ file: 'package.json',
9
+ });
10
+ }
11
+ }
@@ -1,7 +1,7 @@
1
1
  import { readSync } from 'node:fs';
2
2
 
3
- import { layoutFolderProblem, listedFoldersNote } from '../common/layout-folder.ts';
4
- import { menusAvailable, promptSelect, promptText } from '../ui/index.ts';
3
+ import { LayoutFolder } from '../common/layout-folder.ts';
4
+ import { TerminalCapability, TerminalPrompt } from '../ui/index.ts';
5
5
  import { AppSides, CreateConstants, CreateFlags } from './common/index.ts';
6
6
  import type {
7
7
  IAskOptions,
@@ -31,60 +31,13 @@ export const SIDE_FIELDS: Record<TAppSide, INameField> = {
31
31
  /** `@acme`: what `--scope` takes, for a library and for an app. */
32
32
  export const SCOPE_PATTERN = /^@[a-z0-9][a-z0-9-]*$/;
33
33
 
34
- /**
35
- * The optional scope question of a menu: a package scope typed, or nothing for a bare name. Asked only
36
- * where menus are drawn; a plain terminal and a script give `--scope`. `null` is a cancel.
37
- */
38
- export const askScope = async (): Promise<string | undefined | null> => {
39
- const answer = await promptText({
40
- message: 'Package scope (optional, like @acme; empty for none)',
41
- validate: (value) =>
42
- value.trim() === '' || SCOPE_PATTERN.test(value.trim())
43
- ? undefined
44
- : `'${value.trim()}' is not a scope like @acme`,
45
- });
46
-
47
- return answer === null ? null : answer.trim() === '' ? undefined : answer.trim();
48
- };
49
-
50
- export const readFlag = (opts: { args: string[]; flag: string }): string | undefined => {
51
- const index = opts.args.indexOf(opts.flag);
52
-
53
- return index === -1 ? undefined : opts.args[index + 1];
54
- };
55
-
56
- /** The scope the flag names, validated: none when absent, an error that names the flag when it is not `@scope`. */
57
- export const readScope = (opts: {
58
- args: string[];
59
- }): { ok: true; scope: string | undefined } | { ok: false; error: string } => {
60
- const given = readFlag({ args: opts.args, flag: CreateFlags.SCOPE });
61
-
62
- if (given === undefined) {
63
- return { ok: true, scope: undefined };
64
- }
65
-
66
- return SCOPE_PATTERN.test(given)
67
- ? { ok: true, scope: given }
68
- : { ok: false, error: `${CreateFlags.SCOPE} '${given}' is not a scope like @acme` };
69
- };
70
-
71
34
  const isValidName = (opts: { name: string }): boolean =>
72
35
  CreateConstants.NAME_PATTERN.test(opts.name);
73
36
 
74
- /** The message a menu shows under a typed name that is not one; nothing when it is fine. */
75
- export const nameProblem = (opts: { name: string }): string | undefined =>
76
- isValidName({ name: opts.name })
77
- ? undefined
78
- : `'${opts.name}' is not a name: lowercase letters, digits and '-', starting with a letter or digit`;
79
-
80
- /** Why a value is not valid for a field: a folder path for a path field, a name for the rest. Undefined when it is valid. */
81
- const fieldProblem = (opts: { field: INameField; value: string }): string | undefined =>
82
- opts.field.isPath === true
83
- ? layoutFolderProblem({ folder: opts.value })
84
- : nameProblem({ name: opts.value });
85
-
86
37
  const NEWLINE = 0x0a;
38
+
87
39
  const CARRIAGE_RETURN = 0x0d;
40
+
88
41
  const RETRY_PAUSE_MILLISECONDS = 5;
89
42
 
90
43
  const readFromDescriptor: TByteReader = (opts) =>
@@ -98,219 +51,273 @@ const pauseBriefly = (): void => {
98
51
  const isWouldBlock = (opts: { error: unknown }): boolean =>
99
52
  opts.error instanceof Error && 'code' in opts.error && opts.error.code === 'EAGAIN';
100
53
 
101
- /**
102
- * One line from a file descriptor, read byte by byte so nothing past the newline is consumed.
103
- * Not Bun's prompt(): it returns null for an empty line, which is not end of input. An empty line
104
- * is '' here; null is only end of input (Ctrl-D, closed stdin) with nothing read. `read` and `pause`
105
- * are replaceable so a test can drive the non-blocking retry without a real pipe.
106
- */
107
- export const readLine = (opts: {
108
- descriptor: number;
109
- read?: TByteReader;
110
- pause?: () => void;
111
- }): string | null => {
112
- const { descriptor, read = readFromDescriptor, pause = pauseBriefly } = opts;
113
- const buffer = Buffer.alloc(1);
114
- const bytes: number[] = [];
115
-
116
- for (;;) {
117
- let count = 0;
118
-
119
- try {
120
- count = read({ descriptor, buffer });
121
- } catch (error) {
122
- // A non-blocking pipe with nothing buffered yet: wait for the writer instead of failing.
123
- if (isWouldBlock({ error })) {
124
- pause();
125
- continue;
126
- }
127
-
128
- throw error;
129
- }
54
+ export class ProjectNames {
55
+ /** Why a value is not valid for a field: a folder path for a path field, a name for the rest. Undefined when it is valid. */
56
+ private static fieldProblem(opts: { field: INameField; value: string }): string | undefined {
57
+ return opts.field.isPath === true
58
+ ? LayoutFolder.layoutFolderProblem({ folder: opts.value })
59
+ : ProjectNames.nameProblem({ name: opts.value });
60
+ }
130
61
 
131
- if (count === 0) {
132
- return bytes.length === 0 ? null : Buffer.from(bytes).toString('utf8');
133
- }
62
+ private static async askUntilValid(opts: {
63
+ field: INameField;
64
+ ask: TAsk;
65
+ }): Promise<string | null> {
66
+ const { field } = opts;
67
+ const validate = (value: string): string | undefined => {
68
+ const name = value.trim() === '' ? (field.previous ?? '') : value.trim();
134
69
 
135
- const value = buffer.readUInt8(0);
70
+ if (name === '' && field.optional === true) {
71
+ return undefined;
72
+ }
136
73
 
137
- if (value === NEWLINE) {
138
- break;
139
- }
74
+ return ProjectNames.fieldProblem({ field, value: name });
75
+ };
140
76
 
141
- bytes.push(value);
142
- }
77
+ for (;;) {
78
+ const answer = await opts.ask({
79
+ question: field.question,
80
+ previous: field.previous,
81
+ choices: field.choices,
82
+ validate,
83
+ });
143
84
 
144
- if (bytes.at(-1) === CARRIAGE_RETURN) {
145
- bytes.pop();
146
- }
85
+ if (answer === null) {
86
+ return null;
87
+ }
147
88
 
148
- return Buffer.from(bytes).toString('utf8');
149
- };
89
+ const name = answer.trim() === '' ? (opts.field.previous ?? '') : answer.trim();
150
90
 
151
- /** The shown default is the user's own earlier choice, never one VULCAN made up. */
152
- export const askWithPrompt = (opts: IAskOptions): string | null => {
153
- const choices =
154
- opts.choices !== undefined && opts.choices.length > 1 ? ` [${opts.choices.join(', ')}]` : '';
91
+ if (name === '' && opts.field.optional === true) {
92
+ return '';
93
+ }
155
94
 
156
- process.stdout.write(
157
- opts.previous === undefined
158
- ? `? ${opts.question}${choices} > `
159
- : `? ${opts.question}${choices} (${opts.previous}) > `,
160
- );
95
+ const problem = ProjectNames.fieldProblem({ field, value: name });
161
96
 
162
- return readLine({ descriptor: CreateConstants.STDIN_DESCRIPTOR });
163
- };
97
+ if (problem === undefined) {
98
+ return name;
99
+ }
164
100
 
165
- const NEW_FOLDER = ':new-folder';
101
+ process.stderr.write(` ${problem}\n`);
102
+ }
103
+ }
166
104
 
167
- /** A menu, not a line: existing folders are picked, a new name is typed with its default shown. */
168
- const askWithMenus: TAsk = async (opts) => {
169
- if (opts.choices !== undefined && opts.choices.length > 0) {
170
- const picked = await promptSelect({
171
- message: opts.question,
172
- choices: [
173
- ...opts.choices.map((value) => ({ value, label: value })),
174
- { value: NEW_FOLDER, label: 'New folder...' },
175
- ],
176
- initial: opts.previous,
105
+ /**
106
+ * The optional scope question of a menu: a package scope typed, or nothing for a bare name. Asked only
107
+ * where menus are drawn; a plain terminal and a script give `--scope`. `null` is a cancel.
108
+ */
109
+ static async askScope(): Promise<string | undefined | null> {
110
+ const answer = await TerminalPrompt.promptText({
111
+ message: 'Package scope (optional, like @acme; empty for none)',
112
+ validate: (value) =>
113
+ value.trim() === '' || SCOPE_PATTERN.test(value.trim())
114
+ ? undefined
115
+ : `'${value.trim()}' is not a scope like @acme`,
177
116
  });
178
117
 
179
- if (picked !== NEW_FOLDER) {
180
- return picked;
181
- }
118
+ return answer === null ? null : answer.trim() === '' ? undefined : answer.trim();
182
119
  }
183
120
 
184
- return promptText({
185
- message: opts.question,
186
- defaultValue: opts.previous,
187
- validate: opts.validate,
188
- });
189
- };
121
+ static readFlag(opts: { args: string[]; flag: string }): string | undefined {
122
+ const index = opts.args.indexOf(opts.flag);
190
123
 
191
- /** Menus in a terminal that can draw them, the plain question everywhere else. */
192
- export const askInTerminal: TAsk = (opts) =>
193
- menusAvailable() ? askWithMenus(opts) : askWithPrompt(opts);
124
+ return index === -1 ? undefined : opts.args[index + 1];
125
+ }
194
126
 
195
- const askUntilValid = async (opts: { field: INameField; ask: TAsk }): Promise<string | null> => {
196
- const { field } = opts;
197
- const validate = (value: string): string | undefined => {
198
- const name = value.trim() === '' ? (field.previous ?? '') : value.trim();
127
+ /** The scope the flag names, validated: none when absent, an error that names the flag when it is not `@scope`. */
128
+ static readScope(opts: {
129
+ args: string[];
130
+ }): { ok: true; scope: string | undefined } | { ok: false; error: string } {
131
+ const given = ProjectNames.readFlag({ args: opts.args, flag: CreateFlags.SCOPE });
199
132
 
200
- if (name === '' && field.optional === true) {
201
- return undefined;
133
+ if (given === undefined) {
134
+ return { ok: true, scope: undefined };
202
135
  }
203
136
 
204
- return fieldProblem({ field, value: name });
205
- };
137
+ return SCOPE_PATTERN.test(given)
138
+ ? { ok: true, scope: given }
139
+ : { ok: false, error: `${CreateFlags.SCOPE} '${given}' is not a scope like @acme` };
140
+ }
206
141
 
207
- for (;;) {
208
- const answer = await opts.ask({
209
- question: field.question,
210
- previous: field.previous,
211
- choices: field.choices,
212
- validate,
213
- });
142
+ /** The message a menu shows under a typed name that is not one; nothing when it is fine. */
143
+ static nameProblem(opts: { name: string }): string | undefined {
144
+ return isValidName({ name: opts.name })
145
+ ? undefined
146
+ : `'${opts.name}' is not a name: lowercase letters, digits and '-', starting with a letter or digit`;
147
+ }
214
148
 
215
- if (answer === null) {
216
- return null;
217
- }
149
+ /**
150
+ * One line from a file descriptor, read byte by byte so nothing past the newline is consumed.
151
+ * Not Bun's prompt(): it returns null for an empty line, which is not end of input. An empty line
152
+ * is '' here; null is only end of input (Ctrl-D, closed stdin) with nothing read. `read` and `pause`
153
+ * are replaceable so a test can drive the non-blocking retry without a real pipe.
154
+ */
155
+ static readLine(opts: {
156
+ descriptor: number;
157
+ read?: TByteReader;
158
+ pause?: () => void;
159
+ }): string | null {
160
+ const { descriptor, read = readFromDescriptor, pause = pauseBriefly } = opts;
161
+ const buffer = Buffer.alloc(1);
162
+ const bytes: number[] = [];
163
+
164
+ for (;;) {
165
+ let count = 0;
166
+
167
+ try {
168
+ count = read({ descriptor, buffer });
169
+ } catch (error) {
170
+ // A non-blocking pipe with nothing buffered yet: wait for the writer instead of failing.
171
+ if (isWouldBlock({ error })) {
172
+ pause();
173
+ continue;
174
+ }
175
+
176
+ throw error;
177
+ }
218
178
 
219
- const name = answer.trim() === '' ? (opts.field.previous ?? '') : answer.trim();
179
+ if (count === 0) {
180
+ return bytes.length === 0 ? null : Buffer.from(bytes).toString('utf8');
181
+ }
220
182
 
221
- if (name === '' && opts.field.optional === true) {
222
- return '';
223
- }
183
+ const value = buffer.readUInt8(0);
184
+
185
+ if (value === NEWLINE) {
186
+ break;
187
+ }
224
188
 
225
- const problem = fieldProblem({ field, value: name });
189
+ bytes.push(value);
190
+ }
226
191
 
227
- if (problem === undefined) {
228
- return name;
192
+ if (bytes.at(-1) === CARRIAGE_RETURN) {
193
+ bytes.pop();
229
194
  }
230
195
 
231
- process.stderr.write(` ${problem}\n`);
196
+ return Buffer.from(bytes).toString('utf8');
232
197
  }
233
- };
234
198
 
235
- /** Every name from its flag; a missing one is asked in a TTY and an error otherwise. */
236
- export const resolveNames = async (opts: {
237
- fields: INameField[];
238
- args: string[];
239
- interactive: boolean;
240
- ask: TAsk;
241
- }): Promise<TNamesResult> => {
242
- const names: Record<string, string> = {};
199
+ /** The shown default is the user's own earlier choice, never one VULCAN made up. */
200
+ static askWithPrompt(opts: IAskOptions): string | null {
201
+ const choices =
202
+ opts.choices !== undefined && opts.choices.length > 1 ? ` [${opts.choices.join(', ')}]` : '';
243
203
 
244
- for (const field of opts.fields) {
245
- const flagged = readFlag({ args: opts.args, flag: field.flag });
204
+ process.stdout.write(
205
+ opts.previous === undefined
206
+ ? `? ${opts.question}${choices} > `
207
+ : `? ${opts.question}${choices} (${opts.previous}) > `,
208
+ );
246
209
 
247
- if (flagged !== undefined) {
248
- const problem = fieldProblem({ field, value: flagged });
210
+ return ProjectNames.readLine({ descriptor: CreateConstants.STDIN_DESCRIPTOR });
211
+ }
249
212
 
250
- if (problem !== undefined) {
251
- return {
252
- ok: false,
253
- error:
254
- field.isPath === true
255
- ? `${field.flag} ${problem}`
256
- : `${field.flag} '${flagged}' is not a name: lowercase letters, digits and '-'`,
257
- };
213
+ /** Every name from its flag; a missing one is asked in a TTY and an error otherwise. */
214
+ static async resolve(opts: {
215
+ fields: INameField[];
216
+ args: string[];
217
+ interactive: boolean;
218
+ ask: TAsk;
219
+ }): Promise<TNamesResult> {
220
+ const names: Record<string, string> = {};
221
+
222
+ for (const field of opts.fields) {
223
+ const flagged = ProjectNames.readFlag({ args: opts.args, flag: field.flag });
224
+
225
+ if (flagged !== undefined) {
226
+ const problem = ProjectNames.fieldProblem({ field, value: flagged });
227
+
228
+ if (problem !== undefined) {
229
+ return {
230
+ ok: false,
231
+ error:
232
+ field.isPath === true
233
+ ? `${field.flag} ${problem}`
234
+ : `${field.flag} '${flagged}' is not a name: lowercase letters, digits and '-'`,
235
+ };
236
+ }
237
+
238
+ names[field.key] = flagged;
239
+ continue;
258
240
  }
259
241
 
260
- names[field.key] = flagged;
261
- continue;
262
- }
242
+ if (!opts.interactive) {
243
+ if (field.optional === true) {
244
+ names[field.key] = '';
245
+ continue;
246
+ }
263
247
 
264
- if (!opts.interactive) {
265
- if (field.optional === true) {
266
- names[field.key] = '';
267
- continue;
248
+ if (field.previous !== undefined) {
249
+ names[field.key] = field.previous;
250
+ continue;
251
+ }
252
+
253
+ const listed =
254
+ field.choices !== undefined && field.choices.length > 1
255
+ ? `; ${LayoutFolder.listedNote({ folders: field.choices })}`
256
+ : '';
257
+
258
+ return {
259
+ ok: false,
260
+ error: `missing ${field.flag} (${field.question}${listed}) - names are never chosen for you`,
261
+ };
268
262
  }
269
263
 
270
- if (field.previous !== undefined) {
264
+ if (field.fixed === true && field.previous !== undefined) {
271
265
  names[field.key] = field.previous;
272
266
  continue;
273
267
  }
274
268
 
275
- const listed =
276
- field.choices !== undefined && field.choices.length > 1
277
- ? `; ${listedFoldersNote({ folders: field.choices })}`
278
- : '';
269
+ const answer = await ProjectNames.askUntilValid({ field, ask: opts.ask });
279
270
 
280
- return {
281
- ok: false,
282
- error: `missing ${field.flag} (${field.question}${listed}) - names are never chosen for you`,
283
- };
284
- }
271
+ if (answer === null) {
272
+ return { ok: false, error: 'aborted' };
273
+ }
285
274
 
286
- if (field.fixed === true && field.previous !== undefined) {
287
- names[field.key] = field.previous;
288
- continue;
275
+ names[field.key] = answer;
289
276
  }
290
277
 
291
- const answer = await askUntilValid({ field, ask: opts.ask });
278
+ return { ok: true, names };
279
+ }
280
+
281
+ /** Two folders given the same name would mix kinds of code; the error names both flags. */
282
+ static findFolderClash(opts: { folders: { flag: string; value: string }[] }): string | undefined {
283
+ for (const [index, first] of opts.folders.entries()) {
284
+ const second = opts.folders.slice(index + 1).find((other) => other.value === first.value);
292
285
 
293
- if (answer === null) {
294
- return { ok: false, error: 'aborted' };
286
+ if (second !== undefined) {
287
+ return `${first.flag} and ${second.flag} both name '${first.value}' - each kind of code needs its own folder`;
288
+ }
295
289
  }
296
290
 
297
- names[field.key] = answer;
291
+ return undefined;
298
292
  }
293
+ }
299
294
 
300
- return { ok: true, names };
301
- };
295
+ const NEW_FOLDER = ':new-folder';
302
296
 
303
- /** Two folders given the same name would mix kinds of code; the error names both flags. */
304
- export const findFolderClash = (opts: {
305
- folders: { flag: string; value: string }[];
306
- }): string | undefined => {
307
- for (const [index, first] of opts.folders.entries()) {
308
- const second = opts.folders.slice(index + 1).find((other) => other.value === first.value);
297
+ /** A menu, not a line: existing folders are picked, a new name is typed with its default shown. */
298
+ const askWithMenus: TAsk = async (opts) => {
299
+ if (opts.choices !== undefined && opts.choices.length > 0) {
300
+ const picked = await TerminalPrompt.promptSelect({
301
+ message: opts.question,
302
+ choices: [
303
+ ...opts.choices.map((value) => ({ value, label: value })),
304
+ { value: NEW_FOLDER, label: 'New folder...' },
305
+ ],
306
+ initial: opts.previous,
307
+ });
309
308
 
310
- if (second !== undefined) {
311
- return `${first.flag} and ${second.flag} both name '${first.value}' - each kind of code needs its own folder`;
309
+ if (picked !== NEW_FOLDER) {
310
+ return picked;
312
311
  }
313
312
  }
314
313
 
315
- return undefined;
314
+ return TerminalPrompt.promptText({
315
+ message: opts.question,
316
+ defaultValue: opts.previous,
317
+ validate: opts.validate,
318
+ });
316
319
  };
320
+
321
+ /** Menus in a terminal that can draw them, the plain question everywhere else. */
322
+ export const askInTerminal: TAsk = (opts) =>
323
+ TerminalCapability.menusAvailable() ? askWithMenus(opts) : ProjectNames.askWithPrompt(opts);