@venizia/vulcan 0.3.7 → 0.3.9

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.
package/README.md CHANGED
@@ -16,7 +16,7 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
16
16
 
17
17
  | Command | What it does |
18
18
  |---|---|
19
- | `init [--config ts\|mts\|mjs\|js]` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.*`, the three lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, the atlas `.mcp.json`, a Makefile with the `-include` and a fallback rule for a missing `vulcan.mk`. Appends the agent entries to `.gitignore`, installs the lint tools (listing them first; a failed install exits 1), and ends with a numbered list of what is left. Needs a `package.json` in the directory. A project whose `package.json` declares `workspaces` gets no root lint configs. Never overwrites; prints what to add to existing files |
19
+ | `init [--config ts\|mts\|mjs\|js]` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.*`, the three lint configs, `.agents/rules.md`, `.agents/knowledge/index.md`, a Makefile with the `-include` and a fallback rule for a missing `vulcan.mk`. Appends the agent entries to `.gitignore`, installs the lint tools (listing them first; a failed install exits 1), and ends with a numbered list of what is left. Needs a `package.json` in the directory. A project whose `package.json` declares `workspaces` gets no root lint configs. Never overwrites; prints what to add to existing files |
20
20
  | `init --preset <name\|file:path> --project <name> --app <name> [--backend-dir\|--frontend-dir <name>] [--shared-dir <name>]` | Create a new monorepo with its first app from a framework preset: the root manifests, the app's files, the VULCAN layer and a knowledge bundle, then install, `git init` (a missing git is reported, not fatal), `sync` and the checks, and ends with `cd <project> && make dev` and the app's URL. A name missing from the flags is asked in a terminal; none has a default. Refuses a folder that is not empty |
21
21
  | `add --preset <name\|file:path> --app <name> [--backend-dir\|--frontend-dir <name>] [--api <app> \| --no-api]` | Add an app from a preset to a monorepo `init --preset` created: registers it in `workspaces`, the `catalog`, the config and the knowledge bundle, picks a free port, then installs, syncs and checks. A frontend says which backend app to proxy `/api` to |
22
22
  | `sync [--dry-run] [--prune]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`; the one `bun init` writes is replaced, any other hand-written file is left alone), `.claude/settings.json` (shipped + slot + project hooks + `claude.settings` over your personal keys; what it applied is recorded in `.claude/vulcan-managed.json`, so a removed choice is removed, and a hook it wrote is taken back by its command even after you edited its entry), `.claude/skills/` links, and the committed `.agents/vulcan.manifest.json`. Prints each base rule added, changed or removed since the manifest last recorded it, with its new text, then records the new hashes. `--prune` also removes what sync proves stale and did not write: an old VULCAN or plugin-era hook command (a shipped hook exactly as an older VULCAN released it, or a `.agents/` hook whose file is gone) and a dead `.claude/skills` link - never a developer's own hook, a customised shipped command, a real directory or a symlinked `.claude/skills`. `--dry-run` writes nothing and labels each line `would create`, `would replace` or `would remove`. Idempotent |
@@ -52,7 +52,7 @@ An unknown key is an error; every error names the file and the field.
52
52
 
53
53
  - `rules.md` - the base rules: write boundaries, security, process, build, and the IGNIS coding style V-C-01..V-C-18 (39 rules; it lists V-W-05, V-C-03 and V-C-05 as retired).
54
54
  - `slots.json` - rules a project picks a wording for (V-W-01 today).
