@venizia/vulcan 0.2.0-0 → 0.2.0-1

package/README.md

@@ -17,10 +17,10 @@ flag `bun x` fetches it when `@venizia/vulcan` is not installed yet.
 | Command | What it does |
 |---|---|
 | `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 `-include`. Never overwrites; prints what to add to existing files, and the atlas `.mcp.json` entry for projects with a wiki |
-| `sync [--dry-run] [--prune]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`), `.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), `.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 in an old form, or a `.agents/` hook whose file is gone) and a dead `.claude/skills` link - never a developer's own hook or a real directory. Idempotent |
+| `sync [--dry-run] [--prune]` | Write the gitignored agent adapters: `CLAUDE.md` (`@AGENTS.md`), `.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 |
 | `doctor` | Check the project follows VULCAN; exit 1 on any violation |
 | `upgrade [<version\|tag>]` | Install the target `@venizia/vulcan` (default: the `next` dist-tag), then run `sync` from the newly installed CLI |
-| `x <tool> [args...]` | Run a shipped tool at the pinned version: `okf`, `atlas` |
+| `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 |
 | `help`, `version` | |
 
 Diagnostics go to stderr; `vulcan` writes nothing to stdout of its own, so `vulcan x atlas mcp` is a
@@ -63,7 +63,7 @@ or shadows a shipped one.
 shadowed) · `make` (includes `vulcan.mk`, no shipped target redefined) · `hooks` (shipped hooks are
 not re-registered) · `adapters` (sync is current, no hand-written `CLAUDE.md`, valid settings) ·
 `prune` (no stale hook command or dead skill link - `sync --prune` removes them) ·
-`style` (`@venizia/dev-configs` declared by the package holding the lint config or the root, every lint config builds on it).
+`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`).
 
 The session-start digest prints the base write boundaries, the slot choices, the project's own rules (bold `| **W-00** |` rows and `| V-W-02, V-W-03 |` rows that elaborate base rules), the project's `<!-- minimap-shape:start -->` ... `<!-- minimap-shape:end -->` block from `.agents/rules.md` verbatim, and the `digest.oftenDropped` rules.
 

package/base/claude/settings.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/session-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; echo \"vulcan: the session-start hook cannot run (node_modules/@venizia/vulcan or bun is missing) - run bun install\" >&2; exit 2"
+            "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/session-start.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; [ -f \"$f\" ] || echo \"vulcan: the session-start hook cannot run: node_modules/@venizia/vulcan is missing - run bun install\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the session-start hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
           }
         ]
       }
@@ -18,7 +18,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '\"command\" *: *\"bun (install|i)( --?[a-z][a-z0-9-]*(=[A-Za-z0-9._-]+)?)*\"'; then exit 0; fi; echo \"vulcan: the guard-writes hook cannot run (node_modules/@venizia/vulcan or bun is missing) - run bun install (the one command that passes until then)\" >&2; exit 2"
+            "command": "f=\"${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts\"; if [ -f \"$f\" ] && command -v bun >/dev/null 2>&1; then bun \"$f\"; s=$?; [ \"$s\" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '\"command\" *: *\"bun (install|i)( (--frozen-lockfile|--production|-p|--no-save|--ignore-scripts|--force|--verbose|--silent))*\"'; then exit 0; fi; [ -f \"$f\" ] || echo \"vulcan: the guard-writes hook cannot run: node_modules/@venizia/vulcan is missing - run bun install (the one command that passes until then)\" >&2; command -v bun >/dev/null 2>&1 || echo \"vulcan: the guard-writes hook cannot run: bun is not on PATH - put bun on PATH (Claude Code may have started without your shell's PATH)\" >&2; exit 2"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/vulcan",
-  "version": "0.2.0-0",
+  "version": "0.2.0-1",
   "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
   "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
   "repository": {
@@ -44,8 +44,8 @@
     "test": "NODE_ENV=test bun test --env-file=.env.test"
   },
   "dependencies": {
-    "@venizia/vulcan-atlas": "0.2.0-0",
-    "@venizia/vulcan-okf": "0.2.0-0",
+    "@venizia/vulcan-atlas": "0.2.0-1",
+    "@venizia/vulcan-okf": "0.2.0-1",
     "zod": "^4.5.4"
   },
   "devDependencies": {

package/src/commands/sync.command.ts

@@ -6,6 +6,15 @@ import { diffBaseRules, planPrune, planSync, SyncConstants, SyncStatuses } from
 
 const DRY_RUN_FLAG = '--dry-run';
 const PRUNE_FLAG = '--prune';
+const LABEL_WIDTH = 9;
+
+/** Under --dry-run nothing is written, so a write is labelled as what it would do. */
+const DRY_RUN_LABELS: Record<string, string> = {
+  [SyncStatuses.CREATED]: 'would create',
+  [SyncStatuses.REPLACED]: 'would replace',
+  [SyncStatuses.REMOVED]: 'would remove',
+};
+const DRY_RUN_LABEL_WIDTH = Math.max(...Object.values(DRY_RUN_LABELS).map(label => label.length));
 
 export const runSyncCommand = async (opts: ICommandContext): Promise<number> => {
   const loaded = await loadConfig({ root: opts.cwd });
@@ -22,6 +31,7 @@ export const runSyncCommand = async (opts: ICommandContext): Promise<number> =>
   const actions = [...planSync({ root: opts.cwd, config: loaded.config }), ...pruned];
   // Read before the manifest action rewrites the hashes it compares against.
   const changes = diffBaseRules({ root: opts.cwd });
+  const width = dryRun ? DRY_RUN_LABEL_WIDTH : LABEL_WIDTH;
 
   for (const action of actions) {
     if (!dryRun) {
@@ -29,14 +39,13 @@ export const runSyncCommand = async (opts: ICommandContext): Promise<number> =>
     }
 
     const note = action.note === undefined ? '' : ` (${action.note})`;
+    const label = (dryRun ? DRY_RUN_LABELS[action.status] : undefined) ?? action.status;
 
-    process.stderr.write(
-      `  ${action.status.padEnd(9)} ${relative(opts.cwd, action.path)}${note}\n`,
-    );
+    process.stderr.write(`  ${label.padEnd(width)} ${relative(opts.cwd, action.path)}${note}\n`);
   }
 
   for (const { id, change, text } of changes) {
-    process.stderr.write(`  ${change.padEnd(9)} ${[id, text].filter(Boolean).join(' ')}\n`);
+    process.stderr.write(`  ${change.padEnd(width)} ${[id, text].filter(Boolean).join(' ')}\n`);
   }
 
   const settingsBroken = actions.some(

package/src/doctor/checks.ts

@@ -2,6 +2,7 @@ import { Glob } from 'bun';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { BASE_DIRECTORY, ProjectLayout } from '../common/index.ts';
+import { resolvePackages } from '../config/index.ts';
 import type { TResolvedConfig } from '../config/index.ts';
 import {
   parseBaseReferences,
@@ -271,15 +272,20 @@ const hasStylePackage = (opts: { directory: string }): boolean => {
 /**
  * D9: the shared coding style - every lint config builds on it, and the package whose `.configs/`
  * holds the config declares it, or the root does. A project with no lint config declares it at the
- * root.
+ * root. Owners are `packages/*` and every configured package's `path`, such as `umbras/kit`.
  */
 export const checkStyle = (opts: ICheckContext): IViolation[] => {
   const violations: IViolation[] = [];
   const owners = [
-    '.',
-    ...listDirectories({ directory: join(opts.root, 'packages') }).map(name =>
-      join('packages', name),
-    ),
+    ...new Set([
+      '.',
+      ...listDirectories({ directory: join(opts.root, 'packages') }).map(name =>
+        join('packages', name),
+      ),
+      ...resolvePackages({ config: opts.config }).map(
+        entry => relative(opts.root, join(opts.root, entry.path)) || '.',
+      ),
+    ]),
   ];
   const isRootDeclared = hasStylePackage({ directory: opts.root });
   let lintConfigs = 0;

package/src/router.ts

@@ -66,6 +66,11 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
     return ExitCodes.FAILURE;
   }
 
