@venizia/vulcan 0.4.9-2 → 0.4.9-3
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 +5 -6
- package/base/make/vulcan.mk +1 -11
- package/base/rules.md +3 -8
- package/package.json +3 -3
- package/src/agents/atlas-block.ts +2 -2
- package/src/agents/common/constants.ts +1 -21
- package/src/agents/exclude.ts +2 -2
- package/src/agents/render.ts +2 -2
- package/src/agents/resolve.ts +1 -16
- package/src/commands/agents.command.ts +1 -1
- package/src/commands/help.command.ts +3 -4
- package/src/commands/init.command.ts +2 -15
- package/src/commands/sync.command.ts +0 -5
- package/src/commands/x.command.ts +1 -1
- package/src/common/constants.ts +0 -22
- package/src/common/layout-folder.ts +1 -5
- package/src/common/types.ts +0 -5
- package/src/config/common/constants.ts +2 -23
- package/src/config/common/types.ts +1 -10
- package/src/config/loader.ts +15 -16
- package/src/config/schema.ts +16 -21
- package/src/create/add-app.ts +2 -10
- package/src/create/add-lib.ts +1 -8
- package/src/create/common/constants.ts +0 -14
- package/src/create/common/types.ts +1 -2
- package/src/create/preset.ts +0 -12
- package/src/create/workspace.ts +5 -5
- package/src/doctor/checks.ts +20 -85
- package/src/doctor/common/constants.ts +2 -33
- package/src/doctor/runner.ts +0 -1
- package/src/doctor/tags.ts +4 -5
- package/src/hooks/codex-patch.ts +0 -6
- package/src/hooks/common/constants.ts +0 -24
- package/src/hooks/guard-manifest.ts +1 -1
- package/src/hooks/subagent-card.ts +1 -4
- package/src/init/common/constants.ts +0 -11
- package/src/init/scaffold.ts +8 -16
- package/src/manifest/render.ts +1 -25
- package/src/owner/constants.ts +0 -4
- package/src/owner/violations.ts +1 -15
- package/src/router.ts +1 -2
- package/src/rules/base.ts +0 -4
- package/src/rules/parser.ts +0 -10
- package/src/sync/base-rules.ts +1 -2
- package/src/sync/common/constants.ts +0 -18
- package/src/sync/common/types.ts +1 -1
- package/src/sync/index.ts +0 -1
- package/src/sync/planner.ts +1 -17
- package/src/sync/settings.ts +0 -9
- package/src/visualize/assets.ts +1 -1
- package/src/visualize/compare-schema.ts +0 -4
- package/src/visualize/constants.ts +0 -24
- package/src/visualize/kinds-schema.ts +0 -8
- package/src/wiki/constants.ts +0 -4
- package/base/templates/vulcan.config.js +0 -5
- package/base/templates/vulcan.config.mjs +0 -5
- package/base/templates/vulcan.config.ts +0 -6
- package/src/sync/prune.ts +0 -142
package/README.md
CHANGED
|
@@ -16,10 +16,10 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
|
|
|
16
16
|
|
|
17
17
|
| Command | What it does |
|
|
18
18
|
|---|---|
|
|
19
|
-
| `init
|
|
19
|
+
| `init` | Scaffold the project layer: `AGENTS.md`, `.configs/vulcan.config.mts`, 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
|
-
| `sync [--dry-run]
|
|
22
|
+
| `sync [--dry-run]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`; an existing 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. `--dry-run` writes nothing and labels each line `would create`, `would replace` or `would remove`. Idempotent |
|
|
23
23
|
| `doctor` | Check the project follows VULCAN; exit 1 on any violation |
|
|
24
24
|
| `upgrade [--stable \| --nightly] [<version\|tag>]` | Install the target `@venizia/vulcan`, then run `sync` from the newly installed CLI. `--stable` (default) is the `latest` dist-tag, never a prerelease; `--nightly` is the higher of `latest` and `next`; a named version or tag wins over both. `--nightly` that cannot read the dist-tags exits 1; a stable upgrade from an installed prerelease says that `--nightly` keeps the prerelease line |
|
|
25
25
|
| `x <tool> [args...]` | Run a shipped tool at the pinned version: `okf`, `atlas`. `x --help` prints the help; `x <tool> --help` goes to the tool |
|
|
@@ -30,7 +30,7 @@ clean MCP stdio server.
|
|
|
30
30
|
|
|
31
31
|
## The project config
|
|
32
32
|
|
|
33
|
-
`.configs/vulcan.config
|
|
33
|
+
`.configs/vulcan.config.mts`:
|
|
34
34
|
|
|
35
35
|
```ts
|
|
36
36
|
import type { VulcanConfig } from '@venizia/vulcan';
|
|
@@ -50,7 +50,7 @@ An unknown key is an error; every error names the file and the field.
|
|
|
50
50
|
|
|
51
51
|
## What ships (`base/`)
|
|
52
52
|
|
|
53
|
-
- `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (50 rules
|
|
53
|
+
- `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (50 rules).
|
|
54
54
|
- `slots.json` - rules a project picks a wording for (V-W-01 today).
|
|
55
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).
|
|
@@ -62,11 +62,10 @@ or shadows a shipped one.
|
|
|
62
62
|
## `doctor` checks
|
|
63
63
|
|
|
64
64
|
`config` (exactly one valid config) · `layout` (AGENTS.md, rules, knowledge bundle) · `rule-ids` (every
|
|
65
|
-
`V-` ID a project rule points at - an `Extends` list or a first cell - is a base rule
|
|
65
|
+
`V-` ID a project rule points at - an `Extends` list or a first cell - is a base rule) · `rule-slots` (every slot chosen, valid option) · `skills` (no shipped skill
|
|
66
66
|
shadowed) · `make` (includes `vulcan.mk`, no shipped target redefined) · `hooks` (shipped hooks are
|
|
67
67
|
not re-registered) · `adapters` (sync is current, no hand-written `CLAUDE.md`, valid settings) ·
|
|
68
68
|
`manifest` (`.agents/vulcan.manifest.json` exists and matches the config) · `tags` (every release tag `atlas.tagPattern` reads names a declared package, an alias or an ignored tag) ·
|
|
69
|
-
`prune` (no stale hook command or dead skill link - `sync --prune` removes them) ·
|
|
70
69
|
`apps` (every `layout` folder is a workspace and every package lives in one; skipped without `layout`) ·
|
|
71
70
|
`style` (`@venizia/dev-configs` declared by the package holding the lint config or the root, every lint config builds on it; the packages are `packages/*` and every configured package `path`) ·
|
|
72
71
|
`scaffold` (the config is filled in: a project whose `package.json` declares `workspaces` lists its `packages`, and `.agents/knowledge/index.md` no longer holds the `vulcan:scaffold` line `init` writes).
|
package/base/make/vulcan.mk
CHANGED
|
@@ -8,8 +8,7 @@ VULCAN_BASE ?= node_modules/@venizia/vulcan/base
|
|
|
8
8
|
WIKI_REPO ?=
|
|
9
9
|
|
|
10
10
|
.PHONY: vulcan-sync vulcan-doctor okf-check okf-check-strict okf-gen okf-coverage okf-viz \
|
|
11
|
-
surface-gen surface-check atlas-symbols atlas-releases
|
|
12
|
-
knowledge-symbols-check wiki-links-check wiki-anchors-check
|
|
11
|
+
surface-gen surface-check atlas-symbols atlas-releases wiki-links-check wiki-anchors-check
|
|
13
12
|
|
|
14
13
|
vulcan-sync: ## Write the agent adapters, settings, skill links and manifest from the config
|
|
15
14
|
@$(VULCAN) sync
|
|
@@ -51,15 +50,6 @@ atlas-symbols: ## Print the symbols atlas reads from the built or installed .d.t
|
|
|
51
50
|
atlas-releases: ## Print the release table atlas computes from the tags
|
|
52
51
|
@$(VULCAN) x atlas releases
|
|
53
52
|
|
|
54
|
-
# Writes the packages: list into every changelog entry that declares none - once, then review it.
|
|
55
|
-
changelogs-migrate: ## Write the packages: list into changelog entries that declare none
|
|
56
|
-
@$(VULCAN) x atlas changelogs migrate
|
|
57
|
-
|
|
58
|
-
# A concept may name code (`symbols:` in its frontmatter); this fails when a named symbol is gone or its
|
|
59
|
-
# signature changed since `vulcan x atlas concepts stamp`. It reads the built .d.ts - run it after build.
|
|
60
|
-
knowledge-symbols-check: ## Fail when a symbol a concept names is gone or its signature changed
|
|
61
|
-
@$(VULCAN) x atlas concepts check
|
|
62
|
-
|
|
63
53
|
# The wiki link gates. Set WIKI_REPO (owner/name) in the project's Makefile before the include. Flags go in
|
|
64
54
|
# WIKI_LINKS_FLAGS (--dirs, --skip-prose, --skip) and WIKI_ANCHORS_FLAGS (--content, --dist).
|
|
65
55
|
wiki-links-check: ## Fail when the wiki or the knowledge bundle names a source path git does not track
|
package/base/rules.md
CHANGED
|
@@ -1,20 +1,15 @@
|
|
|
1
1
|
# Rules - VULCAN base
|
|
2
2
|
|
|
3
3
|
<!-- Shipped by @venizia/vulcan. Never edit in a project: add extensions in .agents/rules.md.
|
|
4
|
-
W, S, P, B are INTERIM until the base-rules work reconciles the rules the projects share.
|
|
5
4
|
C is the shared coding style, shipped to every project; a rule that binds one project's own stack
|
|
6
5
|
lives in that project. -->
|
|
7
6
|
|
|
8
7
|
Cite by ID. Every rule has "Enforced by". Base IDs carry the `V-` namespace (`V-W-01`, `V-C-04`).
|
|
9
8
|
A project extends this set in its own `.agents/rules.md` with bare IDs (`W-06`, `C-19`), which can
|
|
10
9
|
never collide with a base ID. A `V-` ID there points at a base rule (`Extends V-W-01`); `vulcan doctor`
|
|
11
|
-
fails one the base does not carry
|
|
10
|
+
fails one the base does not carry.
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
- `V-W-05` - the task-manager loop
|
|
16
|
-
- `V-C-03` - `@inject` on container-built classes, moved to the project whose stack it binds
|
|
17
|
-
- `V-C-05` - `getError` / `ApplicationError`, moved to the project whose stack it binds, with the hard stack once in `V-C-18`
|
|
12
|
+
An ID the base drops is never reused.
|
|
18
13
|
|
|
19
14
|
## W - Write boundaries
|
|
20
15
|
|
|
@@ -78,7 +73,7 @@ Retired IDs are never reused (2026-10-17):
|
|
|
78
73
|
| V-C-04 | **Never abbreviate identifiers:** `ProductRepository` not `ProductRepo`, `ProductDocument` not `ProductDoc`; type parameters too (`TDocument`, not `TDoc`). A project lists its own exceptions in its rules (for example `tz` for a time zone). | SOFT |
|
|
79
74
|
| V-C-06 | **Never a silent catch - log it.** Always braces. Early return. `switch` with `default` over a long if-else chain. Strict TypeScript; no `any` where a type exists. | LINT (braces, floating promises) + SOFT |
|
|
80
75
|
| V-C-07 | **A function name opens with its verb** - `generate` `build` `to` `is` `has` `assert` `extract` `enrich` `get` `resolve`. `is*` returns a boolean and leaves the branch to the caller; `assert*` throws and returns `void`, so the code after it needs none - reach for `assert*` when every caller would throw on `false` anyway. `has*` is the ownership question (`hasBucket`, never `isBucketExists`). That list is for UTILITY functions; service methods lean on a wider set. **Arrow functions, not `function` declarations** (do not churn existing ones). State plus the operations on it live in a class with static members - the `LoggerFactory` shape - never module-level `let` plus exported arrows. | SOFT |
|
|
81
|
-
| V-C-08 | **Enumerable strings are a const class plus `TConstValue`,** never a raw string-literal union.
|
|
76
|
+
| V-C-08 | **Enumerable strings are a const class plus `TConstValue`,** never a raw string-literal union. When something validates against such a class, it carries `static readonly SCHEME_SET = new Set([...])` over its values and `static isValid(value: string): boolean` reading it, so a runtime check exists wherever a value crosses a boundary (`IsolationLevels` in connectors is the model; a subclass redeclares `SCHEME_SET` with `...Parent.SCHEME_SET` first); a class nothing validates against needs neither. The `T`/`I` prefix follows the declaration keyword: `type` gets `T`, `interface` gets `I`; an interface turned into a type alias is renamed, and no tool catches it - grep both directions. | SOFT |
|
|
82
77
|
| V-C-09 | **Comments state only a constraint the code cannot show** - one to three lines; no history, no dates, no decision notes, no restating the code - the one exception is the `// SHORTCUT:` marker of V-B-07. Most code needs none. | SOFT |
|
|
83
78
|
| V-C-10 | **No explicit cast in new code.** `as X`, `as any`, `as unknown as X` and `as never` assert nothing; they silence the compiler where the type is wrong. Fix the type instead: a generic on the setter, a narrower parameter, a typed helper, `satisfies`. A pre-existing cast is removed when the line is touched, never copied. Generic parameters are full words (`ApplicationType`, `TDocument`), never `App` or `TDoc` (V-C-04). | SOFT |
|
|
84
79
|
| V-C-11 | **SIMPLE FIRST, in code and in prose.** Fewest concepts, plainest words, smallest surface. Complexity must buy correctness, speed or safety the simple version cannot, and the artifact says what it bought. Something a reader cannot follow in one pass is a defect even when it works. Fix the root cause with the smallest change; never layer an abstraction on a misdiagnosed problem. Small means the code holds only what the task needs - not golfed: no clever one-liners to save lines, and no code for a need nobody has yet. | SOFT |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/vulcan",
|
|
3
|
-
"version": "0.4.9-
|
|
3
|
+
"version": "0.4.9-3",
|
|
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
|
"bugs": {
|
|
@@ -44,8 +44,8 @@
|
|
|
44
44
|
},
|
|
45
45
|
"dependencies": {
|
|
46
46
|
"@clack/prompts": "1.8.1",
|
|
47
|
-
"@venizia/vulcan-atlas": "0.4.9-
|
|
48
|
-
"@venizia/vulcan-okf": "0.4.9-
|
|
47
|
+
"@venizia/vulcan-atlas": "0.4.9-3",
|
|
48
|
+
"@venizia/vulcan-okf": "0.4.9-3",
|
|
49
49
|
"zod": "^4.6.7"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
|
|
1
|
+
const ATLAS_BLOCK_START =
|
|
2
2
|
'<!-- vulcan:atlas:start - generated by vulcan sync from .configs/vulcan.config.*; do not edit -->';
|
|
3
|
-
|
|
3
|
+
const ATLAS_BLOCK_END = '<!-- vulcan:atlas:end -->';
|
|
4
4
|
const START_PREFIX = '<!-- vulcan:atlas:start';
|
|
5
5
|
const MUST_READ = '## Must read first';
|
|
6
6
|
|
|
@@ -10,39 +10,19 @@ export class AgentScopes {
|
|
|
10
10
|
}
|
|
11
11
|
}
|
|
12
12
|
|
|
13
|
-
/** Why an agent's list was chosen: a flag, the local file, the config,
|
|
13
|
+
/** Why an agent's list was chosen: a flag, the local file, the config, the question, or the default. */
|
|
14
14
|
export class AgentSources {
|
|
15
15
|
static readonly FLAG = 'flag';
|
|
16
16
|
static readonly LOCAL = 'local';
|
|
17
17
|
static readonly CONFIG = 'config';
|
|
18
|
-
static readonly MIGRATION = 'migration';
|
|
19
18
|
static readonly ASKED = 'asked';
|
|
20
19
|
static readonly DEFAULT = 'default';
|
|
21
|
-
|
|
22
|
-
static readonly SCHEME_SET = new Set<string>([
|
|
23
|
-
this.FLAG,
|
|
24
|
-
this.LOCAL,
|
|
25
|
-
this.CONFIG,
|
|
26
|
-
this.MIGRATION,
|
|
27
|
-
this.ASKED,
|
|
28
|
-
this.DEFAULT,
|
|
29
|
-
]);
|
|
30
|
-
|
|
31
|
-
static isValid(value: string): boolean {
|
|
32
|
-
return this.SCHEME_SET.has(value);
|
|
33
|
-
}
|
|
34
20
|
}
|
|
35
21
|
|
|
36
22
|
/** What taking an entry out of an agent's file found: it was not there, or it was and is gone. */
|
|
37
23
|
export class RemoveOutcomes {
|
|
38
24
|
static readonly ABSENT = 'absent';
|
|
39
25
|
static readonly REMOVED = 'removed';
|
|
40
|
-
|
|
41
|
-
static readonly SCHEME_SET = new Set<string>([this.ABSENT, this.REMOVED]);
|
|
42
|
-
|
|
43
|
-
static isValid(value: string): boolean {
|
|
44
|
-
return this.SCHEME_SET.has(value);
|
|
45
|
-
}
|
|
46
26
|
}
|
|
47
27
|
|
|
48
28
|
/** How a guard reaches an agent that has no Claude-style hook commands: a file the agent loads. */
|
package/src/agents/exclude.ts
CHANGED
|
@@ -2,9 +2,9 @@ import { AgentConstants, AgentScopes } from './common/index.ts';
|
|
|
2
2
|
import { LOCAL_AGENTS_FILE } from './local.ts';
|
|
3
3
|
import { AgentTable } from './table.ts';
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
const EXCLUDE_BLOCK_START =
|
|
6
6
|
'# vulcan:start - written by vulcan sync for the agents you chose; do not edit';
|
|
7
|
-
|
|
7
|
+
const EXCLUDE_BLOCK_END = '# vulcan:end';
|
|
8
8
|
const START_PREFIX = '# vulcan:start';
|
|
9
9
|
/** A block's start line: the project it belongs to sits in brackets after the marker, none for the git top level. */
|
|
10
10
|
const START_PATTERN = /^# vulcan:start(?: \((.*)\))? - written/;
|
package/src/agents/render.ts
CHANGED
|
@@ -2,8 +2,8 @@ import { join } from 'node:path';
|
|
|
2
2
|
import { RecordValue } from '../common/record.ts';
|
|
3
3
|
import { RemoveOutcomes } from './common/index.ts';
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
5
|
+
const CODEX_BLOCK_START = '# vulcan:atlas:start';
|
|
6
|
+
const CODEX_BLOCK_END = '# vulcan:atlas:end';
|
|
7
7
|
const CODEX_TABLE = '[mcp_servers.atlas]';
|
|
8
8
|
const SERVER_NAME = 'atlas';
|
|
9
9
|
|
package/src/agents/resolve.ts
CHANGED
|
@@ -1,12 +1,8 @@
|
|
|
1
|
-
import { existsSync } from 'node:fs';
|
|
2
|
-
import { join } from 'node:path';
|
|
3
1
|
import { AgentConstants, AgentSources } from './common/index.ts';
|
|
4
2
|
import type { TAgentResolution, TAskAgents } from './common/index.ts';
|
|
5
3
|
import { LocalChoice } from './local.ts';
|
|
6
4
|
import { AgentTable } from './table.ts';
|
|
7
5
|
|
|
8
|
-
const PROJECT_FILES = ['CLAUDE.md', '.claude'];
|
|
9
|
-
|
|
10
6
|
export const NO_TTY_HINT = `vulcan sync: no agents chosen on this machine - wrote the Claude files as before; to choose, run: vulcan sync ${AgentConstants.FLAG} ${AgentConstants.EXAMPLE_LIST} (or ${AgentConstants.NONE})`;
|
|
11
7
|
|
|
12
8
|
type TParsed = { ok: true; agents: string[] } | { ok: false; error: string };
|
|
@@ -54,8 +50,7 @@ export class AgentSelection {
|
|
|
54
50
|
|
|
55
51
|
/**
|
|
56
52
|
* Which agents this machine uses, in order: the flag, the stored choice, the committed config's
|
|
57
|
-
* suggestion,
|
|
58
|
-
* default (no terminal, with a hint and nothing stored).
|
|
53
|
+
* suggestion, then ask (terminal) or the Claude default (no terminal, with a hint and nothing stored).
|
|
59
54
|
*/
|
|
60
55
|
static resolve(opts: {
|
|
61
56
|
root: string;
|
|
@@ -127,16 +122,6 @@ export class AgentSelection {
|
|
|
127
122
|
};
|
|
128
123
|
}
|
|
129
124
|
|
|
130
|
-
if (PROJECT_FILES.some((file) => existsSync(join(opts.root, file)))) {
|
|
131
|
-
return {
|
|
132
|
-
ok: true,
|
|
133
|
-
agents: ['claude'],
|
|
134
|
-
source: AgentSources.MIGRATION,
|
|
135
|
-
writeLocal: true,
|
|
136
|
-
hint: undefined,
|
|
137
|
-
};
|
|
138
|
-
}
|
|
139
|
-
|
|
140
125
|
if (opts.interactive) {
|
|
141
126
|
return askNow();
|
|
142
127
|
}
|
|
@@ -21,7 +21,7 @@ const detected = (opts: { root: string }): string[] =>
|
|
|
21
21
|
path: process.env.PATH ?? '',
|
|
22
22
|
});
|
|
23
23
|
|
|
24
|
-
/** What this machine uses now: the stored choice
|
|
24
|
+
/** What this machine uses now: the stored choice or the config's suggestion; nothing when it never chose. */
|
|
25
25
|
const currentAgents = async (opts: {
|
|
26
26
|
root: string;
|
|
27
27
|
}): Promise<{ ok: true; agents: string[]; chosen: boolean } | { ok: false; error: string }> => {
|
|
@@ -4,7 +4,7 @@ const HELP = `vulcan ${VULCAN_VERSION} - one setup, one workflow for every proje
|
|
|
4
4
|
|
|
5
5
|
Usage: bun x vulcan <command>
|
|
6
6
|
|
|
7
|
-
init
|
|
7
|
+
init Scaffold the project layer (never overwrites)
|
|
8
8
|
init --preset <name|file:path> --project <name> --app <name> [--backend-dir|--frontend-dir <path>]
|
|
9
9
|
[--shared-dir <path>] [--scope <@scope>]
|
|
10
10
|
Create a monorepo with its first app, from a framework preset
|
|
@@ -21,10 +21,9 @@ Usage: bun x vulcan <command>
|
|
|
21
21
|
a shared package) against the file the package has (same, differs,
|
|
22
22
|
missing); --full prints the unified diffs, --check exits 1 when
|
|
23
23
|
anything differs or is missing
|
|
24
|
-
sync [--agents <list>|list] [--dry-run]
|
|
24
|
+
sync [--agents <list>|list] [--dry-run]
|
|
25
25
|
Write the adapters of the agents you chose (--agents claude,omp or none,
|
|
26
|
-
stored in .agents/vulcan.local.json; --agents list shows the table)
|
|
27
|
-
--prune also removes stale hooks and dead skill links
|
|
26
|
+
stored in .agents/vulcan.local.json; --agents list shows the table)
|
|
28
27
|
agents [list|add <ids>|remove <ids>|setup] [--dry-run]
|
|
29
28
|
See, add, remove or re-choose the coding agents you use on this machine
|
|
30
29
|
doctor Check the project follows VULCAN; exit 1 on any violation
|
|
@@ -2,11 +2,10 @@ import { existsSync } from 'node:fs';
|
|
|
2
2
|
import { join } from 'node:path';
|
|
3
3
|
import { ExitCodes } from '../common/index.ts';
|
|
4
4
|
import type { ICommandContext } from '../common/index.ts';
|
|
5
|
-
import { ConfigExtensions } from '../config/index.ts';
|
|
6
5
|
import { CreateFlags } from '../create/common/index.ts';
|
|
7
6
|
import { Monorepo } from '../create/init-monorepo.ts';
|
|
8
7
|
import { SubProcess } from '../create/process.ts';
|
|
9
|
-
import {
|
|
8
|
+
import { ProjectScaffold } from '../init/index.ts';
|
|
10
9
|
import { ProfilePrompt } from './profile.command.ts';
|
|
11
10
|
|
|
12
11
|
export const runInitCommand = async (opts: ICommandContext): Promise<number> => {
|
|
@@ -14,18 +13,6 @@ export const runInitCommand = async (opts: ICommandContext): Promise<number> =>
|
|
|
14
13
|
return Monorepo.create({ cwd: opts.cwd, args: opts.args });
|
|
15
14
|
}
|
|
16
15
|
|
|
17
|
-
const flagIndex = opts.args.indexOf(InitConstants.CONFIG_FLAG);
|
|
18
|
-
const requested = flagIndex === -1 ? ConfigExtensions.MTS : (opts.args[flagIndex + 1] ?? '');
|
|
19
|
-
const extension = ConfigExtensions.LOOKUP_ORDER.find((value) => value === requested);
|
|
20
|
-
|
|
21
|
-
if (extension === undefined) {
|
|
22
|
-
process.stderr.write(
|
|
23
|
-
`vulcan init: ${InitConstants.CONFIG_FLAG} takes one of ${ConfigExtensions.LOOKUP_ORDER.join(', ')}\n`,
|
|
24
|
-
);
|
|
25
|
-
|
|
26
|
-
return ExitCodes.FAILURE;
|
|
27
|
-
}
|
|
28
|
-
|
|
29
16
|
// Without it `bun add` walks up to a parent project and installs there.
|
|
30
17
|
if (!existsSync(join(opts.cwd, 'package.json'))) {
|
|
31
18
|
process.stderr.write(
|
|
@@ -35,7 +22,7 @@ export const runInitCommand = async (opts: ICommandContext): Promise<number> =>
|
|
|
35
22
|
return ExitCodes.FAILURE;
|
|
36
23
|
}
|
|
37
24
|
|
|
38
|
-
const result = ProjectScaffold.scaffold({ root: opts.cwd
|
|
25
|
+
const result = ProjectScaffold.scaffold({ root: opts.cwd });
|
|
39
26
|
|
|
40
27
|
for (const entry of result.entries) {
|
|
41
28
|
process.stderr.write(` ${entry.status.padEnd(8)} ${entry.subject}\n`);
|
|
@@ -17,14 +17,12 @@ import {
|
|
|
17
17
|
BaseRulesDiff,
|
|
18
18
|
ExcludePlan,
|
|
19
19
|
LocalPlan,
|
|
20
|
-
PrunePlan,
|
|
21
20
|
SyncConstants,
|
|
22
21
|
SyncPlanner,
|
|
23
22
|
SyncStatuses,
|
|
24
23
|
} from '../sync/index.ts';
|
|
25
24
|
|
|
26
25
|
const DRY_RUN_FLAG = '--dry-run';
|
|
27
|
-
const PRUNE_FLAG = '--prune';
|
|
28
26
|
const LABEL_WIDTH = 9;
|
|
29
27
|
|
|
30
28
|
/** Under --dry-run nothing is written, so a write is labelled as what it would do. */
|
|
@@ -106,8 +104,6 @@ export class SyncFlow {
|
|
|
106
104
|
(id) => !resolved.agents.includes(id),
|
|
107
105
|
);
|
|
108
106
|
const dryRun = opts.args.includes(DRY_RUN_FLAG);
|
|
109
|
-
// Planned before anything is written: prune reads the managed record of the previous sync.
|
|
110
|
-
const pruned = opts.args.includes(PRUNE_FLAG) ? PrunePlan.plan({ root: opts.cwd }) : [];
|
|
111
107
|
// The stored choice is listed whether it was just written or only read; a machine that has not chosen stores nothing.
|
|
112
108
|
const stored =
|
|
113
109
|
resolved.writeLocal || resolved.source === 'local'
|
|
@@ -123,7 +119,6 @@ export class SyncFlow {
|
|
|
123
119
|
...stored,
|
|
124
120
|
...LocalPlan.planWorkspace({ root: opts.cwd }),
|
|
125
121
|
...ExcludePlan.plan({ root: opts.cwd, agents: resolved.agents }),
|
|
126
|
-
...pruned,
|
|
127
122
|
];
|
|
128
123
|
// Read before the manifest action rewrites the hashes it compares against.
|
|
129
124
|
const changes = BaseRulesDiff.diff({ root: opts.cwd });
|
|
@@ -50,7 +50,7 @@ export class ToolRunner {
|
|
|
50
50
|
static async buildEnvironment(opts: {
|
|
51
51
|
root: string;
|
|
52
52
|
}): Promise<{ ok: true; env: Record<string, string> } | { ok: false; error: string }> {
|
|
53
|
-
if (ConfigLoader.
|
|
53
|
+
if (ConfigLoader.findFile({ root: opts.root }) === undefined) {
|
|
54
54
|
return { ok: true, env: {} };
|
|
55
55
|
}
|
|
56
56
|
|
package/src/common/constants.ts
CHANGED
|
@@ -12,24 +12,6 @@ export class VulcanCommands {
|
|
|
12
12
|
static readonly X = 'x';
|
|
13
13
|
static readonly HELP = 'help';
|
|
14
14
|
static readonly VERSION = 'version';
|
|
15
|
-
static readonly SCHEME_SET = new Set<string>([
|
|
16
|
-
this.INIT,
|
|
17
|
-
this.ADD,
|
|
18
|
-
this.SYNC,
|
|
19
|
-
this.AGENTS,
|
|
20
|
-
this.DOCTOR,
|
|
21
|
-
this.UPGRADE,
|
|
22
|
-
this.CLEAN,
|
|
23
|
-
this.PROFILE,
|
|
24
|
-
this.PRESET,
|
|
25
|
-
this.VISUALIZE,
|
|
26
|
-
this.X,
|
|
27
|
-
this.HELP,
|
|
28
|
-
this.VERSION,
|
|
29
|
-
]);
|
|
30
|
-
static isValid(value: string): boolean {
|
|
31
|
-
return this.SCHEME_SET.has(value);
|
|
32
|
-
}
|
|
33
15
|
}
|
|
34
16
|
|
|
35
17
|
/** The release channels `vulcan upgrade` picks between; the channel is a flag, never stored in the config. */
|
|
@@ -38,10 +20,6 @@ export class UpgradeFlags {
|
|
|
38
20
|
static readonly NIGHTLY = '--nightly';
|
|
39
21
|
/** Tests only: a JSON object of dist-tags that stands in for the registry read. */
|
|
40
22
|
static readonly DIST_TAGS_ENV = 'VULCAN_DIST_TAGS';
|
|
41
|
-
static readonly SCHEME_SET = new Set<string>([this.STABLE, this.NIGHTLY]);
|
|
42
|
-
static isValid(value: string): boolean {
|
|
43
|
-
return this.SCHEME_SET.has(value);
|
|
44
|
-
}
|
|
45
23
|
}
|
|
46
24
|
|
|
47
25
|
export class ExitCodes {
|
|
@@ -18,7 +18,7 @@ export interface ILayout {
|
|
|
18
18
|
class LayoutFolderLimits {
|
|
19
19
|
/** `auroras/apps` is two segments. */
|
|
20
20
|
static readonly MAX_SEGMENTS = 4;
|
|
21
|
-
/** One segment
|
|
21
|
+
/** One segment of a layout folder: lower case letters, digits and hyphens, starting with a letter or digit. */
|
|
22
22
|
static readonly SEGMENT_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
|
|
23
23
|
static readonly FORBIDDEN_SEGMENTS = new Set(['node_modules']);
|
|
24
24
|
}
|
|
@@ -32,10 +32,6 @@ export class LayoutKeys {
|
|
|
32
32
|
/** The keys `add` can target and `guard-package` guards. */
|
|
33
33
|
static readonly MANAGED = [this.BACKEND, this.FRONTEND, this.SHARED] as const;
|
|
34
34
|
static readonly ALL = [...this.MANAGED, this.OTHER] as const;
|
|
35
|
-
static readonly SCHEME_SET = new Set<string>(this.ALL);
|
|
36
|
-
static isValid(value: string): boolean {
|
|
37
|
-
return this.SCHEME_SET.has(value);
|
|
38
|
-
}
|
|
39
35
|
}
|
|
40
36
|
|
|
41
37
|
/** Whether `inner` is `outer` or sits below it. */
|
package/src/common/types.ts
CHANGED
|
@@ -1,11 +1,6 @@
|
|
|
1
|
-
import type { VulcanCommands, VulcanTools } from './constants.ts';
|
|
2
|
-
|
|
3
1
|
/** The values of a const class's static fields: `TConstValue<typeof Colors>` is `'red' | 'blue'`. */
|
|
4
2
|
export type TConstValue<TClass> = Extract<TClass[keyof TClass], string | number> & {};
|
|
5
3
|
|
|
6
|
-
export type TVulcanCommand = TConstValue<typeof VulcanCommands>;
|
|
7
|
-
export type TVulcanTool = TConstValue<typeof VulcanTools>;
|
|
8
|
-
|
|
9
4
|
/** Where `vulcan x` finds a tool: the npm package and the bin it declares. */
|
|
10
5
|
export interface IToolPackage {
|
|
11
6
|
packageName: string;
|
|
@@ -2,12 +2,6 @@
|
|
|
2
2
|
export class PackageKinds {
|
|
3
3
|
static readonly APP = 'app';
|
|
4
4
|
static readonly LIB = 'lib';
|
|
5
|
-
|
|
6
|
-
static readonly SCHEME_SET = new Set<string>([this.APP, this.LIB]);
|
|
7
|
-
|
|
8
|
-
static isValid(value: string): boolean {
|
|
9
|
-
return this.SCHEME_SET.has(value);
|
|
10
|
-
}
|
|
11
5
|
}
|
|
12
6
|
|
|
13
7
|
/** Which preset kind made a library: `lib` (may use the project's framework) or `shared` (depends on no framework). */
|
|
@@ -22,22 +16,6 @@ export class LibraryKinds {
|
|
|
22
16
|
}
|
|
23
17
|
}
|
|
24
18
|
|
|
25
|
-
/** Config file extensions, in lookup order. */
|
|
26
|
-
export class ConfigExtensions {
|
|
27
|
-
static readonly TS = 'ts';
|
|
28
|
-
static readonly MTS = 'mts';
|
|
29
|
-
static readonly MJS = 'mjs';
|
|
30
|
-
static readonly JS = 'js';
|
|
31
|
-
|
|
32
|
-
static readonly LOOKUP_ORDER = [this.TS, this.MTS, this.MJS, this.JS] as const;
|
|
33
|
-
|
|
34
|
-
static readonly SCHEME_SET = new Set<string>(this.LOOKUP_ORDER);
|
|
35
|
-
|
|
36
|
-
static isValid(value: string): boolean {
|
|
37
|
-
return this.SCHEME_SET.has(value);
|
|
38
|
-
}
|
|
39
|
-
}
|
|
40
|
-
|
|
41
19
|
/** The agents `vulcan sync` writes adapters for. */
|
|
42
20
|
export class CodingAgents {
|
|
43
21
|
static readonly CLAUDE = 'claude';
|
|
@@ -82,7 +60,8 @@ export class HookEvents {
|
|
|
82
60
|
|
|
83
61
|
export class ConfigConstants {
|
|
84
62
|
static readonly DIRECTORY = '.configs';
|
|
85
|
-
|
|
63
|
+
/** The one config file name, under `.configs/`. */
|
|
64
|
+
static readonly FILE = 'vulcan.config.mts';
|
|
86
65
|
static readonly DEFAULT_KNOWLEDGE_BUNDLE = '.agents/knowledge';
|
|
87
66
|
static readonly RULE_ID_PATTERN = /^(?:[A-Z]+-)?[A-Z]-\d{2}$/;
|
|
88
67
|
/** The rules a session drops most, printed at every session start unless the project lists its own. */
|
|
@@ -1,14 +1,5 @@
|
|
|
1
1
|
import type { TConstValue } from '../../common/index.ts';
|
|
2
|
-
import type {
|
|
3
|
-
CodingAgents,
|
|
4
|
-
ConfigExtensions,
|
|
5
|
-
HookEvents,
|
|
6
|
-
LibraryKinds,
|
|
7
|
-
PackageKinds,
|
|
8
|
-
} from './constants.ts';
|
|
2
|
+
import type { LibraryKinds, PackageKinds } from './constants.ts';
|
|
9
3
|
|
|
10
|
-
export type TConfigExtension = TConstValue<typeof ConfigExtensions>;
|
|
11
|
-
export type TCodingAgent = TConstValue<typeof CodingAgents>;
|
|
12
|
-
export type THookEvent = TConstValue<typeof HookEvents>;
|
|
13
4
|
export type TPackageKind = TConstValue<typeof PackageKinds>;
|
|
14
5
|
export type TLibraryKind = TConstValue<typeof LibraryKinds>;
|
package/src/config/loader.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { existsSync } from 'node:fs';
|
|
2
2
|
import { join, relative } from 'node:path';
|
|
3
3
|
import { pathToFileURL } from 'node:url';
|
|
4
|
-
import { ConfigConstants
|
|
4
|
+
import { ConfigConstants } from './common/index.ts';
|
|
5
5
|
import { VULCAN_CONFIG_SCHEMA } from './schema.ts';
|
|
6
6
|
import type { TResolvedConfig } from './schema.ts';
|
|
7
7
|
|
|
@@ -13,30 +13,29 @@ const describeError = (opts: { error: unknown }): string =>
|
|
|
13
13
|
opts.error instanceof Error ? opts.error.message : String(opts.error);
|
|
14
14
|
|
|
15
15
|
export class ConfigLoader {
|
|
16
|
-
/**
|
|
17
|
-
static
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
16
|
+
/** `.configs/vulcan.config.mts` when the project has one. */
|
|
17
|
+
static findFile(opts: { root: string }): string | undefined {
|
|
18
|
+
const file = join(opts.root, ConfigConstants.DIRECTORY, ConfigConstants.FILE);
|
|
19
|
+
|
|
20
|
+
return existsSync(file) ? file : undefined;
|
|
21
21
|
}
|
|
22
22
|
|
|
23
23
|
static async load(opts: { root: string }): Promise<TLoadResult> {
|
|
24
|
-
const
|
|
24
|
+
const file = ConfigLoader.findFile({ root: opts.root });
|
|
25
|
+
|
|
26
|
+
if (file === undefined) {
|
|
27
|
+
const other = ['ts', 'mjs', 'js']
|
|
28
|
+
.map((extension) => `vulcan.config.${extension}`)
|
|
29
|
+
.find((name) => existsSync(join(opts.root, ConfigConstants.DIRECTORY, name)));
|
|
30
|
+
const hint =
|
|
31
|
+
other === undefined ? '' : ` (${other} is not read: rename it to ${ConfigConstants.FILE})`;
|
|
25
32
|
|
|
26
|
-
if (files.length === 0) {
|
|
27
33
|
return {
|
|
28
34
|
ok: false,
|
|
29
|
-
error: `no ${ConfigConstants.DIRECTORY}/${ConfigConstants.
|
|
35
|
+
error: `no ${ConfigConstants.DIRECTORY}/${ConfigConstants.FILE} found in ${opts.root}${hint}`,
|
|
30
36
|
};
|
|
31
37
|
}
|
|
32
38
|
|
|
33
|
-
if (files.length > 1) {
|
|
34
|
-
const names = files.map((file) => relative(opts.root, file)).join(', ');
|
|
35
|
-
|
|
36
|
-
return { ok: false, error: `more than one config - keep exactly one of: ${names}` };
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
const [file] = files;
|
|
40
39
|
const shown = relative(opts.root, file);
|
|
41
40
|
|
|
42
41
|
let loaded: { default?: unknown };
|
package/src/config/schema.ts
CHANGED
|
@@ -97,9 +97,22 @@ const TRUSTED_SCRIPT = z.union([
|
|
|
97
97
|
/** One folder, or a list of them: a side whose apps are grouped keeps each group's folder. */
|
|
98
98
|
const LAYOUT_VALUE = z.union([LAYOUT_FOLDER, z.array(LAYOUT_FOLDER).min(1)]);
|
|
99
99
|
|
|
100
|
+
/** An npm package name, lower case: the pattern and the length atlas applies to every package name of the manifest. */
|
|
101
|
+
const NPM_NAME_PATTERN = /^(?:@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*$/;
|
|
102
|
+
const NPM_NAME_MAX_LENGTH = 214;
|
|
103
|
+
|
|
104
|
+
const NPM_PACKAGE_NAME = z.string().superRefine((value, context) => {
|
|
105
|
+
if (value.length > NPM_NAME_MAX_LENGTH || !NPM_NAME_PATTERN.test(value)) {
|
|
106
|
+
context.addIssue({
|
|
107
|
+
code: 'custom',
|
|
108
|
+
message: `package name '${value}' is not an npm package name: npm names are lower case (a to z, digits, . _ ~ -) with an optional @scope/, at most ${NPM_NAME_MAX_LENGTH} characters, and atlas refuses the manifest otherwise`,
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
});
|
|
112
|
+
|
|
100
113
|
const PROJECT_PACKAGE = z.strictObject({
|
|
101
114
|
dir: z.string().regex(/^[a-z0-9][a-z0-9.-]*$/),
|
|
102
|
-
name:
|
|
115
|
+
name: NPM_PACKAGE_NAME,
|
|
103
116
|
/** Where the package lives, from the root; default `packages/<dir>`. */
|
|
104
117
|
path: z.string().optional(),
|
|
105
118
|
aliases: z.array(z.string()).default([]),
|
|
@@ -151,24 +164,16 @@ const checkPackagesUnique = (
|
|
|
151
164
|
};
|
|
152
165
|
|
|
153
166
|
/**
|
|
154
|
-
* A release template: `<dir>`
|
|
167
|
+
* A release template: `<dir>` is the package DIRECTORY - the `packages` key,
|
|
155
168
|
* never the npm name (`packages/core-server` published as `@acme/server` tags `core-server-v1.2.0`); `<version>` is the
|
|
156
169
|
* version; `<issue>` an issue number. Every other character is literal. When matching a commit, a
|
|
157
170
|
* leading `[#<issue>] ` is optional and a trailing ` [<mode>]` is tolerated. A release train that
|
|
158
171
|
* tags once leaves `<dir>` out (`v<version>`).
|
|
159
172
|
*/
|
|
160
173
|
const RELEASE_TEMPLATE = z.string().refine((value) => value.includes('<version>'), {
|
|
161
|
-
message: 'a template with <version> (and <dir>
|
|
174
|
+
message: 'a template with <version> (and <dir> for per-package releases)',
|
|
162
175
|
});
|
|
163
176
|
|
|
164
|
-
/** A key the config once accepted and no tool ever read: still named, so the error says it is gone rather than "unrecognized". */
|
|
165
|
-
const removedAtlasKey = (opts: { key: string }) =>
|
|
166
|
-
z
|
|
167
|
-
.never({
|
|
168
|
-
error: `atlas.${opts.key} was removed - no tool reads it; delete it from the config`,
|
|
169
|
-
})
|
|
170
|
-
.optional();
|
|
171
|
-
|
|
172
177
|
/** A renderer by id: a built-in, or a project module (`module`); a bare string is the id alone. */
|
|
173
178
|
const OKF_RENDERER = z.union([
|
|
174
179
|
z.string().transform((id) => ({ id, options: {} })),
|
|
@@ -290,16 +295,6 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
|
|
|
290
295
|
}),
|
|
291
296
|
atlas: z
|
|
292
297
|
.strictObject({
|
|
293
|
-
/** Removed in 0.2.0-8; present only so the error can name `packages`. */
|
|
294
|
-
packages: z
|
|
295
|
-
.never({
|
|
296
|
-
error:
|
|
297
|
-
'atlas.packages was removed - move the list to the top-level packages: [{ dir, name }] (release order; dir is the old key, name the old value)',
|
|
298
|
-
})
|
|
299
|
-
.optional(),
|
|
300
|
-
releaseCommit: removedAtlasKey({ key: 'releaseCommit' }),
|
|
301
|
-
typescriptFrom: removedAtlasKey({ key: 'typescriptFrom' }),
|
|
302
|
-
legacyTagPrefixes: removedAtlasKey({ key: 'legacyTagPrefixes' }),
|
|
303
298
|
tagPattern: RELEASE_TEMPLATE.default('<dir>-v<version>'),
|
|
304
299
|
/**
|
|
305
300
|
* Templates of an earlier tag layout that are still releases: atlas and the changelog check read a tag
|