55
- - `skills/` - `knowledge-sync`, `docs-writing`, `docs-update` (project-neutral; a project-specific skill stays in its project). Skill evals have not been run against a model: the skills pass the lint, and their output is a draft to review.
55
+ - `skills/` - `knowledge-sync`, `docs-writing`, `docs-update`, `build-a-feature` (project-neutral; a project-specific skill stays in its project). Skill evals have not been run against a model: the skills pass the lint, and their output is a draft to review.
56
56
  - `hooks/` - `session-start.ts` (prints the rules digest) `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call) `guard-manifest.ts` (refuses a write to the generated `.agents/vulcan.manifest.json`) `guard-package.ts` (denies a hand-written new `package.json` in a layout folder when a recorded preset has a `vulcan add` command for it, else only warns) and `guard-remote-hosts.ts` (only for a config with `remoteHosts`: asks before a command reaches a host that is not listed; whole-name or `*` match, never substring).
57
57
  - `claude/settings.json`, `make/vulcan.mk`, `templates/`.
58
58
 
@@ -0,0 +1,122 @@
1
+ ---
2
+ name: build-a-feature
3
+ description: Builds a feature - an endpoint, a service, a repository, a page, a new app or a shared package - from the user's goal to a reviewed, tested change, with every convention and API looked up in atlas. Use when the user asks to build, add or implement something, asks how a feature would be built here, or asks which skill or workflow you follow for a feature. Load it before you answer any of these, a question about the workflow included, because its first step is a lookup in atlas and an answer given without it is ungrounded.
4
+ user-invocable: true
5
+ allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
6
+ ---
7
+
8
+ # Build a feature
9
+
10
+ The project's framework, its conventions and its APIs live in atlas. Every fact you state about how
11
+ things are done here is **grounded**: it comes from an atlas call made in this session, quoted with
12
+ its source. A plan step that depends on a lookup is written after the lookup ran. The user decides
13
+ when to commit.
14
+
15
+ `$ARGUMENTS` names the feature. With no arguments, ask what to build.
16
+
17
+ **Ground first, every time** - for a named feature and for a question about this workflow alike.
18
+ Before your first answer, call `search` for how a feature is built in this project and `presets`.
19
+ Open the answer with one quoted hit and the preset list (each preset with the apps and libraries
20
+ it creates), then describe the steps below.
21
+
22
+ **Contents**: [Checklist](#checklist) · [1. Settle the goal](#1-settle-the-goal) · [2. Ground the conventions](#2-ground-the-conventions) · [3. Design the interface](#3-design-the-interface) · [4. Plan the slices](#4-plan-the-slices) · [5. Build slice by slice](#5-build-slice-by-slice) · [6. Check](#6-check) · [7. Update knowledge](#7-update-knowledge) · [8. Review and hand over](#8-review-and-hand-over)
23
+
24
+ ## Checklist
25
+
26
+ Copy it into your reply and tick each box when its criterion holds:
27
+
28
+ ```
29
+ - [ ] 1. Goal settled - every open decision answered by the user
30
+ - [ ] 2. Conventions grounded - each layer the feature touches has an atlas hit you quote
31
+ - [ ] 3. Interface approved - the user said yes to the interface and the seams to test
32
+ - [ ] 4. Slices planned - each slice names one behaviour, its seam, its files
33
+ - [ ] 5. Slices built - every slice went red, then green; every import came from `symbol`
34
+ - [ ] 6. Checks green - typecheck, lint, test, vulcan doctor passed; the real behaviour shown
35
+ - [ ] 7. Knowledge current - each changed fact is in the bundle and its log
36
+ - [ ] 8. Diff reviewed - the whole diff read once, findings fixed, summary given
37
+ ```
38
+
39
+ ## 1. Settle the goal
40
+
41
+ Ask in **rounds**. A round holds every question you can ask now without guessing an earlier
42
+ answer: who uses the feature, what it does, what is out of scope, which inputs fail. Number each
43
+ question and put your recommended answer under it. Wait for the answers, then ask the next round.
44
+
45
+ A question about how the project or its framework works is a fact: look it up in atlas (step 2)
46
+ instead of asking. The user answers decisions.
47
+
48
+ Done when no decision is left open.
49
+
50
+ ## 2. Ground the conventions
51
+
52
+ For each layer the feature touches, find how this project already does it:
53
+
54
+ | You need | Call |
55
+ |---|---|
56
+ | How a feature of this kind is organised (routes, controllers, services, repositories, datasources, pages) | `search` with the kind and the layer, then `get` on the best hits |
57
+ | The project's own concepts and decisions | `search` with `corpus: "knowledge"` |
58
+ | A new app or a shared package | `presets`, then the exact `vulcan add` command it returns |
59
+ | What changed in a release you depend on | `changes`, `version` |
60
+
61
+ A knowledge page under `.agents/knowledge/packages/` is a summary of what a package is; the way
62
+ code is written comes from atlas. When atlas has nothing on a point, tell the user and mark the
63
+ point **unverified**.
64
+
65
+ Done when each layer has a quoted atlas hit, or is marked unverified.
66
+
67
+ ## 3. Design the interface
68
+
69
+ Propose what callers see, before any code: routes with their request and response schemas, class
70
+ and method names, options, configuration and environment keys, files to add. Aim for a **deep**
71
+ interface: the fewest methods and parameters that cover the behaviour, with the complexity behind
72
+ them. Name the convention behind each choice and the atlas hit it came from.
73
+
74
+ Then name the **seams** to test: the public interfaces where a test observes the behaviour (an
75
+ HTTP route, a service method, a page's rendered output). Tests live at these seams only.
76
+
77
+ Done when the user approves the interface and the seams.
78
+
79
+ ## 4. Plan the slices
80
+
81
+ Split the work into **vertical slices**: each one a thin path through every layer it needs, for one
82
+ behaviour, testable at one agreed seam. List each slice with its behaviour, its seam and the files
83
+ it touches. Order them so the first slice is the simplest end-to-end path (a tracer bullet).
84
+
85
+ Done when the user approves the slices.
86
+
87
+ ## 5. Build slice by slice
88
+
89
+ For each slice, in order:
90
+
91
+ 1. Write one test at the slice's seam. Its expected values come from the spec or a worked example,
92
+ computed independently of the code under test. Run it: it goes **red**, for the reason you expect.
93
+ 2. Call `symbol` for each export of the framework or of a workspace package you are about to
94
+ import or call, and use the signature and import path it returns.
95
+ 3. Write the smallest code that turns the test **green**. Run it.
96
+
97
+ A database change is a migration file you write and hand to the user to apply.
98
+
99
+ Done when every slice went red, then green.
100
+
101
+ ## 6. Check
102
+
103
+ Run the app's `typecheck`, `lint` and `test`, then `bun x --no-install vulcan doctor`, and read each
104
+ output. Then show the real behaviour: start the app and call the endpoint, or open the page, and
105
+ paste what came back.
106
+
107
+ Done when every check passed in this session and the behaviour is shown.
108
+
109
+ ## 7. Update knowledge
110
+
111
+ Each fact about the project that changed - a new concept, a decision, a gotcha - goes into the
112
+ knowledge bundle and its log in the same change.
113
+
114
+ Done when the bundle and its log match the change.
115
+
116
+ ## 8. Review and hand over
117
+
118
+ Read the whole diff once, for bugs and for the project's rules. Refactor here, with the tests
119
+ green. Fix what you find, then summarise the change with the checks you ran and their results.
120
+ The user decides when to commit.
121
+
122
+ Done when the diff is clean and the summary names every check and its result.
@@ -0,0 +1,29 @@
1
+ {
2
+ "skill_name": "build-a-feature",
3
+ "evals": [
4
+ {
5
+ "id": 0,
6
+ "prompt": "If I want to implement a feature with you, what will you do with me? Which skill or workflow do you use?",
7
+ "expected_output": "Calls atlas search for how a feature is built in this project and atlas presets before its first answer; opens with one quoted hit and the preset list (the frontend preset included); then describes the workflow, naming the atlas call at each step it depends on; claims no lookup it has not made; nothing is written or committed",
8
+ "files": [".agents/vulcan.manifest.json"]
9
+ },
10
+ {
11
+ "id": 1,
12
+ "prompt": "Add a GET endpoint that returns the server time to the first backend app. Propose the surface first; do not write code yet.",
13
+ "expected_output": "Calls atlas search for how a controller and a route are written here and get on the hits; proposes the route, its response schema and the controller and method names, each convention backed by the atlas hit it came from; waits for approval; no source file changed",
14
+ "files": [".agents/vulcan.manifest.json"]
15
+ },
16
+ {
17
+ "id": 2,
18
+ "prompt": "We need a second backend app named billing and a shared library named money. Set them up.",
19
+ "expected_output": "Calls atlas presets, then runs the exact vulcan add commands it returned (an app with --app billing, a library with --lib money); never hand-writes a package.json, a tsconfig or scripts; runs the new packages' checks and vulcan doctor; nothing committed",
20
+ "files": [".agents/vulcan.manifest.json"]
21
+ },
22
+ {
23
+ "id": 3,
24
+ "prompt": "Add an endpoint that lists the products under a price. Walk me through it.",
25
+ "expected_output": "Asks its open decisions in one numbered round with a recommended answer each (filter shape, sorting, paging, empty result) and looks up the conventions in atlas instead of asking; proposes the route, schemas and class names with the seams to test; plans vertical slices starting with the simplest end-to-end path; writes no code before the user approves",
26
+ "files": [".agents/vulcan.manifest.json"]
27
+ }
28
+ ]
29
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.3.7",
3
+ "version": "0.3.9",
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": {
@@ -44,8 +44,9 @@
44
44
  "test": "NODE_ENV=test bun test --env-file=.env.test"
45
45
  },
46
46
  "dependencies": {
47
- "@venizia/vulcan-atlas": "0.3.7",
48
- "@venizia/vulcan-okf": "0.3.7",
47
+ "@clack/prompts": "1.8.1",
48
+ "@venizia/vulcan-atlas": "0.3.9",
49
+ "@venizia/vulcan-okf": "0.3.9",
49
50
  "zod": "^4.5.4"
50
51
  },
51
52
  "devDependencies": {
@@ -17,6 +17,7 @@ export const renderAtlasBlock = (opts: { project: string; sources: string[] }):
17
17
  'Look facts up there before you answer or write from memory (V-P-07):',
18
18
  '`symbol` before you use an export (signature, import path, source line); `search`, then `get`, for how something works or which convention applies; `version` or `changes` for a release or an upgrade.',
19
19
  'A new app or package: ask `presets` which preset and which `vulcan add` command, run it, and never hand-write package.json, tsconfig or scripts.',
20
+ 'How to build something here (a feature, a controller, a service, a repository): `search` first, then `get`, before you answer; a plan never says "check atlas" for a step you have not done.',
20
21
  ATLAS_BLOCK_END,
21
22
  '',
22
23
  ].join('\n');
@@ -24,6 +24,7 @@ export const excludePathsOf = (opts: {
24
24
  skillNames: string[];
25
25
  }): IExcludeGroup[] => {
26
26
  const listedSkills = new Set<string>();
27
+ let listedShared = false;
27
28
  const groups: IExcludeGroup[] = [];
28
29
 
29
30
  for (const entry of readAgentTable().filter(item => opts.agents.includes(item.id))) {
@@ -39,6 +40,10 @@ export const excludePathsOf = (opts: {
39
40
 
40
41
  if (entry.mcp.scope === AgentScopes.PROJECT) {
41
42
  paths.push(`/${entry.mcp.path}`);
43
+ } else if (!listedShared) {
44
+ // The root `.mcp.json` several agents read is listed once, under the first of them.
45
+ listedShared = true;
46
+ paths.push(`/${AgentConstants.SHARED_MCP_FILE}`);
42
47
  }
43
48
 
44
49
  if (entry.skills.dir !== CLAUDE_SKILLS_DIRECTORY && !listedSkills.has(entry.skills.dir)) {
@@ -1,22 +1,95 @@
1
1
  import { askWithPrompt } from '../create/names.ts';
2
- import type { IAgentQuestion } from './common/index.ts';
2
+ import { menusAvailable, promptMultiselect } from '../ui/index.ts';
3
+ import type { IAgentQuestion, TAgentResolution } from './common/index.ts';
3
4
  import { AgentConstants } from './common/index.ts';
4
- import { agentIds } from './table.ts';
5
+ import { resolveAgents } from './resolve.ts';
6
+ import { agentIds, readAgentTable } from './table.ts';
5
7
 
6
- /** The terminal question: what was detected, what exists, and the developer's earlier choice as the shown default. */
7
- export const askAgentsInTerminal = (question: IAgentQuestion): string | null => {
8
- const lines = [
9
- 'Which coding agents do you use in this project? (comma-separated, Enter accepts)',
8
+ const listOf = (opts: { agents: string[] }): string =>
9
+ opts.agents.length === 0 ? AgentConstants.NONE : opts.agents.join(', ');
10
+
11
+ /**
12
+ * The question as the terminal shows it. It says exactly what an empty answer does: it keeps the
13
+ * choice stored on this machine when there is one, else it takes what was detected.
14
+ */
15
+ export const renderAgentsQuestion = (question: IAgentQuestion): string => {
16
+ const enter =
17
+ question.stored === undefined
18
+ ? `Enter accepts the detected list: ${listOf({ agents: question.detected })}`
19
+ : `Enter keeps your earlier choice: ${listOf({ agents: question.stored })}`;
20
+
21
+ return [
22
+ `Which coding agents do you use in this project? (comma-separated; ${enter})`,
10
23
  ` detected: ${question.detected.length === 0 ? '(none)' : question.detected.join(', ')}`,
11
24
  ...(question.stored === undefined
12
25
  ? []
13
- : [
14
- ` chosen before: ${question.stored.length === 0 ? AgentConstants.NONE : question.stored.join(', ')}`,
15
- ]),
26
+ : [` chosen before: ${listOf({ agents: question.stored })}`]),
16
27
  ` available: ${[...agentIds(), AgentConstants.NONE].join(', ')}`,
17
- ];
28
+ ].join('\n');
29
+ };
18
30
 
19
- process.stdout.write(`${lines.join('\n')}\n`);
31
+ export const askAgentsInTerminal = (question: IAgentQuestion): string | null => {
32
+ process.stdout.write(`${renderAgentsQuestion(question)}\n`);
20
33
 
21
34
  return askWithPrompt({ question: 'Agents' });
22
35
  };
36
+
37
+ export type TResolveAgentsInput = Omit<Parameters<typeof resolveAgents>[0], 'ask'>;
38
+
39
+ const hintOf = (opts: { id: string; question: IAgentQuestion }): string | undefined => {
40
+ const notes = [
41
+ ...(opts.question.detected.includes(opts.id) ? ['detected'] : []),
42
+ ...(opts.question.stored?.includes(opts.id) ? ['chosen before'] : []),
43
+ ];
44
+
45
+ return notes.length === 0 ? undefined : notes.join(', ');
46
+ };
47
+
48
+ /**
49
+ * The checkbox menu: what this machine chose before is ticked, else what was detected. The first
50
+ * pass of the resolution only learns whether it has to ask; the answer then goes back in as a list,
51
+ * so the order in which sources are tried stays in `resolveAgents`.
52
+ */
53
+ const resolveAgentsWithMenu = async (opts: TResolveAgentsInput): Promise<TAgentResolution> => {
54
+ const questions: IAgentQuestion[] = [];
55
+ const first = resolveAgents({
56
+ ...opts,
57
+ ask: question => {
58
+ questions.push(question);
59
+
60
+ return '';
61
+ },
62
+ });
63
+ const [question] = questions;
64
+
65
+ if (question === undefined) {
66
+ return first;
67
+ }
68
+
69
+ const picked = await promptMultiselect({
70
+ message: 'Which coding agents do you use in this project?',
71
+ choices: readAgentTable().map(entry => ({
72
+ value: entry.id,
73
+ label: entry.name,
74
+ hint: hintOf({ id: entry.id, question }),
75
+ })),
76
+ initial: question.stored ?? question.detected,
77
+ });
78
+
79
+ return resolveAgents({
80
+ ...opts,
81
+ ask: () => {
82
+ if (picked === null) {
83
+ return null;
84
+ }
85
+
86
+ return picked.length === 0 ? AgentConstants.NONE : picked.join(',');
87
+ },
88
+ });
89
+ };
90
+
91
+ /** Menus in a terminal that can draw them, the plain question everywhere else. */
92
+ export const resolveAgentsInTerminal = (opts: TResolveAgentsInput): Promise<TAgentResolution> =>
93
+ menusAvailable()
94
+ ? resolveAgentsWithMenu(opts)
95
+ : Promise.resolve(resolveAgents({ ...opts, ask: askAgentsInTerminal }));
@@ -25,13 +25,23 @@ export const atlasServerEntry = (opts: { root: string }): { command: string; arg
25
25
  ],
26
26
  });
27
27
 
28
+ /**
29
+ * The atlas server as the root `.mcp.json` starts it: the same for every developer, so it is relative.
30
+ * Claude Code, omp and Copilot CLI launch a project server from the project root.
31
+ */
32
+ export const canonicalAtlasEntry = (): { command: string; args: string[] } => ({
33
+ command: 'bun',
34
+ args: ['x', '--no-install', 'vulcan', 'x', 'atlas', 'mcp', '--root', '.'],
35
+ });
36
+
28
37
  const isRecord = (value: unknown): value is Record<string, unknown> =>
29
38
  typeof value === 'object' && value !== null && !Array.isArray(value);
30
39
 
31
40
  /**
32
41
  * Whether an `atlas` entry is the one sync writes, for whatever place: `bun <root>/node_modules/.bin/vulcan
