@skill-map/cli 0.29.0 → 0.31.0

package/dist/cli.js

@@ -775,6 +775,53 @@ function link(source, target) {
   };
 }
 
+// kernel/util/strip-code-blocks.ts
+var FENCE_RE = /^(?<indent> {0,3})(?<fence>`{3,}|~{3,})/;
+function stripCodeBlocks(input) {
+  if (!input) return input;
+  const fenceless = stripFences(input);
+  return stripInline(fenceless);
+}
+function stripFences(input) {
+  const out = [];
+  const lines = input.split("\n");
+  let openFence = null;
+  for (const line of lines) {
+    if (openFence) {
+      const closer = matchClosingFence(line, openFence);
+      if (closer) {
+        out.push(blank(line));
+        openFence = null;
+      } else {
+        out.push(blank(line));
+      }
+      continue;
+    }
+    const open = FENCE_RE.exec(line);
+    if (open?.groups) {
+      openFence = open.groups["fence"];
+      out.push(blank(line));
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join("\n");
+}
+function matchClosingFence(line, openFence) {
+  const m = FENCE_RE.exec(line);
+  if (!m?.groups) return false;
+  const fence = m.groups["fence"];
+  return fence[0] === openFence[0] && fence.length >= openFence.length;
+}
+function stripInline(input) {
+  return input.replace(/(`+)([\s\S]*?)\1/g, (_full, ticks, body) => {
+    return ticks.replace(/`/g, " ") + blank(body) + ticks.replace(/`/g, " ");
+  });
+}
+function blank(s) {
+  return s.replace(/[^\s]/g, " ");
+}
+
 // kernel/trigger-normalize.ts
 function normalizeTrigger(source) {
   let out = source.normalize("NFD");
@@ -787,21 +834,43 @@ function normalizeTrigger(source) {
 
 // plugins/core/extractors/at-directive/index.ts
 var ID2 = "at-directive";
-var AT_RE = /(?:^|[^A-Za-z0-9_@])(@[a-z0-9][a-z0-9_-]*(?:[/:][a-z0-9][a-z0-9_-]*)?)/gi;
+var AT_RE = /(?:^|[^A-Za-z0-9_@])(@(?:\.{1,2}\/|\/)?[a-z0-9](?:[a-z0-9_\-./]*[a-z0-9_])?(?::[a-z0-9][a-z0-9_-]*)?)/gi;
+var FILE_EXT_RE = /\.(md|mdx|js|jsx|ts|tsx|json|yml|yaml|toml|txt|html|css|scss|less|py|rb|go|rs|java|c|cpp|h|hpp|sh|sql|svg|png|jpg|jpeg|gif|webp|pdf)$/i;
 var atDirectiveExtractor = {
   id: ID2,
   pluginId: "core",
   kind: "extractor",
   version: "1.0.0",
-  description: "Detects `@agent-name` mentions in a node's body and turns each one into an arrow between nodes in the graph.",
+  description: "Detects `@<token>` directives in a node's body. A bare handle (e.g. `@team`) becomes a `mentions` link; a file-flavoured token (e.g. `@docs/api.md`, `@./readme.md`) becomes a `references` link, matching how Claude Code / Gemini CLI / Cursor read the same syntax.",
   scope: "body",
   extract(ctx) {
-    const seen = /* @__PURE__ */ new Set();
-    for (const match of ctx.body.matchAll(AT_RE)) {
+    const seenMentions = /* @__PURE__ */ new Set();
+    const seenReferences = /* @__PURE__ */ new Set();
+    const body = stripCodeBlocks(ctx.body);
+    for (const match of body.matchAll(AT_RE)) {
       const original = match[1];
+      const bare = original.slice(1);
+      const isReference = bare.startsWith("./") || bare.startsWith("../") || bare.startsWith("/") || FILE_EXT_RE.test(bare);
+      if (isReference) {
+        const target = bare.replace(/^\.\//, "");
+        if (seenReferences.has(target)) continue;
+        seenReferences.add(target);
+        ctx.emitLink({
+          source: ctx.node.path,
+          target,
+          kind: "references",
+          confidence: "medium",
+          sources: [ID2],
+          trigger: {
+            originalTrigger: original,
+            normalizedTrigger: target.toLowerCase()
+          }
+        });
+        continue;
+      }
       const normalized = normalizeTrigger(original);
-      if (seen.has(normalized)) continue;
-      seen.add(normalized);
+      if (seenMentions.has(normalized)) continue;
+      seenMentions.add(normalized);
       ctx.emitLink({
         source: ctx.node.path,
         target: original,
@@ -993,8 +1062,12 @@ var slashExtractor = {
   scope: "body",
   extract(ctx) {
     const seen = /* @__PURE__ */ new Set();
-    for (const match of ctx.body.matchAll(SLASH_RE)) {
+    const body = stripCodeBlocks(ctx.body);
+    for (const match of body.matchAll(SLASH_RE)) {
       const original = match[1];
+      const endIdx = (match.index ?? 0) + match[0].length;
+      const nextChar = body[endIdx];
+      if (nextChar && /[A-Za-z0-9_/-]/.test(nextChar)) continue;
       const normalized = normalizeTrigger(original);
       if (seen.has(normalized)) continue;
       seen.add(normalized);
@@ -1176,7 +1249,7 @@ function tooltipFor(status) {
 }
 
 // plugins/core/analyzers/broken-ref/index.ts
-import { resolve } from "path";
+import { posix as pathPosix2, resolve } from "path";
 
 // plugins/core/analyzers/broken-ref/text.ts
 var BROKEN_REF_TEXTS = {
@@ -1185,7 +1258,13 @@ var BROKEN_REF_TEXTS = {
   // Tooltips for the per-node view-contribution badges. Singular vs
   // plural keeps the count grammar correct without a sub-template.
   alertTooltipSingle: "This node has a broken reference. Open the inspector for details.",
-  alertTooltipMany: "This node has {{count}} broken references. Open the inspector for details."
+  alertTooltipMany: "This node has {{count}} broken references. Open the inspector for details.",
+  // Fix-summary copy when the broken trigger has a same-named file on
+  // disk that does not advertise `name:` in its frontmatter. Two
+  // variants for single vs multiple candidates; same template family
+  // as the alert tooltips above.
+  hintSummarySingle: "Add `name: {{name}}` to the frontmatter of {{candidate}} so this reference resolves.",
+  hintSummaryMany: "Add `name: {{name}}` to the frontmatter of one of these files so this reference resolves: {{candidates}}."
 };
 
 // plugins/core/analyzers/broken-ref/index.ts
@@ -1225,13 +1304,15 @@ var brokenRefAnalyzer = {
   evaluate(ctx) {
     const byPath3 = new Set(ctx.nodes.map((n) => n.path));
     const byNormalizedName = indexByNormalizedName(ctx.nodes);
+    const byBasenameWithoutName = indexByBasenameWithoutName(ctx.nodes);
     const refIndex = ctx.referenceablePaths && ctx.referenceablePaths.size > 0 && ctx.cwd ? { paths: ctx.referenceablePaths, cwd: ctx.cwd } : null;
     const issues = [];
     const perNode = /* @__PURE__ */ new Map();
     for (const link2 of ctx.links) {
       if (isResolved(link2, byPath3, byNormalizedName)) continue;
       if (refIndex && resolvesViaReferencePaths(link2, refIndex)) continue;
-      issues.push(buildIssue(link2));
+      const candidates = findHintCandidates(link2, byBasenameWithoutName);
+      issues.push(buildIssue(link2, candidates));
       perNode.set(link2.source, (perNode.get(link2.source) ?? 0) + 1);
     }
     for (const [nodePath, count] of perNode) {
@@ -1251,8 +1332,13 @@ var brokenRefAnalyzer = {
     return issues;
   }
 };
-function buildIssue(link2) {
-  return {
+function buildIssue(link2, hintCandidates = []) {
+  const data = {
+    target: link2.target,
+    kind: link2.kind,
+    trigger: link2.trigger?.normalizedTrigger ?? null
+  };
+  const issue = {
     analyzerId: ID9,
     severity: "warn",
     nodeIds: [link2.source],
@@ -1261,12 +1347,28 @@ function buildIssue(link2) {
       source: link2.source,
       target: link2.target
     }),
-    data: {
-      target: link2.target,
-      kind: link2.kind,
-      trigger: link2.trigger?.normalizedTrigger ?? null
-    }
+    data
   };
+  if (hintCandidates.length > 0) {
+    const suggestedName = (link2.trigger?.normalizedTrigger ?? "").replace(/^[/@]/, "").trim();
+    const candidatePaths = hintCandidates.map((n) => n.path);
+    data["hint"] = {
+      kind: "missing-frontmatter-name",
+      suggestedName,
+      candidates: candidatePaths
+    };
+    issue.fix = {
+      summary: candidatePaths.length === 1 ? tx(BROKEN_REF_TEXTS.hintSummarySingle, {
+        name: suggestedName,
+        candidate: candidatePaths[0]
+      }) : tx(BROKEN_REF_TEXTS.hintSummaryMany, {
+        name: suggestedName,
+        candidates: candidatePaths.join(", ")
+      }),
+      autofixable: false
+    };
+  }
+  return issue;
 }
 function resolvesViaReferencePaths(link2, refIndex) {
   if (!isPathStyleLink(link2)) return false;
@@ -1285,6 +1387,36 @@ function indexByNormalizedName(nodes) {
   }
   return out;
 }
+function basenameWithoutExt(path) {
+  const base = pathPosix2.basename(path);
+  const ext = pathPosix2.extname(base);
+  return ext ? base.slice(0, -ext.length) : base;
+}
+function indexByBasenameWithoutName(nodes) {
+  const out = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    const raw = node.frontmatter?.["name"];
+    const name = typeof raw === "string" ? raw : "";
+    if (name) continue;
+    const bare = basenameWithoutExt(node.path);
+    if (!bare) continue;
+    const key = normalizeTrigger(bare);
+    if (!key) continue;
+    const bucket = out.get(key) ?? [];
+    bucket.push(node);
+    out.set(key, bucket);
+  }
+  return out;
+}
+function findHintCandidates(link2, idx) {
+  const normalized = link2.trigger?.normalizedTrigger;
+  if (!normalized) return [];
+  const sigil = normalized.charAt(0);
+  if (sigil !== "/" && sigil !== "@") return [];
+  const withoutSigil = normalized.slice(1).trim();
+  if (!withoutSigil) return [];
+  return idx.get(withoutSigil) ?? [];
+}
 function isResolved(link2, byPath3, byNormalizedName) {
   const normalized = link2.trigger?.normalizedTrigger;
   if (normalized) {
@@ -2831,7 +2963,7 @@ var UPDATE_CHECK_TEXTS = {
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.29.0",
+  version: "0.31.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -7949,9 +8081,9 @@ function providerKindFailure(opts, status, fileName, errDescription) {
     }
   };
 }
-function isDirectorySafe(path, statSync11) {
+function isDirectorySafe(path, statSync12) {
   try {
-    return statSync11(path).isDirectory();
+    return statSync12(path).isDirectory();
   } catch {
     return false;
   }
@@ -23616,43 +23748,37 @@ var STUB_COMMANDS = [
 ];
 
 // cli/commands/tutorial.ts
-import { existsSync as existsSync29, readFileSync as readFileSync19 } from "fs";
-import { writeFile as writeFile2 } from "fs/promises";
+import { cpSync as cpSync2, existsSync as existsSync29, mkdirSync as mkdirSync7, rmSync as rmSync2, statSync as statSync11 } from "fs";
 import { dirname as dirname19, join as join19, resolve as resolve36 } from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
 import { Command as Command37, Option as Option35 } from "clipanion";
 
 // cli/i18n/tutorial.texts.ts
 var TUTORIAL_TEXTS = {
-  // Success, written to stdout after `<cwd>/{{filename}}` is created.
-  // Multi-line layout: the two trigger phrases (English / Spanish) are
-  // indented and labelled so they're the most visible part of the
-  // output. The reminder above them surfaces the SKILL's language
-  // policy: the first message the tester writes to Claude sets the
-  // tutorial language for the rest of the session.
-  /**
-   * Success body. `glyph` is wrapped green at the call site; `cwd`
-   * renders relative to the user's cwd when it sits underneath. The
-   * `English` / `Español` labels print dim, the eye lands on the
-   * trigger phrases the user is going to copy / paste.
-   */
-  written: "  {{glyph}}  {{filename}} created at {{cwd}}\n\n  Open Claude Code in this directory. Your first message sets\n  the tutorial language for the rest of the session:\n\n      {{enLabel}}  run @{{filename}}\n      {{esLabel}}  ejecut\xE1 @{{filename}}\n",
+  // Success, written to stdout after `<cwd>/{{target}}` is created.
+  // The skill now lives at `.claude/skills/<slug>/`; Claude Code
+  // auto-discovers it on the next boot, so the tester invokes by
+  // speaking a trigger phrase rather than referencing the file path.
+  // English / Spanish triggers are surfaced side by side and the
+  // first phrase the tester types sets the tutorial language for the
+  // rest of the session.
+  written: "  {{glyph}}  Skill `{{slug}}` materialized at {{target}} (under {{cwd}})\n\n  Open Claude Code in this directory. The skill is auto-\n  discovered; invoke it with one of its trigger phrases. The\n  first message you type sets the tutorial language for the\n  rest of the session:\n\n      {{enLabel}}  {{enTrigger}}\n      {{esLabel}}  {{esTrigger}}\n",
   writtenLabelEn: "English",
   writtenLabelEs: "Espa\xF1ol",
-  // Refusal, `{{filename}}` already exists and `--force` was not set.
+  // Refusal, `{{target}}` already exists and `--force` was not set.
   // Goes to stderr, exit code 2 (operational error per spec § Exit codes).
   // Mirrors the success body shape: glyph + headline, then a dim hint
   // line spelling the fix.
-  alreadyExists: "{{glyph}}  {{filename}} already exists at {{cwd}}\n   {{hint}}\n",
-  alreadyExistsHint: "Pass `--force` to overwrite.",
+  alreadyExists: "{{glyph}}  {{target}} already exists under {{cwd}}\n   {{hint}}\n",
+  alreadyExistsHint: "Pass `--force` to overwrite (deletes the existing folder first).",
   // Invalid `variant` positional argument. Goes to stderr, exit code 2.
   // Mirrors `alreadyExists`: glyph + headline + dim hint enumerating the
   // valid values.
   invalidVariant: "{{glyph}}  sm tutorial: unknown variant '{{variant}}'\n   {{hint}}\n",
   invalidVariantHint: "Valid values: tutorial (default), master.",
-  // I/O failure on write or on reading the bundled SKILL source.
-  writeFailed: "{{glyph}}  sm tutorial: failed to write {{filename}}: {{message}}\n",
-  sourceMissing: "{{glyph}}  sm tutorial: could not read the bundled tutorial ({{filename}}) from the install.\n   {{hint}}\n",
+  // I/O failure on write or on reading the bundled skill source.
+  writeFailed: "{{glyph}}  sm tutorial: failed to write {{target}}: {{message}}\n",
+  sourceMissing: "{{glyph}}  sm tutorial: could not read the bundled skill payload for {{target}} from the install.\n   {{hint}}\n",
   sourceMissingHint: "Reinstall @skill-map/cli or report the bug."
 };
 
@@ -23661,41 +23787,45 @@ var VALID_VARIANTS = ["tutorial", "master"];
 var DEFAULT_VARIANT = "tutorial";
 var VARIANT_SPECS = {
   tutorial: {
-    filename: "sm-tutorial.md",
-    sourcePath: ".claude/skills/sm-tutorial/SKILL.md",
-    bundledName: "sm-tutorial.md"
+    slug: "sm-tutorial",
+    sourceDir: ".claude/skills/sm-tutorial",
+    triggerEn: "start the tutorial",
+    triggerEs: "arranquemos el tutorial"
   },
   master: {
-    filename: "sm-master.md",
-    sourcePath: ".claude/skills/sm-master/SKILL.md",
-    bundledName: "sm-master.md"
+    slug: "sm-master",
+    sourceDir: ".claude/skills/sm-master",
+    triggerEn: "advanced tutorial",
+    triggerEs: "tutorial maestro"
   }
 };
 var TutorialCommand = class extends SmCommand {
   static paths = [["tutorial"]];
   static usage = Command37.Usage({
     category: "Setup",
-    description: "Materialize an interactive tester tutorial (sm-tutorial.md or sm-master.md) in the current directory.",
+    description: "Materialize an interactive tester tutorial as a Claude Code skill folder under `<cwd>/.claude/skills/`.",
     details: `
-      Drops the canonical SKILL.md content as ./sm-tutorial.md (default)
-      or ./sm-master.md (when invoked as \`sm tutorial master\`) so a
-      tester can open Claude Code in the cwd and load the file as a
-      skill by typing "ejecut\xE1 @sm-tutorial.md" (or "@sm-master.md").
-      Top-level only; no subdirectory is created.
+      Drops the canonical skill directory (SKILL.md + any references/
+      sub-folder) under \`<cwd>/.claude/skills/sm-tutorial/\` (default)
+      or \`<cwd>/.claude/skills/sm-master/\` (when invoked as \`sm
+      tutorial master\`). Claude Code auto-discovers the skill the
+      next time it boots in this directory; the tester invokes it by
+      speaking one of its trigger phrases.
 
       Does NOT require an initialized .skill-map/ project. Refuses to
-      overwrite the target file unless --force is passed. Valid values
-      for the positional argument are: tutorial (default), master.
+      overwrite the target directory unless --force is passed. Valid
+      values for the positional argument are: tutorial (default),
+      master.
     `,
     examples: [
-      ["Materialize the basic tutorial in the cwd", "$0 tutorial"],
-      ["Materialize the advanced tutorial in the cwd", "$0 tutorial master"],
-      ["Overwrite an existing target file", "$0 tutorial --force"]
+      ["Materialize the basic tutorial skill in the cwd", "$0 tutorial"],
+      ["Materialize the advanced tutorial skill in the cwd", "$0 tutorial master"],
+      ["Overwrite an existing target directory", "$0 tutorial --force"]
     ]
   });
   variant = Option35.String({ required: false });
   force = Option35.Boolean("--force", false, {
-    description: "Overwrite an existing target file without prompting."
+    description: "Overwrite an existing target directory without prompting."
   });
   async run() {
     const ctx = defaultRuntimeContext();
@@ -23715,38 +23845,41 @@ var TutorialCommand = class extends SmCommand {
     }
     const variant = rawVariant ?? DEFAULT_VARIANT;
     const spec = VARIANT_SPECS[variant];
-    const target = join19(ctx.cwd, spec.filename);
-    if (await pathExists(target) && !this.force) {
+    const targetDir = join19(ctx.cwd, ".claude", "skills", spec.slug);
+    const targetDisplay = `.claude/skills/${spec.slug}/`;
+    if (existsSync29(targetDir) && !this.force) {
       this.printer.error(
         tx(TUTORIAL_TEXTS.alreadyExists, {
           glyph: errGlyph,
-          filename: spec.filename,
+          target: targetDisplay,
           cwd: stderrAnsi.dim(displayCwd(ctx.cwd)),
           hint: stderrAnsi.dim(TUTORIAL_TEXTS.alreadyExistsHint)
         })
       );
       return ExitCode.Error;
     }
-    let body;
+    let sourceDir;
     try {
-      body = loadBundledTutorialText(variant);
+      sourceDir = resolveSkillSourceDir(variant);
     } catch {
       this.printer.error(
         tx(TUTORIAL_TEXTS.sourceMissing, {
           glyph: errGlyph,
-          filename: spec.filename,
+          target: targetDisplay,
           hint: stderrAnsi.dim(TUTORIAL_TEXTS.sourceMissingHint)
         })
       );
       return ExitCode.Error;
     }
     try {
-      await writeFile2(target, body);
+      rmSync2(targetDir, { recursive: true, force: true });
+      mkdirSync7(dirname19(targetDir), { recursive: true });
+      cpSync2(sourceDir, targetDir, { recursive: true });
     } catch (err) {
       this.printer.error(
         tx(TUTORIAL_TEXTS.writeFailed, {
           glyph: errGlyph,
-          filename: spec.filename,
+          target: targetDisplay,
           message: formatErrorMessage(err)
         })
       );
@@ -23762,10 +23895,13 @@ var TutorialCommand = class extends SmCommand {
     this.printer.data(
       tx(TUTORIAL_TEXTS.written, {
         glyph: ansi.green("\u2713"),
-        filename: spec.filename,
+        slug: spec.slug,
+        target: targetDisplay,
         cwd: ansi.dim(displayCwd(ctx.cwd)),
         enLabel: ansi.dim(TUTORIAL_TEXTS.writtenLabelEn),
-        esLabel: ansi.dim(TUTORIAL_TEXTS.writtenLabelEs)
+        esLabel: ansi.dim(TUTORIAL_TEXTS.writtenLabelEs),
+        enTrigger: spec.triggerEn,
+        esTrigger: spec.triggerEs
       })
     );
     return ExitCode.Ok;
@@ -23779,31 +23915,29 @@ function displayCwd(cwd) {
   if (segments.length === 0) return "./";
   return `./${segments[segments.length - 1]}/`;
 }
-var cachedTutorials = /* @__PURE__ */ new Map();
-function loadBundledTutorialText(variant) {
-  const cached = cachedTutorials.get(variant);
+var cachedSourceDirs = /* @__PURE__ */ new Map();
+function resolveSkillSourceDir(variant) {
+  const cached = cachedSourceDirs.get(variant);
   if (cached !== void 0) return cached;
-  const body = readTutorialFromDisk(variant);
-  cachedTutorials.set(variant, body);
-  return body;
-}
-function readTutorialFromDisk(variant) {
   const spec = VARIANT_SPECS[variant];
   const here = dirname19(fileURLToPath6(import.meta.url));
   const candidates = [
-    // dev: src/cli/commands/ → repo-root .claude/skills/<slug>/SKILL.md
-    resolve36(here, "../../..", spec.sourcePath),
-    // bundled: dist/cli.js → dist/cli/tutorial/<filename> (sibling)
-    resolve36(here, "cli/tutorial", spec.bundledName),
-    // bundled fallback: any-depth → cli/tutorial/<filename>
-    resolve36(here, "../cli/tutorial", spec.bundledName)
+    // dev: src/cli/commands/ → repo-root .claude/skills/<slug>/
+    resolve36(here, "../../..", spec.sourceDir),
+    // bundled: dist/cli.js → dist/cli/tutorial/<slug> (sibling)
+    resolve36(here, "cli/tutorial", spec.slug),
+    // bundled fallback: any-depth → cli/tutorial/<slug>
+    resolve36(here, "../cli/tutorial", spec.slug)
   ];
   for (const candidate of candidates) {
-    if (existsSync29(candidate)) {
-      return readFileSync19(candidate, "utf8");
+    if (existsSync29(candidate) && statSync11(candidate).isDirectory()) {
+      cachedSourceDirs.set(variant, candidate);
+      return candidate;
     }
   }
-  throw new Error(`SKILL.md not found in any candidate location (last tried: ${candidates[candidates.length - 1]})`);
+  throw new Error(
+    `skill source directory not found in any candidate location (last tried: ${candidates[candidates.length - 1]})`
+  );
 }
 
 // cli/commands/version.ts