@venizia/vulcan 0.2.0-2 → 0.2.0-3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/vulcan",
-  "version": "0.2.0-2",
+  "version": "0.2.0-3",
   "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-2",
-    "@venizia/vulcan-okf": "0.2.0-2",
+    "@venizia/vulcan-atlas": "0.2.0-3",
+    "@venizia/vulcan-okf": "0.2.0-3",
     "zod": "^4.5.4"
   },
   "devDependencies": {

package/src/doctor/skills.ts

@@ -33,13 +33,46 @@ const filesOf = (opts: { directory: string }): string[] =>
 const lineCountOf = (opts: { text: string }): number =>
   opts.text.replace(/\n$/, '').split('\n').length;
 
-const frontmatterOf = (opts: { text: string }): Record<string, unknown> => {
+const parseYaml = (opts: { text: string }): { value?: unknown; error?: string } => {
+  try {
+    return { value: Bun.YAML.parse(opts.text) };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+};
+
+/**
+ * The frontmatter's fields, or why they cannot be read. Bun's YAML error names no line, so the line
+ * is the first one at which the block stops parsing - counted in the file, the opening `---` is 1.
+ */
+const frontmatterOf = (opts: {
+  text: string;
+}): { data: Record<string, unknown>; error?: string } => {
   const block = FRONTMATTER.exec(opts.text)?.[1];
-  const parsed: unknown = block === undefined ? undefined : Bun.YAML.parse(block);
 
-  return typeof parsed === 'object' && parsed !== null
-    ? Object.fromEntries(Object.entries(parsed))
-    : {};
+  if (block === undefined) {
+    return { data: {} };
+  }
+
+  const parsed = parseYaml({ text: block });
+
+  if (parsed.error !== undefined) {
+    const blockLines = block.split('\n');
+    const failsAt = blockLines.findIndex(
+      (_line, index) =>
+        parseYaml({ text: blockLines.slice(0, index + 1).join('\n') }).error !== undefined,
+    );
+    const where = failsAt === -1 ? '' : ` at line ${failsAt + 2}`;
+
+    return { data: {}, error: `the frontmatter is not valid YAML${where} (${parsed.error})` };
+  }
+
+  return {
+    data:
+      typeof parsed.value === 'object' && parsed.value !== null
+        ? Object.fromEntries(Object.entries(parsed.value))
+        : {},
+  };
 };
 
 /** Every rule one skill directory breaks, each a message naming the file. */
@@ -53,19 +86,23 @@ export const lintSkill = (opts: { directory: string }): string[] => {
   const problems: string[] = [];
   const text = readFileSync(skillFile, 'utf8');
   const frontmatter = frontmatterOf({ text });
-  const { name, description } = frontmatter;
+  const { name, description } = frontmatter.data;
 
-  if (typeof name !== 'string' || !NAME_PATTERN.test(name) || RESERVED_NAME.test(name)) {
+  // One file a project cannot parse is a finding about that file - the other checks still run.
+  if (frontmatter.error !== undefined) {
+    problems.push(`SKILL.md: ${frontmatter.error}`);
+  } else if (typeof name !== 'string' || !NAME_PATTERN.test(name) || RESERVED_NAME.test(name)) {
     problems.push(
       `SKILL.md: name '${String(name)}' - at most 64 characters of a-z, 0-9 and hyphens, never 'claude' or 'anthropic'`,
     );
   }
 
   if (
-    typeof description !== 'string' ||
-    description.trim().length === 0 ||
-    description.length > MAX_DESCRIPTION ||
-    XML_TAG.test(description)
+    frontmatter.error === undefined &&
+    (typeof description !== 'string' ||
+      description.trim().length === 0 ||
+      description.length > MAX_DESCRIPTION ||
+      XML_TAG.test(description))
   ) {
     problems.push('SKILL.md: the description must be 1-1024 characters with no XML tags');
   }

package/src/sync/planner.ts

@@ -225,7 +225,27 @@ const planSkillLinks = (opts: { root: string }): ISyncAction[] => {
       : { path, status: SyncStatuses.CREATED, apply: link };
   });
 
-  return [...links, ...shadowing];
+  // A link into the shipped skills whose skill this VULCAN no longer has (a downgrade, a retired
+  // skill) is sync's own and dead: taken back. Any other link or directory stays.
+  const shippedRoots = [stableSkills, join(BASE_DIRECTORY, SyncConstants.SKILLS_DIRECTORY)];
+  const linked = new Set(sources.map(source => basename(source)));
+  const stale = (existsSync(target) ? readdirSync(target) : [])
+    .filter(name => !linked.has(name))
+    .map(name => join(target, name))
+    .filter(
+      path =>
+        isSymlink({ path }) &&
+        !existsSync(path) &&
+        shippedRoots.some(root => readlinkSync(path).startsWith(`${root}/`)),
+    )
+    .map((path): ISyncAction => ({
+      path,
+      status: SyncStatuses.REMOVED,
+      note: 'a shipped skill this version no longer has',
+      apply: () => rmSync(path),
+    }));
+
+  return [...links, ...shadowing, ...stale];
 };
 
 /** The committed project manifest (Project Contract v1, C1), rendered from the config. */