33
- * x atlas mcp --root <root>` (plus `type: stdio` for VS Code) with the two paths agreeing. Anything else
34
- * is the user's. A project that moved is recognised this way and rewritten.
42
+ * x atlas mcp --root <root>` (plus `type: stdio` for VS Code) with the two paths agreeing, or the relative
43
+ * entry of the root `.mcp.json`. Anything else is the user's. A project that moved is recognised this way
44
+ * and rewritten.
35
45
  */
36
46
  const isOwnEntry = (opts: { entry: unknown }): boolean => {
37
47
  const { entry } = opts;
@@ -40,6 +50,10 @@ const isOwnEntry = (opts: { entry: unknown }): boolean => {
40
50
  return false;
41
51
  }
42
52
 
53
+ if (JSON.stringify(entry) === JSON.stringify(canonicalAtlasEntry())) {
54
+ return true;
55
+ }
56
+
43
57
  const keys = Object.keys(entry).filter(key => key !== 'type');
44
58
  const [bin, ...rest] = entry.args;
45
59
  const root = rest[4];
@@ -78,8 +78,15 @@ export const resolveAgents = (opts: {
78
78
  };
79
79
  }
80
80
 
81
+ // Enter keeps what this machine chose before; with no earlier choice it takes what was detected.
81
82
  return answer.trim() === ''
82
- ? { ok: true, agents: opts.detected, source: 'asked', writeLocal: true, hint: undefined }
83
+ ? {
84
+ ok: true,
85
+ agents: stored.agents ?? opts.detected,
86
+ source: 'asked',
87
+ writeLocal: true,
88
+ hint: undefined,
89
+ }
83
90
  : fromList({ value: answer, source: 'asked' });
84
91
  };
