@venizia/vulcan 0.1.0-2 → 0.2.0-0

package/src/router.ts

@@ -1,9 +1,25 @@
 import { COMMAND_HANDLERS } from './commands/index.ts';
+import { runHelpCommand } from './commands/help.command.ts';
 import { ExitCodes, VulcanCommands } from './common/index.ts';
 
 const HELP_ALIASES = new Set(['--help', '-h']);
 const VERSION_ALIASES = new Set(['--version', '-v']);
 
+interface IAcceptedArgs {
+  flags: string[];
+  /** Flags that take the next argument as their value. */
+  values: string[];
+  positionals: number;
+}
+
+/** What each command takes; `x` hands everything to its tool, `help` and `version` take nothing. */
+const ACCEPTED_ARGS: Record<string, IAcceptedArgs> = {
+  [VulcanCommands.INIT]: { flags: [], values: ['--config'], positionals: 0 },
+  [VulcanCommands.SYNC]: { flags: ['--dry-run', '--prune'], values: [], positionals: 0 },
+  [VulcanCommands.DOCTOR]: { flags: [], values: [], positionals: 0 },
+  [VulcanCommands.UPGRADE]: { flags: [], values: [], positionals: 1 },
+};
+
 /** The command name an argv asks for: no argument or a help flag means help. */
 const resolveCommandName = (opts: { first: string | undefined }): string => {
   if (opts.first === undefined || HELP_ALIASES.has(opts.first)) {
@@ -13,6 +29,32 @@ const resolveCommandName = (opts: { first: string | undefined }): string => {
   return VERSION_ALIASES.has(opts.first) ? VulcanCommands.VERSION : opts.first;
 };
 
+/** The first argument `accepted` does not cover - a typo must never run the command as if unsaid. */
+const findUnknownArg = (opts: { args: string[]; accepted: IAcceptedArgs }): string | undefined => {
+  let positionals = 0;
+
+  for (let index = 0; index < opts.args.length; index++) {
+    const arg = opts.args[index];
+
+    if (opts.accepted.values.includes(arg)) {
+      index++;
+      continue;
+    }
+
+    if (opts.accepted.flags.includes(arg)) {
+      continue;
+    }
+
+    if (arg.startsWith('-') || positionals === opts.accepted.positionals) {
+      return arg;
+    }
+
+    positionals++;
+  }
+
+  return undefined;
+};
+
 export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<number> => {
   const [first, ...args] = opts.argv;
   const name = resolveCommandName({ first });
@@ -24,5 +66,23 @@ export const runVulcan = async (opts: { argv: string[]; cwd: string }): Promise<
     return ExitCodes.FAILURE;
   }
 
+  const accepted = ACCEPTED_ARGS[name];
+
+  if (accepted !== undefined) {
+    if (args.some(arg => HELP_ALIASES.has(arg))) {
+      return runHelpCommand();
+    }
+
+    const unknown = findUnknownArg({ args, accepted });
+
+    if (unknown !== undefined) {
+      process.stderr.write(
+        `vulcan ${name}: unknown argument '${unknown}' - run 'bun x vulcan help'\n`,
+      );
+
+      return ExitCodes.FAILURE;
+    }
+  }
+
   return handler({ args, cwd: opts.cwd });
 };

package/src/rules/base.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { BASE_DIRECTORY } from '../common/index.ts';
+import { extractRuleRows, parseRetiredRuleIds, parseRuleIds } from './parser.ts';
+
+const readBaseMarkdown = (): string => readFileSync(join(BASE_DIRECTORY, 'rules.md'), 'utf8');
+
+/** Each base rule's ID with its table row, verbatim. */
+export const readBaseRules = (): Record<string, string> =>
+  Object.fromEntries(
+    extractRuleRows({ markdown: readBaseMarkdown() }).map(row => {
+      const [id] = parseRuleIds({ markdown: row });
+
+      return [id, row];
+    }),
+  );
+
+export const readRetiredRuleIds = (): string[] =>
+  parseRetiredRuleIds({ markdown: readBaseMarkdown() });

package/src/rules/common/constants.ts

@@ -4,4 +4,7 @@ export class RuleConstants {
 
   /** `W-01` (a project's own) or `V-W-01` (namespaced). */
   static readonly ID_SOURCE = '(?:[A-Z]+-)?[A-Z]-\\d{2}';
+
+  /** `V-W-01`: an ID in the base namespace, defined in the base or pointing at it. */
+  static readonly BASE_ID_SOURCE = `${this.BASE_NAMESPACE}[A-Z]-\\d{2}`;
 }

package/src/rules/index.ts

@@ -1,3 +1,4 @@
 export * from './common/index.ts';
+export * from './base.ts';
 export * from './parser.ts';
 export * from './slots.ts';

package/src/rules/parser.ts

@@ -12,3 +12,38 @@ export const parseRuleIds = (opts: { markdown: string }): string[] =>
 /** The table rows of every rule, verbatim, in order. */
 export const extractRuleRows = (opts: { markdown: string }): string[] =>
   opts.markdown.split('\n').filter(line => RULE_ROW.test(line));
+
+const BASE_ID = new RegExp(`(?<![A-Z-])${RuleConstants.BASE_ID_SOURCE}\\b`, 'g');
+const EXTENDS_LIST = new RegExp(
+  `\\bExtends\\s+${RuleConstants.BASE_ID_SOURCE}(?:(?:\\s*,\\s*|\\s+and\\s+)${RuleConstants.BASE_ID_SOURCE})*`,
+  'g',
+);
+const RETIRED_ITEM = new RegExp(`^- \`(${RuleConstants.BASE_ID_SOURCE})\` - `);
+
+/**
+ * The base IDs a project's rules point at, once each, in order: an `Extends V-X, V-Y and V-Z` list
+ * in a table row, and every `V-` ID in a row's first cell. A `V-` ID in prose or a later cell is not one.
+ */
+export const parseBaseReferences = (opts: { markdown: string }): string[] => {
+  const references = new Set<string>();
+
+  for (const line of opts.markdown.split('\n').filter(row => row.startsWith('|'))) {
+    const firstCell = line.split('|')[1] ?? '';
+    const lists = [...line.matchAll(EXTENDS_LIST)].map(match => match[0]);
+
+    for (const text of [...lists, firstCell]) {
+      for (const match of text.matchAll(BASE_ID)) {
+        references.add(match[0]);
+      }
+    }
+  }
+
+  return [...references];
+};
+
+/** The IDs the base retired, one `` - `V-X-NN` - why `` bullet each; they are never reused. */
+export const parseRetiredRuleIds = (opts: { markdown: string }): string[] =>
+  opts.markdown
+    .split('\n')
+    .map(line => RETIRED_ITEM.exec(line)?.[1])
+    .filter((id): id is string => id !== undefined);

package/src/sync/base-rules.ts

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildBaseRuleHashes, ManifestConstants } from '../manifest/index.ts';
+import { readBaseRules, readRetiredRuleIds } from '../rules/index.ts';
+import { BaseRuleChanges } from './common/index.ts';
+import type { IBaseRuleChange } from './common/index.ts';
+
+/** `| V-W-02 | Never write ... | HARD |` gives `Never write ... | HARD`. */
+const toRuleText = (opts: { row: string }): string =>
+  opts.row
+    .trim()
+    .replace(/^\|[^|]*\|\s*/, '')
+    .replace(/\s*\|$/, '');
+
+/** The hashes the committed manifest recorded; none before a first sync or when it is unreadable. */
+const readSyncedHashes = (opts: { root: string }): Record<string, unknown> => {
+  const file = join(opts.root, ManifestConstants.FILE);
+
+  if (!existsSync(file)) {
+    return {};
+  }
+
+  try {
+    const manifest: { rules?: { base?: Record<string, unknown> } } = JSON.parse(
+      readFileSync(file, 'utf8'),
+    );
+
+    return manifest.rules?.base ?? {};
+  } catch (error) {
+    console.error(
+      `[readSyncedHashes] ${file} | ${error instanceof Error ? error.message : String(error)}`,
+    );
+
+    return {};
+  }
+};
+
+/** V3: each base rule added, changed or removed since the committed manifest's last sync. */
+export const diffBaseRules = (opts: { root: string }): IBaseRuleChange[] => {
+  const synced = readSyncedHashes(opts);
+
+  if (Object.keys(synced).length === 0) {
+    return [];
+  }
+
+  const installed = buildBaseRuleHashes();
+  const rows = readBaseRules();
+  const retired = new Set(readRetiredRuleIds());
+  const changes: IBaseRuleChange[] = [];
+
+  for (const [id, hash] of Object.entries(installed)) {
+    if (synced[id] === hash) {
+      continue;
+    }
+
+    changes.push({
+      id,
+      change: synced[id] === undefined ? BaseRuleChanges.ADDED : BaseRuleChanges.CHANGED,
+      text: toRuleText({ row: rows[id] }),
+    });
+  }
+
+  for (const id of Object.keys(synced).filter(syncedId => installed[syncedId] === undefined)) {
+    changes.push({
+      id,
+      change: BaseRuleChanges.REMOVED,
+      text: retired.has(id) ? '(retired)' : '',
+    });
+  }
+
+  return changes;
+};

