hypomnema 1.3.4 → 1.4.0

package/scripts/lib/wikilink.mjs

@@ -0,0 +1,156 @@
+// Shared wikilink primitives — the ONE source of truth for vault traversal,
+// slug-form generation, and bare wikilink extraction.
+//
+// Consumed by:
+//   - scripts/lint.mjs        (slug map, page collection, link-target scan)
+//   - scripts/rename.mjs      (form index with collision detection, page scan)
+//   - scripts/graph.mjs       (slug index, page collection, link extraction)
+//   - scripts/crystallize.mjs (page collection, link extraction)
+//
+// IMPR-13 consolidation. Before this lib, each script carried its own copy of
+// collectPages + a slug-form deriver, drifting in subtle ways. The four
+// collectPages variants are NOT interchangeable — they differ deliberately in
+// traversal/security/output-shape policy (codex design review, CONCERN):
+//
+//   - rename uses lstat + skips symlinks   → a vault scan can never escape via a
+//     symlinked dir/file (security boundary).
+//   - lint skips `_`-prefixed DIRECTORIES  → pages/feedback/_drafts scaffolds
+//     stay out of the lint set, while `_`-prefixed FILES (e.g. _index.md) lint.
+//   - crystallize skips ANY `.`-prefixed entry (dir AND file).
+//   - graph/lint/rename skip only `.`-prefixed FILES.
+//   - graph/crystallize emit raw `rel`/`slug`; lint keeps OS-native `rel`
+//     (its own buildSlugMap POSIX-normalizes downstream); rename/graph
+//     POSIX-normalize the slug at scan time.
+//
+// So this lib exposes ONE walker core plus four NAMED PRESETS, not a pile of
+// boolean flags — each preset pins exactly one caller's historical behavior and
+// is fixed by a unit test. readdirSync order is preserved verbatim (NO sort):
+// graph's bare-first slug index is order-sensitive (first page wins a shared
+// bare form), so adding a sort would silently change resolution.
+//
+// Collision RESOLUTION is intentionally NOT shared: lint dedups into a Set
+// (membership), rename detects ambiguity to refuse unsafe auto-rewrites, graph
+// is first-wins. Each caller builds its own structure from slugForms(); only the
+// form GENERATION lives here.
+
+import { existsSync, readdirSync, statSync, lstatSync } from 'fs';
+import { join, relative, extname, basename } from 'path';
+import { isScanIgnored } from './hypo-ignore.mjs';
+
+// ── markdown page walker (shared core) ─────────────────────────────────────────
+// `policy` keys (all optional):
+//   lstat            — stat with lstatSync and skip symlinks (rename's security
+//                      boundary). Default: statSync, symlinks followed.
+//   skipDotEntry     — skip ANY entry (dir or file) whose name starts with `.`
+//                      BEFORE the ignore check (crystallize).
+//   skipUnderscoreDir— skip directories whose name starts with `_` (lint).
+//   skipDotFile      — among `.md` files, skip names starting with `.`.
+//   shape(full)      — build the per-page record pushed onto the accumulator.
+function walkMarkdown(dir, root, ignorePatterns, policy, acc) {
+  if (!existsSync(dir)) return acc;
+  for (const entry of readdirSync(dir)) {
+    if (policy.skipDotEntry && entry.startsWith('.')) continue;
+    const full = join(dir, entry);
+    if (isScanIgnored(full, root, ignorePatterns)) continue;
+    const st = policy.lstat ? lstatSync(full) : statSync(full);
+    if (policy.lstat && st.isSymbolicLink()) continue;
+    if (st.isDirectory()) {
+      if (policy.skipUnderscoreDir && entry.startsWith('_')) continue;
+      walkMarkdown(full, root, ignorePatterns, policy, acc);
+    } else if (extname(entry) === '.md' && !(policy.skipDotFile && entry.startsWith('.'))) {
+      acc.push(policy.shape(full));
+    }
+  }
+  return acc;
+}
+
+const posixSlug = (full, root) => relative(root, full).replace(/\.md$/, '').replace(/\\/g, '/');
+
+// lint: `_`-dir skip + `_`-file kept; OS-native `rel` (buildSlugMap normalizes).
+export function collectPagesLint(dir, root, ignorePatterns = []) {
+  return walkMarkdown(
+    dir,
+    root,
+    ignorePatterns,
+    {
+      skipDotFile: true,
+      skipUnderscoreDir: true,
+      shape: (full) => ({ path: full, rel: relative(root, full) }),
+    },
+    [],
+  );
+}
+
+// graph: POSIX slug + bare, no `rel`.
+export function collectPagesGraph(dir, root, ignorePatterns = []) {
+  return walkMarkdown(
+    dir,
+    root,
+    ignorePatterns,
+    {
+      skipDotFile: true,
+      shape: (full) => ({ path: full, slug: posixSlug(full, root), bare: basename(full, '.md') }),
+    },
+    [],
+  );
+}
+
+// rename: lstat + symlink skip (security); POSIX rel/slug/bare.
+export function collectPagesRename(dir, root, ignorePatterns = []) {
+  return walkMarkdown(
+    dir,
+    root,
+    ignorePatterns,
+    {
+      lstat: true,
+      skipDotFile: true,
+      shape: (full) => {
+        const rel = relative(root, full).replace(/\\/g, '/');
+        return { path: full, rel, slug: rel.replace(/\.md$/, ''), bare: basename(full, '.md') };
+      },
+    },
+    [],
+  );
+}
+
+// crystallize: skip ANY `.`-prefixed entry; OS-native `rel`.
+export function collectPagesCrystallize(dir, root, ignorePatterns = []) {
+  return walkMarkdown(
+    dir,
+    root,
+    ignorePatterns,
+    { skipDotEntry: true, shape: (full) => ({ path: full, rel: relative(root, full) }) },
+    [],
+  );
+}
+
+// ── slug-form generation ───────────────────────────────────────────────────────
+// From a POSIX no-extension slug (e.g. `pages/learnings/foo`), derive the three
+// link forms a [[wikilink]] may use:
+//   full   — the whole slug                       [[pages/learnings/foo]]
+//   bare   — the basename                         [[foo]]
+//   dirRel — slug minus the leading scan-dir seg  [[learnings/foo]]  (null if the
+//            slug has no `/`, i.e. nothing to drop)
+// Callers pick which forms to register and own their own collision policy. Do NOT
+// apply this to link-target-only slugs (lint's root-md/sources extraTargets,
+// rename's sources/*) — those resolve VERBATIM, with no derived alias, so a bare
+// form can't mask an unrelated broken link or block a safe rewrite.
+export function slugForms(slug) {
+  const slash = slug.indexOf('/');
+  return { full: slug, bare: basename(slug), dirRel: slash === -1 ? null : slug.slice(slash + 1) };
+}
+
+// ── bare wikilink extraction (graph/crystallize variant) ───────────────────────
+// Raw extraction: matches [[target]] / [[target|alias]] / [[target#anchor]]
+// anywhere, INCLUDING inside code fences (graph counts those as edges, and
+// crystallize counts them for unlinked-page detection — preserving that is
+// behavior-stable). lint uses a DIFFERENT extractor (strips code regions and
+// handles table-escaped `\|`); rename uses length-preserving masking. Neither
+// shares this one.
+export function extractWikilinks(content) {
+  const links = [];
+  for (const m of content.matchAll(/\[\[([^\]|#]+?)(?:[|#][^\]]*?)?\]\]/g)) {
+    links.push(m[1].trim());
+  }
+  return links;
+}

package/scripts/lint.mjs

@@ -17,13 +17,21 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
-import { join, relative, extname, basename } from 'path';
+import { join, extname, basename } from 'path';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
 import { SESSION_STATE_NEXT_HEADINGS } from '../hooks/hypo-shared.mjs';
 import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
-import { parseSchemaVocab, checkForbidden, parseSchemaPageDirs } from './lib/schema-vocab.mjs';
+import {
+  parseSchemaVocab,
+  checkForbidden,
+  parseSchemaPageDirs,
+  parseSchemaTypes,
+} from './lib/schema-vocab.mjs';
 import { findDesignHistoryStale } from './lib/design-history-stale.mjs';
 import { FEEDBACK_SCOPE_RE } from './lib/feedback-scope.mjs';
+import { FAILURE_TYPE_ENUM } from './lib/failure-type.mjs';
+import { collectPagesLint, slugForms } from './lib/wikilink.mjs';
+import { parseFrontmatter, SEQUENCE_ENTRY_RE } from './lib/frontmatter.mjs';
 
 // ── arg parsing ──────────────────────────────────────────────────────────────
 
@@ -41,19 +49,45 @@ function parseArgs(argv) {
 
 // ── frontmatter parser ────────────────────────────────────────────────────────
 
-function parseFrontmatter(content) {
-  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!m) return null;
-  const fm = {};
-  for (const line of m[1].split('\n')) {
+// ── W9: narrow invalid-YAML detector ───────────────────────────────────────────
+// NOT a full YAML parser (zero-dep policy). Catches only specific classes the
+// lenient line-scanner (parseFrontmatter, imported from lib) silently passes but
+// a real YAML parser (js-yaml, what Obsidian uses) rejects. Each class is
+// conservative — it may miss, but must NOT false-positive on valid YAML, so it
+// inspects only top-level (unindented) lines: indented lines may be block-scalar
+// content where ": "/tabs are legal, and reliably telling content from structure
+// needs a real parser. (A leading-tab class was considered and dropped for this
+// reason — it cannot distinguish `relations:\n\t- x` from a tabbed block-scalar
+// body without tracking block context.) Returns an array of reasons.
+function checkYamlInvalid(block) {
+  const reasons = [];
+  const seen = new Set();
+  for (const raw of block.split('\n')) {
+    const line = raw.replace(/\r$/, '');
+    if (!line.trim()) continue;
+    if (/^\s/.test(line) || SEQUENCE_ENTRY_RE.test(line)) continue; // top-level keys only
     const idx = line.indexOf(':');
     if (idx < 0) continue;
-    fm[line.slice(0, idx).trim()] = line
-      .slice(idx + 1)
-      .trim()
-      .replace(/^["']|["']$/g, '');
+    const key = line.slice(0, idx).trim();
+    if (!key) continue;
+    // duplicate top-level key (YAML rejects; line-scanner silently keeps one)
+    if (seen.has(key)) reasons.push(`duplicate key: "${key}"`);
+    else seen.add(key);
+    // colon-space inside an unquoted, non-flow plain scalar. A plain scalar may
+    // not contain ": " — js-yaml hard-errors or silently truncates. Skip quoted
+    // ("/') and flow ([/{) values where ": " is legal, and strip an inline
+    // " #" comment before scanning.
+    let val = line.slice(idx + 1).trim();
+    const c = val[0];
+    if (val && c !== '"' && c !== "'" && c !== '[' && c !== '{') {
+      const hash = val.indexOf(' #');
+      if (hash >= 0) val = val.slice(0, hash);
+      if (/:\s/.test(val)) {
+        reasons.push(`unquoted "${key}" value contains ": " (quote it): "${val.slice(0, 40)}"`);
+      }
+    }
   }
-  return fm;
+  return reasons;
 }
 
 function parseTagsField(rawValue) {
@@ -108,31 +142,14 @@ const TYPE_ENUM_FIELDS = {
     status: ['active', 'superseded', 'archived'],
     tier: ['L1', 'L2'],
     sensitivity: ['public', 'sanitized'],
+    // FEAT-1: optional failure taxonomy. The enum loop guards on `if (fm[field])`,
+    // so an omitted failure_type is never validated (optional, migration-safe).
+    failure_type: FAILURE_TYPE_ENUM,
   },
 };
 
 // ── page collector ────────────────────────────────────────────────────────────
 
-function collectPages(dir, root, pages = [], ignorePatterns = []) {
-  if (!existsSync(dir)) return pages;
-  for (const entry of readdirSync(dir)) {
-    const full = join(dir, entry);
-    if (isScanIgnored(full, root, ignorePatterns)) continue;
-    const st = statSync(full);
-    if (st.isDirectory()) {
-      // `_`-prefixed dirs (e.g. pages/feedback/_drafts) hold scaffolds / scratch
-      // not yet promoted to content — skip so incomplete frontmatter never errors
-      // (mirrors loadFeedbackPages in feedback-sync.mjs). `_`-prefixed *files*
-      // (e.g. _index.md) are still linted.
-      if (entry.startsWith('_')) continue;
-      collectPages(full, root, pages, ignorePatterns);
-    } else if (extname(entry) === '.md' && !entry.startsWith('.')) {
-      pages.push({ path: full, rel: relative(root, full) });
-    }
-  }
-  return pages;
-}
-
 // ── slug map ─────────────────────────────────────────────────────────────────
 
 // `extraTargets` are link-target-only slugs (root *.md, sources/*) that resolve
@@ -142,13 +159,14 @@ function buildSlugMap(pages, extraTargets = []) {
   const map = new Set();
   for (const { rel } of pages) {
     const noExt = rel.replace(/\.md$/, '').replace(/\\/g, '/');
-    map.add(noExt);
-    map.add(basename(rel, '.md'));
-    // Dir-relative alias: drop the leading scan-dir segment so the vault's
-    // convention link [[learnings/foo]] resolves to pages/learnings/foo.md.
-    // (A page directly under a scan dir has no extra segment to drop.)
-    const slash = noExt.indexOf('/');
-    if (slash !== -1) map.add(noExt.slice(slash + 1));
+    // full slug + bare basename + dir-relative alias (drop the leading scan-dir
+    // segment so the convention link [[learnings/foo]] resolves to
+    // pages/learnings/foo.md). slugForms returns dirRel=null when the slug has no
+    // `/` (a page directly under a scan dir has no extra segment to drop).
+    const { full, bare, dirRel } = slugForms(noExt);
+    map.add(full);
+    map.add(bare);
+    if (dirRel) map.add(dirRel);
   }
   for (const t of extraTargets) map.add(t);
   return map;
@@ -165,7 +183,7 @@ function collectLinkTargets(hypoDir, ignorePatterns = []) {
     for (const entry of readdirSync(hypoDir)) {
       const full = join(hypoDir, entry);
       // root-level *.md FILES only (no recursion), honoring .hypoignore plus the
-      // scan-only generated-artifact exclusions (isScanIgnored) like collectPages
+      // scan-only generated-artifact exclusions (isScanIgnored) like collectPagesLint
       // — otherwise an ignored root file (e.g. a secret) or a regenerable report
       // would resolve [[its-slug]] as valid, a false negative.
       if (
@@ -180,7 +198,7 @@ function collectLinkTargets(hypoDir, ignorePatterns = []) {
   }
   // sources/*: linkable as the full 'sources/<name>' slug only — deliberately no
   // bare basename, so a stale [[name]] can't silently resolve to a source file.
-  for (const { rel } of collectPages(join(hypoDir, 'sources'), hypoDir, [], ignorePatterns)) {
+  for (const { rel } of collectPagesLint(join(hypoDir, 'sources'), hypoDir, ignorePatterns)) {
     targets.push(rel.replace(/\.md$/, '').replace(/\\/g, '/'));
   }
   return targets;
@@ -259,10 +277,15 @@ const issues = [];
 // STRICT_PROMOTE_IDS (OQ-E1, frozen as a code constant): confirmed content
 // defects only.
 //   W1 no-frontmatter / W2 unknown-type / W4 broken-wikilink → promote.
+//   W9 invalid-YAML → promote (frontmatter a real YAML parser rejects).
 //   W3 missing-updated  → excluded (auto-repaired by --fix).
 //   W8 design-history-stale → excluded (hypo-personal-check handles it; would
 //                             double-gate).
-const STRICT_PROMOTE_IDS = new Set(['W1', 'W2', 'W4']);
+// NOTE: no gate currently passes --strict (npm run lint / CI / release.yml /
+// crystallize / the close-gate all run plain lint), so promotion is
+// forward-looking — these surface as warnings today. IMPR-3's deliverable is
+// "stop silently green-passing invalid YAML"; the W9 warning satisfies that.
+const STRICT_PROMOTE_IDS = new Set(['W1', 'W2', 'W4', 'W9']);
 
 function issue(severity, rel, msg, fullPath = null, id = null) {
   issues.push({ severity, file: rel, message: msg, path: fullPath, id });
@@ -285,7 +308,7 @@ function lintSessionStateHeadings(content, rel) {
   }
 }
 
-function lintPage({ path, rel }, slugMap, tagVocab, pageDirs) {
+function lintPage({ path, rel }, slugMap, tagVocab, pageDirs, validTypes) {
   // Directory whitelist: a content page under pages/<subdir>/ must live in a
   // SCHEMA-defined directory. Catches typo'd dirs (e.g. pages/learning/ vs the
   // canonical pages/learnings/) regardless of frontmatter, since a directory
@@ -319,6 +342,16 @@ function lintPage({ path, rel }, slugMap, tagVocab, pageDirs) {
     return;
   }
 
+  // W9: invalid-YAML frontmatter the lenient line-scanner would otherwise pass
+  // green. Runs on the raw `---` block (the `content.match` above guarantees an
+  // opening fence; an unclosed fence falls through to the W3/parse path below).
+  const fmBlock = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (fmBlock) {
+    for (const reason of checkYamlInvalid(fmBlock[1])) {
+      issue('warn', rel, `Invalid YAML frontmatter: ${reason}`, null, 'W9');
+    }
+  }
+
   const fm = parseFrontmatter(content);
   if (!fm) {
     issue('error', rel, 'Malformed frontmatter (unclosed ---)');
@@ -329,7 +362,7 @@ function lintPage({ path, rel }, slugMap, tagVocab, pageDirs) {
     if (!fm[field]) issue('error', rel, `Missing required frontmatter field: ${field}`);
   }
 
-  if (fm.type && !VALID_TYPES.includes(fm.type)) {
+  if (fm.type && !validTypes.has(fm.type)) {
     issue('warn', rel, `Unknown type: "${fm.type}"`, null, 'W2');
   }
 
@@ -413,13 +446,19 @@ const args = parseArgs(process.argv);
 
 const ignorePatterns = loadHypoIgnore(args.hypoDir);
 const scanDirs = ['pages', 'projects', 'journal'].map((d) => join(args.hypoDir, d));
-const pages = scanDirs.flatMap((d) => collectPages(d, args.hypoDir, [], ignorePatterns));
+const pages = scanDirs.flatMap((d) => collectPagesLint(d, args.hypoDir, ignorePatterns));
 const linkTargets = collectLinkTargets(args.hypoDir, ignorePatterns);
 const slugMap = buildSlugMap(pages, linkTargets);
 const tagVocab = parseSchemaVocab(args.hypoDir);
 const pageDirs = parseSchemaPageDirs(args.hypoDir);
-
-for (const page of pages) lintPage(page, slugMap, tagVocab, pageDirs);
+// Accepted page types = hardcoded core ∪ the vault SCHEMA's taxonomy. Union (not
+// replace) so core types lint specially handles (session-state, source, …) are
+// never lost when a vault's SCHEMA omits or predates them, while a vault-local
+// extension (working-doc / draft / qa-run) is honored without editing lint —
+// mirroring how tags and page dirs are SCHEMA-derived.
+const validTypes = new Set([...VALID_TYPES, ...parseSchemaTypes(args.hypoDir)]);
+
+for (const page of pages) lintPage(page, slugMap, tagVocab, pageDirs, validTypes);
 
 // W8: design-history.md stale relative to session-log.md. Emitted once per
 // project (not per page) — runs outside the page loop. POSIX-separated path

package/scripts/rename.mjs

@@ -47,9 +47,10 @@ import {
   lstatSync,
   realpathSync,
 } from 'fs';
-import { join, relative, extname, basename, dirname, normalize, isAbsolute, sep } from 'path';
+import { join, basename, dirname, normalize, isAbsolute, sep } from 'path';
 import { resolveHypoRoot, expandHome } from './lib/hypo-root.mjs';
-import { loadHypoIgnore, isScanIgnored } from './lib/hypo-ignore.mjs';
+import { loadHypoIgnore } from './lib/hypo-ignore.mjs';
+import { collectPagesRename, slugForms } from './lib/wikilink.mjs';
 
 // ── arg parsing ───────────────────────────────────────────────────────────────
 
@@ -66,28 +67,6 @@ function parseArgs(argv) {
   return args;
 }
 
-// ── page collection (mirrors graph.mjs / crystallize.mjs collectPages) ──────────
-
-function collectPages(dir, root, pages = [], ignorePatterns = []) {
-  if (!existsSync(dir)) return pages;
-  for (const entry of readdirSync(dir)) {
-    const full = join(dir, entry);
-    if (isScanIgnored(full, root, ignorePatterns)) continue;
-    // lstat (never follow): a symlinked dir or file is skipped entirely so the
-    // whole-vault scan can never traverse out of the vault via a symlink.
-    const st = lstatSync(full);
-    if (st.isSymbolicLink()) {
-      continue;
-    } else if (st.isDirectory()) {
-      collectPages(full, root, pages, ignorePatterns);
-    } else if (extname(entry) === '.md' && !entry.startsWith('.')) {
-      const rel = relative(root, full).replace(/\\/g, '/');
-      pages.push({ path: full, rel, slug: rel.replace(/\.md$/, ''), bare: basename(full, '.md') });
-    }
-  }
-  return pages;
-}
-
 // ── preservation class of a link-source path ───────────────────────────────────
 // Two distinct reasons a file is normally skipped as a link SOURCE, kept separate
 // because directory mode treats them differently (codex design BLOCKER):
@@ -123,10 +102,7 @@ function isPreservedSource(rel) {
 // needs to KNOW when a form is shared, so it maps each form → the set of page
 // rels that expose it. precedence forms per page: full noExt slug, bare
 // basename, dir-relative (drop the leading scan-dir segment).
-function dirRelForm(slug) {
-  const slash = slug.indexOf('/');
-  return slash === -1 ? null : slug.slice(slash + 1);
-}
+const dirRelForm = (slug) => slugForms(slug).dirRel;
 
 function buildFormIndex(pages) {
   const index = new Map(); // form → Set<rel>
@@ -473,7 +449,7 @@ function runDirectory(args, fromDirRel, ignorePatterns) {
     fail(args, `--from subtree contains a symlink — refusing (move could escape the vault)`);
   }
 
-  const pages = collectPages(args.hypoDir, args.hypoDir, [], ignorePatterns);
+  const pages = collectPagesRename(args.hypoDir, args.hypoDir, ignorePatterns);
   const formIndex = buildFormIndex(pages);
 
   // The moving pages: every collected page whose rel is under the from-directory.
@@ -676,7 +652,7 @@ function run(args) {
     return runDirectory(args, fromNorm, ignorePatterns);
   }
 
-  const pages = collectPages(args.hypoDir, args.hypoDir, [], ignorePatterns);
+  const pages = collectPagesRename(args.hypoDir, args.hypoDir, ignorePatterns);
   const formIndex = buildFormIndex(pages);
 
   const fromPage = resolveArgToPage(args.from, pages, formIndex);

package/scripts/smoke-plugin.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+// smoke-plugin.mjs — a cheap, LOCAL structural check that the Claude Code plugin
+// would load, with no network and no Claude CLI dependency (so it runs in CI). It
+// validates the three surfaces Claude Code actually reads:
+//   1. .claude-plugin/plugin.json  — manifest (name, version, commands/skills paths)
+//   2. hooks/hooks.json            — every `${CLAUDE_PLUGIN_ROOT}/...` target must exist
+//   3. component files             — commands/*.md and skills/*/SKILL.md must be REAL
+//      (a .gitkeep alone is not a surface — a plugin with zero commands/skills must fail)
+// plus marketplace↔plugin name parity and that the marketplace `source` resolves to a
+// dir holding .claude-plugin/plugin.json.
+//
+// For a deep, real load check on a dev machine: `claude --plugin-dir . plugin list`.
+// That needs Claude Code installed, so it is NOT used here; this is the CI floor.
+//
+// Usage:
+//   node scripts/smoke-plugin.mjs               # smoke the repo's plugin
+//   node scripts/smoke-plugin.mjs --root <dir>  # point at a fixture (tests)
+//
+// Exit 0 = plugin surfaces are structurally valid. Exit 1 = a load-blocking problem.
+
+import { readFileSync, existsSync, statSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+function parseArgs(argv) {
+  const args = { root: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--root=')) args.root = a.slice(7);
+    else if (a === '--root') args.root = argv[++i];
+  }
+  return args;
+}
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function smoke(root) {
+  const errors = [];
+  const notes = [];
+  const fail = (msg) => errors.push(msg);
+
+  // 1. plugin.json manifest.
+  let plugin = null;
+  const pluginPath = join(root, '.claude-plugin', 'plugin.json');
+  try {
+    plugin = JSON.parse(readFileSync(pluginPath, 'utf-8'));
+  } catch (err) {
+    fail(`.claude-plugin/plugin.json: ${err?.message ?? err}`);
+  }
+  if (plugin) {
+    if (typeof plugin.name !== 'string' || !plugin.name) fail('plugin.json: missing "name"');
+    if (typeof plugin.version !== 'string' || !plugin.version)
+      fail('plugin.json: missing "version"');
+    // commands/skills are declared as relative dir paths; if declared they must resolve.
+    for (const key of ['commands', 'skills']) {
+      if (plugin[key] != null) {
+        const rel = String(plugin[key]).replace(/^\.\//, '');
+        if (!isDir(join(root, rel)))
+          fail(`plugin.json: "${key}" path "${plugin[key]}" is not a directory`);
+      }
+    }
+  }
+
+  // 2. Component files must be REAL regular files, not just a .gitkeep placeholder
+  // (or a directory that happens to be named like a component — isFile, not exists).
+  const commandsMd = isDir(join(root, 'commands'))
+    ? readdirSync(join(root, 'commands')).filter(
+        (f) => f.endsWith('.md') && isFile(join(root, 'commands', f)),
+      )
+    : [];
+  if (commandsMd.length === 0) fail('commands/: no *.md command files (only a placeholder?)');
+  else notes.push(`commands: ${commandsMd.length}`);
+
+  let skillCount = 0;
+  if (isDir(join(root, 'skills'))) {
+    for (const entry of readdirSync(join(root, 'skills'))) {
+      if (isFile(join(root, 'skills', entry, 'SKILL.md'))) skillCount++;
+    }
+  }
+  if (skillCount === 0) fail('skills/: no */SKILL.md skills (only a placeholder?)');
+  else notes.push(`skills: ${skillCount}`);
+
+  // 3. hooks/hooks.json — every command target AND every `shared` file must be a
+  // real regular file on disk. hooks.json is the hook source of truth, so a missing
+  // hypo-shared.mjs / version-check.mjs would pass a manifest-only check but break
+  // hook imports at runtime.
+  const hooksPath = join(root, 'hooks', 'hooks.json');
+  if (!existsSync(hooksPath)) {
+    fail('hooks/hooks.json: missing');
+  } else {
+    let hooksJson = null;
+    try {
+      hooksJson = JSON.parse(readFileSync(hooksPath, 'utf-8'));
+    } catch (err) {
+      fail(`hooks/hooks.json: ${err?.message ?? err}`);
+    }
+    if (hooksJson) {
+      if (!hooksJson.hooks || typeof hooksJson.hooks !== 'object') {
+        fail('hooks/hooks.json: missing top-level "hooks" object');
+      } else {
+        const targets = new Set();
+        for (const groups of Object.values(hooksJson.hooks)) {
+          for (const group of groups || []) {
+            for (const hk of group?.hooks || []) {
+              if (hk?.command) {
+                // command looks like `node ${CLAUDE_PLUGIN_ROOT}/hooks/foo.mjs [args]`
+                const m = String(hk.command).match(/\$\{CLAUDE_PLUGIN_ROOT\}\/(\S+)/);
+                if (m) targets.add(m[1]);
+              }
+            }
+          }
+        }
+        if (targets.size === 0)
+          fail('hooks/hooks.json: no ${CLAUDE_PLUGIN_ROOT} command targets found');
+        for (const rel of targets) {
+          if (!isFile(join(root, rel))) fail(`hooks/hooks.json: target "${rel}" is not a file`);
+        }
+        notes.push(`hook targets: ${targets.size}`);
+      }
+      // `shared` lists hook-relative support files that the targets import.
+      if (Array.isArray(hooksJson.shared)) {
+        for (const shared of hooksJson.shared) {
+          if (!isFile(join(root, 'hooks', shared)))
+            fail(`hooks/hooks.json: shared file "hooks/${shared}" is not a file`);
+        }
+        notes.push(`shared: ${hooksJson.shared.length}`);
+      }
+    }
+  }
+
+  // 4. marketplace.json — name parity + source resolves.
+  const mpPath = join(root, '.claude-plugin', 'marketplace.json');
+  let mp = null;
+  try {
+    mp = JSON.parse(readFileSync(mpPath, 'utf-8'));
+  } catch (err) {
+    fail(`.claude-plugin/marketplace.json: ${err?.message ?? err}`);
+  }
+  if (mp) {
+    const plugins = Array.isArray(mp.plugins) ? mp.plugins : [];
+    if (plugins.length === 0) fail('marketplace.json: "plugins" is empty');
+    const name = plugin?.name;
+    if (name) {
+      const matches = plugins.filter((p) => p && p.name === name);
+      if (matches.length !== 1) {
+        fail(
+          `marketplace.json: expected exactly one entry named "${name}", found ${matches.length}`,
+        );
+      } else {
+        const src = matches[0].source ?? './';
+        const srcDir = join(root, String(src).replace(/^\.\//, ''));
+        if (!existsSync(join(srcDir, '.claude-plugin', 'plugin.json'))) {
+          fail(
+            `marketplace.json: source "${src}" does not resolve to a dir containing .claude-plugin/plugin.json`,
+          );
+        }
+      }
+    }
+  }
+
+  return { errors, notes };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const root = args.root || REPO_ROOT;
+  const { errors, notes } = smoke(root);
+
+  if (errors.length) {
+    for (const e of errors) console.error(`  ✗ ${e}`);
+    console.error(`\n✗ plugin smoke failed (${errors.length} problem(s)).`);
+    process.exit(1);
+  }
+  console.log(`✓ plugin surfaces valid (${notes.join(', ')}).`);
+  process.exit(0);
+}
+
+main();