85
92
 
@@ -8,8 +8,11 @@ Usage: bun x vulcan <command>
8
8
  init --preset <name|file:path> --project <name> --app <name> [--backend-dir|--frontend-dir <name>]
9
9
  [--shared-dir <name>] Create a monorepo with its first app, from a framework preset
10
10
  (a name missing from the flags is asked in a terminal)
11
- add --preset <name|file:path> --app <name> [--backend-dir|--frontend-dir <name>]
12
- [--api <app> | --no-api] Add an app to the monorepo (a frontend says which backend to proxy to)
11
+ add --preset <name|file:path> (--app <name> | --lib <name>) [--dir <folder>] [--scope <@scope>]
12
+ [--backend-dir|--frontend-dir <name>] [--api <app> | --no-api]
13
+ 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)
13
16
  sync [--agents <list>|list] [--dry-run] [--prune]
14
17
  Write the adapters of the agents you chose (--agents claude,omp or none,
15
18
  stored in .agents/vulcan.local.json; --agents list shows the table);
@@ -4,11 +4,10 @@ import type { ICommandContext } from '../common/index.ts';
4
4
  import { homedir } from 'node:os';
5
5
  import {
6
6
  AgentConstants,
7
- askAgentsInTerminal,
8
7
  detectAgents,
9
8
  readLocalChoice,
10
9
  readAgentTable,
11
- resolveAgents,
10
+ resolveAgentsInTerminal,
12
11
  } from '../agents/index.ts';
