@venizia/vulcan 0.3.8 → 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.
- package/README.md +2 -2
- package/base/skills/build-a-feature/SKILL.md +122 -0
- package/base/skills/build-a-feature/evals/evals.json +29 -0
- package/base/skills/docs-writing/SKILL.md +3 -1
- package/package.json +13 -11
- package/src/agents/atlas-block.ts +1 -0
- package/src/agents/exclude.ts +5 -0
- package/src/agents/prompt.ts +64 -2
- package/src/agents/render.ts +16 -2
- package/src/commands/sync.command.ts +2 -4
- package/src/config/schema.ts +2 -0
- package/src/create/add-app.ts +103 -14
- package/src/create/add-lib.ts +29 -6
- package/src/create/bunfig.ts +11 -0
- package/src/create/common/types.ts +16 -2
- package/src/create/init-monorepo.ts +37 -10
- package/src/create/names.ts +72 -7
- package/src/create/plan.ts +17 -0
- package/src/create/preset-menu.ts +45 -0
- package/src/create/preset.ts +25 -5
- package/src/create/workspace.ts +41 -1
- package/src/doctor/checks.ts +42 -13
- package/src/doctor/runner.ts +2 -1
- package/src/doctor/skills.ts +1 -42
- package/src/init/scaffold.ts +3 -41
- package/src/skills/frontmatter.ts +43 -0
- package/src/skills/index.ts +1 -0
- package/src/sync/agent-files.ts +59 -5
- package/src/sync/agent-removal.ts +55 -0
- package/src/sync/atlas-block.ts +4 -5
- package/src/ui/capability.ts +7 -0
- package/src/ui/index.ts +2 -0
- package/src/ui/keyboard.ts +39 -0
- package/src/ui/prompt.ts +94 -0
- package/base/templates/mcp.json +0 -8
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`,
|
|
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
|
+
}
|
|
@@ -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
|
|
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.
|
|
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,26 +34,28 @@
|
|
|
34
34
|
"LICENSE.md",
|
|
35
35
|
"src",
|
|
36
36
|
"base",
|
|
37
|
-
"
|
|
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": "
|
|
45
|
+
"test": "bun test"
|
|
45
46
|
},
|
|
46
47
|
"dependencies": {
|
|
47
|
-
"@
|
|
48
|
-
"@venizia/vulcan-
|
|
49
|
-
"
|
|
48
|
+
"@clack/prompts": "1.8.1",
|
|
49
|
+
"@venizia/vulcan-atlas": "0.3.10",
|
|
50
|
+
"@venizia/vulcan-okf": "0.3.10",
|
|
51
|
+
"zod": "^4.6.7"
|
|
50
52
|
},
|
|
51
53
|
"devDependencies": {
|
|
52
|
-
"@types/bun": "1.4.
|
|
53
|
-
"@venizia/dev-configs": "0.3.
|
|
54
|
-
"eslint": "10.
|
|
55
|
-
"oxfmt": "0.
|
|
56
|
-
"oxlint": "1.
|
|
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",
|
|
57
59
|
"oxlint-tsgolint": "7.0.2004",
|
|
58
60
|
"typescript": "^6.0.3"
|
|
59
61
|
},
|
|
@@ -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');
|
package/src/agents/exclude.ts
CHANGED
|
@@ -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)) {
|
package/src/agents/prompt.ts
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import { askWithPrompt } from '../create/names.ts';
|
|
2
|
-
import
|
|
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 {
|
|
5
|
+
import { resolveAgents } from './resolve.ts';
|
|
6
|
+
import { agentIds, readAgentTable } from './table.ts';
|
|
5
7
|
|
|
6
8
|
const listOf = (opts: { agents: string[] }): string =>
|
|
7
9
|
opts.agents.length === 0 ? AgentConstants.NONE : opts.agents.join(', ');
|
|
@@ -31,3 +33,63 @@ export const askAgentsInTerminal = (question: IAgentQuestion): string | null =>
|
|
|
31
33
|
|
|
32
34
|
return askWithPrompt({ question: 'Agents' });
|
|
33
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 }));
|
package/src/agents/render.ts
CHANGED
|
@@ -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
|
|
34
|
-
* is the user's. A project that moved is recognised this way
|
|
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];
|
|
@@ -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
|
-
|
|
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 =
|
|
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) {
|
package/src/config/schema.ts
CHANGED
|
@@ -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([]),
|
package/src/create/add-app.ts
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
178
|
-
|
|
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
|
|
296
|
+
const flagged = readFlag({ args: opts.args, flag: CreateFlags.PRESET });
|
|
242
297
|
|
|
243
|
-
if (
|
|
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 =
|
|
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
|
-
|
|
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:
|
|
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),
|