@venizia/vulcan 0.3.9 → 0.3.10

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.10",
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.10",
50
+ "@venizia/vulcan-okf": "0.3.10",
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
  },
@@ -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,6 +13,7 @@ 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';
@@ -108,6 +109,7 @@ const writeMonorepo = (opts: {
108
109
  });
109
110
  writeFile({ root, path: 'README.md', content: `# ${project}\n` });
110
111
  writeFile({ root, path: '.dockerignore', content: renderDockerignore() });
112
+ writeFile({ root, path: 'bunfig.toml', content: renderBunfig() });
111
113
 
112
114
  if (shared !== '') {
113
115
  writeFile({ root, path: `${shared}/.gitkeep`, content: '' });
@@ -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 = {
@@ -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
 
@@ -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
  };