13
12
  import { loadConfig } from '../config/index.ts';
14
13
  import {
@@ -82,7 +81,7 @@ export const runSyncFlow = async (
82
81
  return ExitCodes.FAILURE;
83
82
  }
84
83
 
85
- const resolved = resolveAgents({
84
+ const resolved = await resolveAgentsInTerminal({
86
85
  root: opts.cwd,
87
86
  flag,
88
87
  configAgents: loaded.config.agents,
@@ -92,7 +91,6 @@ export const runSyncFlow = async (
92
91
  home: process.env.HOME ?? homedir(),
93
92
  path: process.env.PATH ?? '',
94
93
  }),
95
- ask: askAgentsInTerminal,
96
94
  });
97
95
 
98
96
  if (!resolved.ok) {
@@ -209,6 +209,8 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
209
209
  name: z.string(),
210
210
  repo: z.string(),
211
211
  ref: z.string().default('develop'),
212
+ /** `installed` (default): the docs are read at the tag of the newest installed package; `ref`: at `ref`. */
213
+ pin: z.enum(['installed', 'ref']).optional(),
212
214
  }),
213
215
  )
214
216
  .default([]),
@@ -10,7 +10,17 @@ import { AppSides, CreateFlags } from './common/index.ts';
10
10
  import type { IAppsBlock, ILocatedPreset, IPresetSpec, TAppSide } from './common/index.ts';