+  // `x` hands its arguments to the tool, so only a help flag in the tool's place is vulcan's.
+  if (name === VulcanCommands.X && HELP_ALIASES.has(args[0] ?? '')) {
+    return runHelpCommand();
+  }
+
   const accepted = ACCEPTED_ARGS[name];
 
   if (accepted !== undefined) {

package/src/sync/common/constants.ts

@@ -26,6 +26,8 @@ export class SyncConstants {
   static readonly MANAGED_FILE = 'vulcan-managed.json';
   static readonly SKILLS_DIRECTORY = 'skills';
   static readonly SKILL_FILE = 'SKILL.md';
+  /** The settings key of hook entries: sync takes a managed hook back by its command, not its whole entry. */
+  static readonly HOOKS_KEY = 'hooks';
   /** Objects of independent entries: merged one level deep, so personal entries survive shared ones. */
   static readonly MERGE_ONE_LEVEL = new Set(['permissions', 'hooks', 'enabledPlugins', 'env']);
 }

package/src/sync/planner.ts

@@ -162,6 +162,19 @@ const findSkillDirectories = (opts: { directory: string }): string[] =>
 /** Shipped and project skills, linked flat into `.claude/skills/<name>`; a real directory there is left alone. */
 const planSkillLinks = (opts: { root: string }): ISyncAction[] => {
   const target = join(opts.root, SyncConstants.CLAUDE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY);
+
+  // A symlinked skills directory points outside the project: writing links through it would land them there.
+  if (isSymlink({ path: target })) {
+    return [
+      {
+        path: target,
+        status: SyncStatuses.SKIPPED,
+        note: 'a symlink - left untouched',
+        apply: NO_CHANGE,
+      },
+    ];
+  }
+
   const stableSkills = join(stableBaseDirectoryOf(opts), SyncConstants.SKILLS_DIRECTORY);
   const shipped = findSkillDirectories({
     directory: join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY),

package/src/sync/prune.ts

@@ -3,9 +3,18 @@ import { join } from 'node:path';
 import { BASE_DIRECTORY } from '../common/index.ts';
 import { SyncConstants, SyncStatuses } from './common/index.ts';
 import type { ISyncAction, TSettings } from './common/index.ts';
+import { extractHookCommands, isSettingsObject, removeHookCommands } from './settings.ts';
 
-/** The directory every shipped hook lives in; a command that runs one is VULCAN's. */
-const SHIPPED_HOOKS_PATH = '@venizia/vulcan/base/hooks/';
+/**
+ * The exact hook commands released VULCAN versions shipped (0.1.0-x, then 0.2.0-0). Only these are
+ * an old VULCAN form: a shipped hook a developer customised is theirs, and never pruned.
+ */
+const RETIRED_SHIPPED_COMMANDS = new Set([
+  `bun "\${CLAUDE_PROJECT_DIR}"/node_modules/@venizia/vulcan/base/hooks/session-start.ts`,
+  `bun "\${CLAUDE_PROJECT_DIR}"/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts`,
+  `f="\${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/session-start.ts"; if [ -f "$f" ] && command -v bun >/dev/null 2>&1; then bun "$f"; s=$?; [ "$s" -eq 0 ] && exit 0; exit 2; fi; echo "vulcan: the session-start hook cannot run (node_modules/@venizia/vulcan or bun is missing) - run bun install" >&2; exit 2`,
+  `f="\${CLAUDE_PROJECT_DIR}/node_modules/@venizia/vulcan/base/hooks/guard-writes.ts"; if [ -f "$f" ] && command -v bun >/dev/null 2>&1; then bun "$f"; s=$?; [ "$s" -eq 0 ] && exit 0; exit 2; fi; if grep -Eq '"command" *: *"bun (install|i)( --?[a-z][a-z0-9-]*(=[A-Za-z0-9._-]+)?)*"'; then exit 0; fi; echo "vulcan: the guard-writes hook cannot run (node_modules/@venizia/vulcan or bun is missing) - run bun install (the one command that passes until then)" >&2; exit 2`,
+]);
 
 /**
  * A hook a project kept under its own `.agents/` - where plugin-era setups put theirs: the whole
@@ -15,15 +24,15 @@ const SHIPPED_HOOKS_PATH = '@venizia/vulcan/base/hooks/';
 const AGENTS_HOOK =
   /^(?:bun|node)\s+(?:"?\$\{?CLAUDE_PROJECT_DIR\}?"?\/)?(\.agents\/[\w./-]+\.ts)\s*$/;
 
-type THookEntries = Record<string, { hooks?: { command?: string }[] }[]>;
-
 const readJson = (opts: { path: string }): TSettings | undefined => {
   if (!existsSync(opts.path)) {
     return undefined;
   }
 
   try {
-    return JSON.parse(readFileSync(opts.path, 'utf8'));
+    const parsed = { value: JSON.parse(readFileSync(opts.path, 'utf8')) };
+
+    return isSettingsObject(parsed) ? parsed.value : undefined;
   } catch (error) {
     console.error(
       `[readJson] ${opts.path} | ${error instanceof Error ? error.message : String(error)}`,
@@ -33,17 +42,12 @@ const readJson = (opts: { path: string }): TSettings | undefined => {
   }
 };
 
-const commandsOf = (opts: { settings: TSettings | undefined }): string[] =>
-  Object.values((opts.settings?.hooks ?? {}) as THookEntries).flatMap(entries =>
-    entries.flatMap(entry => (entry.hooks ?? []).flatMap(hook => hook.command ?? [])),
-  );
-
 /**
- * A command sync did not write that is known to be stale: a shipped hook in a form this VULCAN no
- * longer writes, or a `.agents/` hook whose file is gone. Any other command is a developer's own.
+ * A command sync did not write that is known to be stale: a shipped hook exactly as an older VULCAN
+ * released it, or a `.agents/` hook whose file is gone. Any other command is a developer's own.
  */
 const isStaleCommand = (opts: { root: string; command: string; shipped: Set<string> }): boolean => {
-  if (opts.command.includes(SHIPPED_HOOKS_PATH)) {
+  if (RETIRED_SHIPPED_COMMANDS.has(opts.command)) {
     return !opts.shipped.has(opts.command);
   }
 
@@ -55,24 +59,23 @@ const isStaleCommand = (opts: { root: string; command: string; shipped: Set<stri
 /** Takes one command out of the settings file; an entry or an event left empty goes with it. */
 const removeHookCommand = (opts: { path: string; command: string }): void => {
   const settings = readJson({ path: opts.path });
-  const hooks = (settings?.hooks ?? {}) as THookEntries;
+  const hooks = { value: settings?.[SyncConstants.HOOKS_KEY] };
 
-  if (settings === undefined) {
+  if (settings === undefined || !isSettingsObject(hooks)) {
     return;
   }
 
-  for (const [event, entries] of Object.entries(hooks)) {
-    const kept = entries
-      .map(entry => ({
-        ...entry,
-        hooks: (entry.hooks ?? []).filter(hook => hook.command !== opts.command),
-      }))
-      .filter(entry => entry.hooks.length > 0);
+  for (const [event, entries] of Object.entries(hooks.value)) {
+    if (!Array.isArray(entries)) {
+      continue;
+    }
+
+    const kept = removeHookCommands({ entries, commands: new Set([opts.command]) });
 
     if (kept.length > 0) {
-      hooks[event] = kept;
+      hooks.value[event] = kept;
     } else {
-      delete hooks[event];
+      delete hooks.value[event];
     }
   }
 
@@ -96,20 +99,23 @@ export const planPrune = (opts: { root: string }): ISyncAction[] => {
   const directory = join(opts.root, SyncConstants.CLAUDE_DIRECTORY);
   const settingsPath = join(directory, SyncConstants.SETTINGS_FILE);
   const managed = new Set(
-    commandsOf({ settings: readJson({ path: join(directory, SyncConstants.MANAGED_FILE) }) }),
+    extractHookCommands({
+      settings: readJson({ path: join(directory, SyncConstants.MANAGED_FILE) }),
+    }),
   );
   const shipped = new Set(
-    commandsOf({
+    extractHookCommands({
       settings: readJson({ path: join(BASE_DIRECTORY, 'claude', SyncConstants.SETTINGS_FILE) }),
     }),
   );
   const staleCommands = [
-    ...new Set(commandsOf({ settings: readJson({ path: settingsPath }) })),
+    ...new Set(extractHookCommands({ settings: readJson({ path: settingsPath }) })),
   ].filter(
     command => !managed.has(command) && isStaleCommand({ root: opts.root, command, shipped }),
   );
   const skills = join(directory, SyncConstants.SKILLS_DIRECTORY);
-  const deadLinks = existsSync(skills)
+  // lstat, not stat: a symlinked skills directory leads out of the project and is never walked.
+  const deadLinks = lstatSync(skills, { throwIfNoEntry: false })?.isDirectory()
     ? readdirSync(skills)
         .map(name => join(skills, name))
         .filter(path => isDeadLink({ path }))

package/src/sync/settings.ts

@@ -48,6 +48,71 @@ export const mergeSettings = (opts: { base: TSettings; overlay: TSettings }): TS
 
 const toKey = (opts: { value: unknown }): string => JSON.stringify(opts.value);
 
+/** The command of a hook; `undefined` when `hook` is not an object with a command string. */
+const toHookCommand = (opts: { hook: unknown }): string | undefined => {
+  const hook = { value: opts.hook };
+
+  return isSettingsObject(hook) && typeof hook.value.command === 'string'
+    ? hook.value.command
+    : undefined;
+};
+
+/** A hook entry and its hooks; `undefined` when `entry` is not an object with a `hooks` array. */
+const toHookEntry = (opts: {
+  entry: unknown;
+}): { entry: TSettings; hooks: unknown[] } | undefined => {
+  const entry = { value: opts.entry };
+
+  return isSettingsObject(entry) && Array.isArray(entry.value.hooks)
+    ? { entry: entry.value, hooks: entry.value.hooks }
+    : undefined;
+};
+
+/** Every hook command in one event's entries; anything that is not an entry or a command is skipped. */
+export const extractEntryCommands = (opts: { entries: unknown }): string[] =>
+  Array.isArray(opts.entries)
+    ? opts.entries.flatMap(entry =>
+        (toHookEntry({ entry })?.hooks ?? []).flatMap(hook => toHookCommand({ hook }) ?? []),
+      )
+    : [];
+
+/** Every hook command of a settings file, across its events. */
+export const extractHookCommands = (opts: { settings: TSettings | undefined }): string[] => {
+  const hooks = { value: opts.settings?.[SyncConstants.HOOKS_KEY] };
+
+  return isSettingsObject(hooks)
+    ? Object.values(hooks.value).flatMap(entries => extractEntryCommands({ entries }))
+    : [];
+};
+
+/**
+ * `entries` without the hooks whose command is in `commands`: an entry's other hooks and keys stay,
+ * an entry left with no hooks goes, and anything that is not an entry is kept as it is.
+ */
+export const removeHookCommands = (opts: {
+  entries: unknown[];
+  commands: Set<string>;
+}): unknown[] =>
+  opts.entries.flatMap(entry => {
+    const hookEntry = toHookEntry({ entry });
+
+    if (hookEntry === undefined) {
+      return [entry];
+    }
+
+    const kept = hookEntry.hooks.filter(hook => {
+      const command = toHookCommand({ hook });
+
+      return command === undefined || !opts.commands.has(command);
+    });
+
+    if (kept.length === hookEntry.hooks.length) {
+      return [entry];
+    }
+
+    return kept.length > 0 ? [{ ...hookEntry.entry, hooks: kept }] : [];
+  });
+
 /** `settings` with its keys in `reference`'s order: keys `reference` has keep their place, new keys follow. */
 const orderKeysLike = (opts: { settings: TSettings; reference: TSettings }): TSettings => {
   const keys = [
@@ -109,7 +174,15 @@ export const removeManagedSettings = (opts: {
 
       if (Array.isArray(innerCurrent) && Array.isArray(innerManaged)) {
         const managedKeys = new Set(innerManaged.map(entry => toKey({ value: entry })));
-        const kept = innerCurrent.filter(entry => !managedKeys.has(toKey({ value: entry })));
+        const unmatched = innerCurrent.filter(entry => !managedKeys.has(toKey({ value: entry })));
+        // A hand-edited entry no longer matches whole: its managed hooks still go, by command.
+        const kept =
+          key === SyncConstants.HOOKS_KEY
+            ? removeHookCommands({
+                entries: unmatched,
+                commands: new Set(extractEntryCommands({ entries: innerManaged })),
+              })
+            : unmatched;
 
         if (kept.length > 0) {
           inner[innerKey] = kept;