package/src/sync/common/constants.ts

@@ -3,11 +3,14 @@ export class SyncStatuses {
   static readonly REPLACED = 'replaced';
   static readonly UNCHANGED = 'unchanged';
   static readonly SKIPPED = 'skipped';
+  /** Taken out by `sync --prune`. */
+  static readonly REMOVED = 'removed';
   static readonly SCHEME_SET = new Set<string>([
     this.CREATED,
     this.REPLACED,
     this.UNCHANGED,
     this.SKIPPED,
+    this.REMOVED,
   ]);
   static isValid(value: string): boolean {
     return this.SCHEME_SET.has(value);
@@ -26,3 +29,14 @@ export class SyncConstants {
   /** 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']);
 }
+
+/** How a base rule moved between the manifest's last sync and the installed base. */
+export class BaseRuleChanges {
+  static readonly ADDED = 'added';
+  static readonly CHANGED = 'changed';
+  static readonly REMOVED = 'removed';
+  static readonly SCHEME_SET = new Set<string>([this.ADDED, this.CHANGED, this.REMOVED]);
+  static isValid(value: string): boolean {
+    return this.SCHEME_SET.has(value);
+  }
+}

package/src/sync/common/types.ts

@@ -1,5 +1,5 @@
 import type { TConstValue } from '../../common/index.ts';
-import type { SyncStatuses } from './constants.ts';
+import type { BaseRuleChanges, SyncStatuses } from './constants.ts';
 
 export type TSyncStatus = TConstValue<typeof SyncStatuses>;
 
@@ -12,3 +12,12 @@ export interface ISyncAction {
   note?: string;
   apply: () => void;
 }
+
+export type TBaseRuleChange = TConstValue<typeof BaseRuleChanges>;
+
+/** One base rule that moved since the last sync; `text` is its new text, or `(retired)` when the base retired it. */
+export interface IBaseRuleChange {
+  id: string;
+  change: TBaseRuleChange;
+  text: string;
+}

package/src/sync/index.ts

@@ -1,3 +1,5 @@
 export * from './common/index.ts';
+export * from './base-rules.ts';
 export * from './planner.ts';
+export * from './prune.ts';
 export * from './settings.ts';

package/src/sync/planner.ts

@@ -9,10 +9,11 @@ import {
   symlinkSync,
   writeFileSync,
 } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
-import { BASE_DIRECTORY } from '../common/index.ts';
+import { basename, dirname, join, resolve } from 'node:path';
+import { BASE_DIRECTORY, stableBaseDirectoryOf } from '../common/index.ts';
 import { CodingAgents } from '../config/index.ts';
 import type { TResolvedConfig } from '../config/index.ts';
+import { ManifestConstants, renderManifest } from '../manifest/index.ts';
 import { readSlots } from '../rules/index.ts';
 import { SyncConstants, SyncStatuses } from './common/index.ts';
 import type { ISyncAction, TSettings } from './common/index.ts';
@@ -161,9 +162,10 @@ 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);
+  const stableSkills = join(stableBaseDirectoryOf(opts), SyncConstants.SKILLS_DIRECTORY);
   const shipped = findSkillDirectories({
     directory: join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY),
-  });
+  }).map(source => join(stableSkills, basename(source)));
   const shippedNames = new Set(shipped.map(source => basename(source)));
   const project = findSkillDirectories({
     directory: join(opts.root, '.agents', SyncConstants.SKILLS_DIRECTORY),
@@ -213,12 +215,32 @@ const planSkillLinks = (opts: { root: string }): ISyncAction[] => {
   return [...links, ...shadowing];
 };
 
-/** Every adapter the project's agents need, planned, not written. */
-export const planSync = (opts: { root: string; config: TResolvedConfig }): ISyncAction[] =>
-  opts.config.agents.includes(CodingAgents.CLAUDE)
+/** The committed project manifest (Project Contract v1, C1), rendered from the config. */
+export const planManifest = (opts: { root: string; config: TResolvedConfig }): ISyncAction => {
+  const path = join(opts.root, ManifestConstants.FILE);
+  const text = renderManifest(opts);
+  const write = (): void => {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+  };
+
+  if (!existsSync(path)) {
+    return { path, status: SyncStatuses.CREATED, apply: write };
+  }
+
+  return readFileSync(path, 'utf8') === text
+    ? { path, status: SyncStatuses.UNCHANGED, apply: NO_CHANGE }
+    : { path, status: SyncStatuses.REPLACED, apply: write };
+};
+
+/** Every adapter the project's agents need, and the manifest every project carries - planned, not written. */
+export const planSync = (opts: { root: string; config: TResolvedConfig }): ISyncAction[] => [
+  ...(opts.config.agents.includes(CodingAgents.CLAUDE)
     ? [
         planClaudeImport({ root: opts.root }),
         planSettings(opts),
         ...planSkillLinks({ root: opts.root }),
       ]
-    : [];
+    : []),
+  planManifest(opts),
+];

package/src/sync/prune.ts

@@ -0,0 +1,132 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+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';
+
+/** The directory every shipped hook lives in; a command that runs one is VULCAN's. */
+const SHIPPED_HOOKS_PATH = '@venizia/vulcan/base/hooks/';
+
+/**
+ * A hook a project kept under its own `.agents/` - where plugin-era setups put theirs: the whole
+ * command is `bun` or `node` on that file, from the project root. Any other shape - another
+ * directory's `.agents/`, `$HOME`, a `cd` first - is a developer's own and never pruned.
+ */
+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'));
+  } catch (error) {
+    console.error(
+      `[readJson] ${opts.path} | ${error instanceof Error ? error.message : String(error)}`,
+    );
+
+    return 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.
+ */
+const isStaleCommand = (opts: { root: string; command: string; shipped: Set<string> }): boolean => {
+  if (opts.command.includes(SHIPPED_HOOKS_PATH)) {
+    return !opts.shipped.has(opts.command);
+  }
+
+  const agentsHook = AGENTS_HOOK.exec(opts.command)?.[1];
+
+  return agentsHook !== undefined && !existsSync(join(opts.root, agentsHook));
+};
+
+/** 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;
+
+  if (settings === undefined) {
+    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);
+
+    if (kept.length > 0) {
+      hooks[event] = kept;
+    } else {
+      delete hooks[event];
+    }
+  }
+
+  writeFileSync(opts.path, `${JSON.stringify(settings, null, 2)}\n`);
+};
+
+const isDeadLink = (opts: { path: string }): boolean => {
+  try {
+    return lstatSync(opts.path).isSymbolicLink() && !existsSync(opts.path);
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * `sync --prune`: what sync can prove is stale and did not write itself - old VULCAN and plugin-era
+ * hook commands, and skill links whose target is gone. What sync wrote last time it takes back on
+ * every run; a developer's own hooks and any real directory are never touched.
+ */
+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) }) }),
+  );
+  const shipped = new Set(
+    commandsOf({
+      settings: readJson({ path: join(BASE_DIRECTORY, 'claude', SyncConstants.SETTINGS_FILE) }),
+    }),
+  );
+  const staleCommands = [
+    ...new Set(commandsOf({ 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)
+    ? readdirSync(skills)
+        .map(name => join(skills, name))
+        .filter(path => isDeadLink({ path }))
+    : [];
+
+  return [
+    ...staleCommands.map((command): ISyncAction => ({
+      path: settingsPath,
+      status: SyncStatuses.REMOVED,
+      note: `stale hook: ${command}`,
+      apply: () => removeHookCommand({ path: settingsPath, command }),
+    })),
+    ...deadLinks.map((path): ISyncAction => ({
+      path,
+      status: SyncStatuses.REMOVED,
+      note: 'dead link',
+      apply: () => rmSync(path),
+    })),
+  ];
+};