11
11
  import { today, writeFile } from './files.ts';
12
12
  import { recordedPresetOf } from './lib-preset.ts';
13
- import { askWithPrompt, readFlag, resolveNames, SIDE_FIELDS } from './names.ts';
13
+ import { menusAvailable, promptSelect } from '../ui/index.ts';
14
+ import { askPresetSpec } from './preset-menu.ts';
15
+ import { ABORTED, confirmWrite, planLines } from './plan.ts';
16
+ import {
17
+ askInTerminal,
18
+ askWithPrompt,
19
+ nameProblem,
20
+ readFlag,
21
+ resolveNames,
22
+ SIDE_FIELDS,
23
+ } from './names.ts';
14
24
  import { readExistingApps, renderNext } from './next.ts';
15
25
  import { copyPresetFiles, locatePreset, parsePresetSpec } from './preset.ts';
16
26
  import { isInstallSkipped, runBun } from './process.ts';
@@ -103,10 +113,22 @@ const kindCommands = (opts: { presetValue: string }): string[] => [
103
113
  `bun x --no-install vulcan add --preset ${opts.presetValue} ${CreateFlags.LIB} <name>`,
104
114
  ];
105
115
 
116
+ const NO_BACKEND = ':none';
117
+ const KIND_HINTS: Record<string, string> = { app: 'a runnable app', lib: 'a shared package' };
118
+
106
119
  const SAY_WHAT = `say what to create - \`${CreateFlags.APP} <name>\` (a runnable app) or \`${CreateFlags.LIB} <name>\` (a shared package)`;
107
120
 
108
121
  /** The terminal asks which kind, listing only what the preset offers; end of input stops the command. */
109
- const askKind = (opts: { offered: string[] }): string | undefined => {
122
+ const askKind = async (opts: { offered: string[] }): Promise<string | undefined> => {
123
+ if (menusAvailable()) {
124
+ const picked = await promptSelect({
125
+ message: 'What do you want to create?',
126
+ choices: opts.offered.map(kind => ({ value: kind, label: kind, hint: KIND_HINTS[kind] })),
127
+ });
128
+
129
+ return picked ?? undefined;
130
+ }
131
+
110
132
  for (;;) {
111
133
  const answer = askWithPrompt({
112
134
  question: `What do you want to create? (${opts.offered.join(', ')})`,
@@ -156,13 +178,13 @@ const literal = (opts: {
156
178
  ];
157
179
 
158
180
  /** A frontend's proxy target: the chosen backend app's port, or nothing when it has no backend. */
159
- const resolveApiUrl = (opts: {
181
+ const resolveApiUrl = async (opts: {
160
182
  root: string;
161
183
  args: string[];
162
184
  interactive: boolean;
163
185
  backendFolder: string | undefined;
164
186
  packages: IProjectPackage[];
165
- }): { ok: true; apiUrl: string } | { ok: false; error: string } => {
187
+ }): Promise<{ ok: true; apiUrl: string } | { ok: false; error: string }> => {
166
188
  if (opts.args.includes(CreateFlags.NO_API)) {
167
189
  return { ok: true, apiUrl: '' };
168
190
  }
@@ -174,8 +196,34 @@ const resolveApiUrl = (opts: {
174
196
  return { ok: false, error: MISSING_API };
175
197
  }
176
198
 
177
- chosen =
178
- askWithPrompt({ question: 'Backend app to proxy /api to (empty for none)' })?.trim() ?? '';
199
+ if (menusAvailable()) {
200
+ const backends = opts.packages.filter(
201
+ entry =>
202
+ opts.backendFolder !== undefined && entry.path.startsWith(`${opts.backendFolder}/`),
203
+ );
204
+
205
+ // Nothing to pick from: a frontend of a project without a backend has nothing to proxy to.
206
+ if (backends.length === 0) {
207
+ return { ok: true, apiUrl: '' };
208
+ }
209
+
210
+ const picked = await promptSelect({
211
+ message: 'Backend app to proxy /api to',
212
+ choices: [
213
+ ...backends.map(entry => ({ value: entry.dir, label: entry.dir, hint: entry.path })),
214
+ { value: NO_BACKEND, label: 'none', hint: 'no proxy' },
215
+ ],
216
+ });
217
+
218
+ if (picked === null) {
219
+ return { ok: false, error: 'aborted' };
220
+ }
221
+
222
+ chosen = picked === NO_BACKEND ? '' : picked;
223
+ } else {
224
+ chosen =
225
+ askWithPrompt({ question: 'Backend app to proxy /api to (empty for none)' })?.trim() ?? '';
226
+ }
179
227
 
180
228
  if (chosen === '') {
181
229
  return { ok: true, apiUrl: '' };
@@ -236,11 +284,24 @@ const locate = async (opts: {
236
284
  : { ok: false, error: `could not install ${opts.spec.packageName}@${opts.spec.range}` };
237
285
  };
238
286
 
287
+ /** A terminal picks one of the presets the project recorded or an official one, or types another; null when cancelled. */
288
+ const askPreset = async (opts: { cwd: string }): Promise<string | null> => {
289
+ const loaded = await loadConfig({ root: opts.cwd });
290
+
291
+ return askPresetSpec({ recorded: loaded.ok ? (loaded.config.presets ?? []) : [] });
292
+ };
293
+
239
294
  const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): Promise<number> => {
240
295
  const { cwd } = opts;
241
- const presetValue = readFlag({ args: opts.args, flag: CreateFlags.PRESET });
296
+ const flagged = readFlag({ args: opts.args, flag: CreateFlags.PRESET });
242
297
 
243
- if (presetValue === undefined) {
298
+ if (flagged === undefined && !menusAvailable()) {
299
+ return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
300
+ }
301
+
302
+ const presetValue = flagged ?? (await askPreset({ cwd }))?.trim();
303
+
304
+ if (presetValue === undefined || presetValue === '') {
244
305
  return fail({ message: '--preset needs a value (a package name, or file:<path>)' });
245
306
  }
246
307
 
@@ -299,7 +360,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
299
360
 
300
361
  if (!libFlag && !appFlag) {
301
362
  const offered = ['app', ...(located.located.libFile === undefined ? [] : ['lib'])];
302
- const chosen = offered.length === 1 ? 'app' : askKind({ offered });
363
+ const chosen = offered.length === 1 ? 'app' : await askKind({ offered });
303
364
 
304
365
  if (chosen === undefined) {
305
366
  return fail({ message: SAY_WHAT });
@@ -309,7 +370,15 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
309
370
  }
310
371
 
311
372
  if (kind === 'lib') {
312
- const name = libName ?? askWithPrompt({ question: 'Name of this library' })?.trim();
373
+ const name =
374
+ libName ??
375
+ (
376
+ await askInTerminal({
377
+ question: 'Name of this library',
378
+ validate: value =>
379
+ value.trim() === '' ? undefined : nameProblem({ name: value.trim() }),
380
+ })
381
+ )?.trim();
313
382
 
314
383
  if (name === undefined || name === '') {
315
384
  return fail({ message: `${CreateFlags.LIB} needs a name` });
@@ -348,14 +417,15 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
348
417
 
349
418
  const side = preset.side;
350
419
  const previous = config.layout[side];
351
- const names = resolveNames({
420
+ const names = await resolveNames({
352
421
  fields: [
353
- { ...SIDE_FIELDS[side], previous },
422
+ // A menu does not ask for what cannot change: apps of one side share the folder the config holds.
423
+ { ...SIDE_FIELDS[side], previous, fixed: menusAvailable() },
354
424
  { key: 'app', flag: CreateFlags.APP, question: `Name of this ${side} app` },
355
425
  ],
356
426
  args: opts.args,
357
427
  interactive,
358
- ask: askWithPrompt,
428
+ ask: askInTerminal,
359
429
  });
360
430
 
361
431
  if (!names.ok) {
@@ -392,7 +462,7 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
392
462
  let apiUrl = '';
393
463
 
394
464
  if (side === AppSides.FRONTEND) {
395
- const api = resolveApiUrl({
465
+ const api = await resolveApiUrl({
396
466
  root: cwd,
397
467
  args: opts.args,
398
468
  interactive,
@@ -463,6 +533,25 @@ const runAdd = async (opts: { cwd: string; args: string[]; scratch: string }): P
463
533
  process.stderr.write(`${warning}\n`);
464
534
  }
465
535
 
536
+ const confirmed = await confirmWrite({
537
+ title: `Add ${app}`,
538
+ lines: planLines({
539
+ rows: [
540
+ ['app', `${folder}/${app}`],
541
+ ['side', side],
542
+ ['preset', `${packageName} ${packageVersion}`],
543
+ ['port', String(devPort)],
544
+ ...(side === AppSides.FRONTEND
545
+ ? [['proxy', apiUrl === '' ? '(none)' : apiUrl] as [string, string]]
546
+ : []),
547
+ ],
548
+ }),
549
+ });
550
+
551
+ if (!confirmed) {
552
+ return fail({ message: ABORTED });
553
+ }
554
+
466
555
  copyPresetFiles({
467
556
  located: located.located,
468
557
  target: join(cwd, folder, app),