@skill-map/cli 0.11.1 → 0.13.0

package/README.md

@@ -1,6 +1,6 @@
 # skill-map
 
-Map, inspect, and manage collections of interrelated Markdown files — skills, agents, commands, hooks, and notes that compose AI-agent ecosystems (Claude Code, Codex, Gemini, Copilot, Obsidian vaults, docs sites).
+Map, inspect, and manage collections of interrelated Markdown files — skills, agents, commands, hooks, and notes that compose AI-agent ecosystems (Claude Code, Codex, Gemini, Copilot, docs sites).
 
 **Status**: pre-1.0, active development. Steps 0a–9 are complete (spec, kernel, plugin loader, full CLI surface, plugin author UX). Step 14 (Full Web UI) is in progress with sub-steps 14.1–14.4 closed (Hono BFF + REST + WebSocket broadcaster + reactive UI); 14.5–14.7 (polish + bundle budgets + responsive scope) still pending. The full deterministic scan, check, history, orphans, plugin authoring, and `sm serve` are live; the optional LLM layer (Phase B / `v0.8.0`) lands after Step 14 closes. See [`ROADMAP.md`](../ROADMAP.md) for the canonical completeness marker and full execution plan. Releases follow the standard changeset flow.
 

package/dist/cli.js

@@ -1,4 +1,5 @@
 // cli/entry.ts
+import { existsSync as existsSync19 } from "fs";
 import { Builtins, Cli as Cli2 } from "clipanion";
 
 // kernel/adapters/silent-logger.ts
@@ -28,6 +29,41 @@ function configureLogger(impl) {
   active = impl;
 }
 
+// kernel/util/tx.ts
+var TOKEN_RE = /\{\{\s*([A-Za-z][A-Za-z0-9_]*)\s*\}\}/g;
+function tx(template, vars = {}) {
+  return template.replace(TOKEN_RE, (_match, name) => {
+    if (!Object.prototype.hasOwnProperty.call(vars, name)) {
+      throw new Error(
+        `tx: missing variable "${name}" for template "${template.slice(0, 80)}${template.length > 80 ? "\u2026" : ""}"`
+      );
+    }
+    const value = vars[name];
+    if (value === null || value === void 0) {
+      throw new Error(
+        `tx: variable "${name}" is null/undefined for template "${template.slice(0, 80)}${template.length > 80 ? "\u2026" : ""}"`
+      );
+    }
+    return String(value);
+  });
+}
+
+// cli/i18n/entry.texts.ts
+var ENTRY_TEXTS = {
+  bareNoProject: 'No skill-map project found in {{cwd}}.\nRun "sm init" to bootstrap one, or "sm --help" to see all commands.\n',
+  parseErrorHeadline: "sm: {{message}}",
+  parseErrorUnknownOption: "unknown option '{{name}}'",
+  parseErrorUnknownOptionForVerb: "{{verb}}: unknown option '{{name}}'",
+  parseErrorUnknownCommand: "unknown command '{{name}}'",
+  parseErrorIncompleteCommand: "incomplete command '{{name}}'",
+  parseErrorSubcommandList: "Available subcommands: {{suggestions}}.",
+  parseErrorVerbUsage: "{{verb}}: {{message}}",
+  parseErrorFlagSuggestion: "Did you mean '{{suggestion}}'?",
+  parseErrorVerbSuggestion: "Did you mean {{suggestions}}?",
+  parseErrorVerbHelpHint: "Run 'sm help {{verb}}' for usage.",
+  parseErrorFooter: "Run 'sm help' to see the full command list."
+};
+
 // kernel/ports/logger.ts
 var LOG_LEVELS = [
   "trace",
@@ -65,25 +101,6 @@ function sanitizeForTerminal(text) {
   return text.replace(ANSI_ESCAPE_RE, "").replace(C0_CONTROL_RE, "");
 }
 
-// kernel/util/tx.ts
-var TOKEN_RE = /\{\{\s*([A-Za-z][A-Za-z0-9_]*)\s*\}\}/g;
-function tx(template, vars = {}) {
-  return template.replace(TOKEN_RE, (_match, name) => {
-    if (!Object.prototype.hasOwnProperty.call(vars, name)) {
-      throw new Error(
-        `tx: missing variable "${name}" for template "${template.slice(0, 80)}${template.length > 80 ? "\u2026" : ""}"`
-      );
-    }
-    const value = vars[name];
-    if (value === null || value === void 0) {
-      throw new Error(
-        `tx: variable "${name}" is null/undefined for template "${template.slice(0, 80)}${template.length > 80 ? "\u2026" : ""}"`
-      );
-    }
-    return String(value);
-  });
-}
-
 // cli/i18n/logger.texts.ts
 var LOGGER_TEXTS = {
   invalidLevel: 'invalid log level "{{value}}" (expected one of: {{allowed}})\n'
@@ -179,6 +196,224 @@ function extractLogLevelFlag(argv) {
 }
 var LOGGER_ENV_VAR = ENV_VAR;
 
+// cli/util/db-path.ts
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+
+// cli/i18n/util.texts.ts
+var UTIL_TEXTS = {
+  // db-path.ts
+  dbNotFound: "DB not found at {{path}}; run `sm scan` first.\n",
+  // elapsed.ts
+  doneIn: "done in {{elapsed}}\n",
+  // confirm.ts (default-no prompt suffix)
+  confirmPromptSuffix: " [y/N] ",
+  /**
+   * Regex source matching affirmative answers in `confirm()`. Compiled
+   * with the `i` flag in the helper. Pre-i18n today the pattern is
+   * English-only; when a non-English locale lands the catalog grows
+   * alternations (e.g. `^(y(es)?|s(í|i)?)$`).
+   */
+  confirmYesPatternSource: "^y(es)?$"
+};
+
+// cli/util/db-path.ts
+var SKILL_MAP_DIR = ".skill-map";
+var DB_FILENAME = "skill-map.db";
+var JOBS_DIRNAME = "jobs";
+var PLUGINS_DIRNAME = "plugins";
+var SETTINGS_FILENAME = "settings.json";
+var LOCAL_SETTINGS_FILENAME = "settings.local.json";
+var IGNORE_FILENAME = ".skill-mapignore";
+var DEFAULT_DB_REL = `${SKILL_MAP_DIR}/${DB_FILENAME}`;
+var GITIGNORE_ENTRIES = [
+  `${SKILL_MAP_DIR}/${LOCAL_SETTINGS_FILENAME}`,
+  `${SKILL_MAP_DIR}/${DB_FILENAME}`
+];
+function resolveDbPath(options) {
+  if (options.db) return resolve(options.db);
+  if (options.global) return join(options.homedir, DEFAULT_DB_REL);
+  return resolve(options.cwd, DEFAULT_DB_REL);
+}
+function defaultProjectDbPath(ctx) {
+  return resolve(ctx.cwd, DEFAULT_DB_REL);
+}
+function defaultProjectJobsDir(ctx) {
+  return resolve(ctx.cwd, SKILL_MAP_DIR, JOBS_DIRNAME);
+}
+function defaultProjectPluginsDir(ctx) {
+  return resolve(ctx.cwd, SKILL_MAP_DIR, PLUGINS_DIRNAME);
+}
+function defaultUserPluginsDir(ctx) {
+  return join(ctx.homedir, SKILL_MAP_DIR, PLUGINS_DIRNAME);
+}
+function defaultDbPath(scopeRoot) {
+  return join(scopeRoot, SKILL_MAP_DIR, DB_FILENAME);
+}
+function defaultSettingsPath(scopeRoot) {
+  return join(scopeRoot, SKILL_MAP_DIR, SETTINGS_FILENAME);
+}
+function defaultLocalSettingsPath(scopeRoot) {
+  return join(scopeRoot, SKILL_MAP_DIR, LOCAL_SETTINGS_FILENAME);
+}
+function defaultIgnoreFilePath(scopeRoot) {
+  return join(scopeRoot, IGNORE_FILENAME);
+}
+function assertDbExists(path, stderr) {
+  if (path === ":memory:" || existsSync(path)) return true;
+  stderr.write(tx(UTIL_TEXTS.dbNotFound, { path }));
+  return false;
+}
+
+// cli/util/exit-codes.ts
+var ExitCode = {
+  Ok: 0,
+  Issues: 1,
+  Error: 2,
+  Duplicate: 3,
+  NonceMismatch: 4,
+  NotFound: 5
+};
+
+// cli/util/parse-error.ts
+function isClipanionParseError(err) {
+  if (!err || typeof err !== "object") return false;
+  const e = err;
+  if (typeof e.name !== "string") return false;
+  if (!Array.isArray(e.input)) return false;
+  return e.name === "UnknownSyntaxError" || e.name === "AmbiguousSyntaxError";
+}
+function formatParseError(params) {
+  const { args: args2, verbPaths, error } = params;
+  const firstToken = args2[0] ?? "";
+  const offendingFlag = extractOffendingFlag(error.message);
+  if (offendingFlag !== null) {
+    const verbPrefix2 = matchedVerbPrefix(args2, verbPaths);
+    const suggestion2 = suggestFlag(offendingFlag);
+    const headline = verbPrefix2 ? tx(ENTRY_TEXTS.parseErrorUnknownOptionForVerb, { verb: verbPrefix2, name: offendingFlag }) : tx(ENTRY_TEXTS.parseErrorUnknownOption, { name: offendingFlag });
+    return renderError(headline, suggestion2);
+  }
+  if (firstToken === "") {
+    return renderError(error.message.trim(), null);
+  }
+  const verbPrefix = matchedVerbPrefix(args2, verbPaths);
+  if (verbPrefix) {
+    const headline = tx(ENTRY_TEXTS.parseErrorVerbUsage, { verb: verbPrefix, message: error.message.trim() });
+    return renderError(headline, tx(ENTRY_TEXTS.parseErrorVerbHelpHint, { verb: verbPrefix }));
+  }
+  const subcommands = subcommandsUnder(firstToken, verbPaths);
+  if (subcommands.length > 0) {
+    const headline = tx(ENTRY_TEXTS.parseErrorIncompleteCommand, { name: firstToken });
+    const suggestion2 = tx(ENTRY_TEXTS.parseErrorSubcommandList, {
+      suggestions: formatSuggestionList(subcommands)
+    });
+    return renderError(headline, suggestion2);
+  }
+  const candidates = closestVerbs(firstToken, verbPaths);
+  const suggestion = candidates.length > 0 ? tx(ENTRY_TEXTS.parseErrorVerbSuggestion, { suggestions: formatSuggestionList(candidates) }) : null;
+  return renderError(tx(ENTRY_TEXTS.parseErrorUnknownCommand, { name: firstToken }), suggestion);
+}
+function subcommandsUnder(namespace, verbPaths) {
+  const matches = verbPaths.filter((path) => path.length >= 2 && path[0] === namespace).map((path) => path.join(" ")).sort();
+  return matches.slice(0, 3);
+}
+function matchedVerbPrefix(args2, verbPaths) {
+  const leading = [];
+  for (const tok of args2) {
+    if (tok.startsWith("-")) break;
+    leading.push(tok);
+  }
+  if (leading.length === 0) return "";
+  let best = [];
+  for (const path of verbPaths) {
+    if (path.length > leading.length) continue;
+    const matches = path.every((tok, i) => leading[i] === tok);
+    if (matches && path.length > best.length) best = path;
+  }
+  return best.join(" ");
+}
+function renderError(headline, suggestion) {
+  const lines = [tx(ENTRY_TEXTS.parseErrorHeadline, { message: headline })];
+  if (suggestion) lines.push(suggestion);
+  lines.push(ENTRY_TEXTS.parseErrorFooter);
+  return lines.join("\n") + "\n";
+}
+function extractOffendingFlag(message) {
+  const match = /Unsupported option name \("([^"]+)"\)/.exec(message);
+  return match ? match[1] : null;
+}
+function suggestFlag(token) {
+  if (!token.startsWith("-")) return null;
+  if (token.startsWith("--")) return null;
+  if (token.length <= 2) return null;
+  const longForm = "-" + token;
+  return tx(ENTRY_TEXTS.parseErrorFlagSuggestion, { suggestion: longForm });
+}
+function editDistance(a, b, max) {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  let curr = new Array(n + 1);
+  for (let i = 1; i <= m; i++) {
+    const rowMin = fillEditRow({ a, b, i, prev, curr });
+    if (rowMin > max) return max + 1;
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
+function fillEditRow(args2) {
+  const { a, b, i, prev, curr } = args2;
+  curr[0] = i;
+  let rowMin = curr[0];
+  for (let j = 1; j < curr.length; j++) {
+    const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+    const value = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    curr[j] = value;
+    if (value < rowMin) rowMin = value;
+  }
+  return rowMin;
+}
+function closestVerbs(typed, verbPaths) {
+  const target = typed.toLowerCase();
+  const distanceCap = target.length <= 4 ? 2 : 3;
+  const ranked = [];
+  for (const path of verbPaths) {
+    const verb = path.join(" ");
+    const head = path[0];
+    const distHead = editDistance(target, head.toLowerCase(), distanceCap);
+    const distFull = editDistance(target, verb.replace(/\s+/g, "").toLowerCase(), distanceCap);
+    const distance = Math.min(distHead, distFull);
+    if (distance <= distanceCap) ranked.push({ verb, distance });
+  }
+  ranked.sort((a, b) => a.distance - b.distance || a.verb.localeCompare(b.verb));
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const { verb } of ranked) {
+    const head = verb.split(" ")[0];
+    if (seen.has(head)) continue;
+    seen.add(head);
+    out.push(verb);
+    if (out.length === 3) break;
+  }
+  return out;
+}
+function formatSuggestionList(items) {
+  const quoted = items.map((s) => `'${s}'`);
+  if (quoted.length <= 1) return quoted[0] ?? "";
+  if (quoted.length === 2) return `${quoted[0]} or ${quoted[1]}`;
+  return `${quoted.slice(0, -1).join(", ")}, or ${quoted[quoted.length - 1]}`;
+}
+
+// cli/util/runtime-context.ts
+import { homedir } from "os";
+function defaultRuntimeContext() {
+  return { cwd: process.cwd(), homedir: homedir() };
+}
+
 // cli/commands/check.ts
 import { Command as Command2, Option as Option2 } from "clipanion";
 
@@ -271,91 +506,6 @@ var CHECK_TEXTS = {
   probStubAdvisoryAsync: "sm check --include-prob --async: probabilistic Rule dispatch requires the job subsystem (Step 10). Stub: skipped {{count}} probabilistic rule(s) \u2014 {{ruleIds}}. The --async flag is reserved for future encoding (returns job ids without waiting once jobs land); today it is a no-op. Deterministic rules ran as usual.\n"
 };
 
-// cli/util/db-path.ts
-import { existsSync } from "fs";
-import { join, resolve } from "path";
-
-// cli/i18n/util.texts.ts
-var UTIL_TEXTS = {
-  // db-path.ts
-  dbNotFound: "DB not found at {{path}}; run `sm scan` first.\n",
-  // elapsed.ts
-  doneIn: "done in {{elapsed}}\n",
-  // confirm.ts (default-no prompt suffix)
-  confirmPromptSuffix: " [y/N] ",
-  /**
-   * Regex source matching affirmative answers in `confirm()`. Compiled
-   * with the `i` flag in the helper. Pre-i18n today the pattern is
-   * English-only; when a non-English locale lands the catalog grows
-   * alternations (e.g. `^(y(es)?|s(í|i)?)$`).
-   */
-  confirmYesPatternSource: "^y(es)?$"
-};
-
-// cli/util/db-path.ts
-var SKILL_MAP_DIR = ".skill-map";
-var DB_FILENAME = "skill-map.db";
-var JOBS_DIRNAME = "jobs";
-var PLUGINS_DIRNAME = "plugins";
-var SETTINGS_FILENAME = "settings.json";
-var LOCAL_SETTINGS_FILENAME = "settings.local.json";
-var IGNORE_FILENAME = ".skill-mapignore";
-var DEFAULT_DB_REL = `${SKILL_MAP_DIR}/${DB_FILENAME}`;
-var GITIGNORE_ENTRIES = [
-  `${SKILL_MAP_DIR}/${LOCAL_SETTINGS_FILENAME}`,
-  `${SKILL_MAP_DIR}/${DB_FILENAME}`
-];
-function resolveDbPath(options) {
-  if (options.db) return resolve(options.db);
-  if (options.global) return join(options.homedir, DEFAULT_DB_REL);
-  return resolve(options.cwd, DEFAULT_DB_REL);
-}
-function defaultProjectDbPath(ctx) {
-  return resolve(ctx.cwd, DEFAULT_DB_REL);
-}
-function defaultProjectJobsDir(ctx) {
-  return resolve(ctx.cwd, SKILL_MAP_DIR, JOBS_DIRNAME);
-}
-function defaultProjectPluginsDir(ctx) {
-  return resolve(ctx.cwd, SKILL_MAP_DIR, PLUGINS_DIRNAME);
-}
-function defaultUserPluginsDir(ctx) {
-  return join(ctx.homedir, SKILL_MAP_DIR, PLUGINS_DIRNAME);
-}
-function defaultDbPath(scopeRoot) {
-  return join(scopeRoot, SKILL_MAP_DIR, DB_FILENAME);
-}
-function defaultSettingsPath(scopeRoot) {
-  return join(scopeRoot, SKILL_MAP_DIR, SETTINGS_FILENAME);
-}
-function defaultLocalSettingsPath(scopeRoot) {
-  return join(scopeRoot, SKILL_MAP_DIR, LOCAL_SETTINGS_FILENAME);
-}
-function defaultIgnoreFilePath(scopeRoot) {
-  return join(scopeRoot, IGNORE_FILENAME);
-}
-function assertDbExists(path, stderr) {
-  if (path === ":memory:" || existsSync(path)) return true;
-  stderr.write(tx(UTIL_TEXTS.dbNotFound, { path }));
-  return false;
-}
-
-// cli/util/runtime-context.ts
-import { homedir } from "os";
-function defaultRuntimeContext() {
-  return { cwd: process.cwd(), homedir: homedir() };
-}
-
-// cli/util/exit-codes.ts
-var ExitCode = {
-  Ok: 0,
-  Issues: 1,
-  Error: 2,
-  Duplicate: 3,
-  NonceMismatch: 4,
-  NotFound: 5
-};
-
 // cli/util/plugin-runtime.ts
 import { resolve as resolve8 } from "path";
 
@@ -7028,7 +7178,7 @@ import { Command as Command8, Option as Option8 } from "clipanion";
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.11.1",
+  version: "0.13.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -7540,7 +7690,7 @@ function renderCompactOverview(verbs) {
   return lines.join("\n") + "\n";
 }
 var RootHelpCommand = class extends Command8 {
-  static paths = [["-h"], ["--help"], Command8.Default];
+  static paths = [["-h"], ["--help"]];
   async execute() {
     const rawDefs = this.cli.definitions();
     const verbs = rawDefs.filter((d) => !isBuiltin(d)).map(normalizeDefinition).sort(byPath);
@@ -12503,7 +12653,7 @@ var PLACEHOLDER_HTML = `<!doctype html>
   </head>
   <body>
     <h1>skill-map server is running</h1>
-    <p>The UI bundle was not found. Run <code>npm run build --workspace=ui</code> from the repo root, or pass <code>--ui-dist &lt;path&gt;</code>, then restart <code>sm serve</code>.</p>
+    <p>The UI bundle was not found. If you installed <code>@skill-map/cli</code> from npm, this is a packaging bug \u2014 please report it. If you're developing in the monorepo, run <code>npm run build --workspace=ui</code> from the repo root and restart <code>sm serve</code> (or pass <code>--ui-dist &lt;path&gt;</code> to point at a custom build).</p>
     <p>The REST API is available at <code>/api/health</code>.</p>
   </body>
 </html>
@@ -13109,18 +13259,14 @@ function validateWatcherDebounce(value) {
 // server/paths.ts
 import { existsSync as existsSync17, statSync as statSync5 } from "fs";
 import { dirname as dirname9, isAbsolute as isAbsolute5, join as join14, resolve as resolve19 } from "path";
-var DEFAULT_UI_REL = join14("ui", "dist", "browser");
+import { fileURLToPath as fileURLToPath5 } from "url";
+var DEFAULT_UI_REL = join14("ui", "dist", "ui", "browser");
+var PACKAGE_UI_REL = "ui";
 var INDEX_HTML2 = "index.html";
 function resolveDefaultUiDist(ctx) {
-  let current = resolve19(ctx.cwd);
-  for (let i = 0; i < 64; i++) {
-    const candidate = join14(current, DEFAULT_UI_REL);
-    if (isUiBundleDir(candidate)) return candidate;
-    const parent = dirname9(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-  return null;
+  const bundled = resolvePackageBundledUi();
+  if (bundled !== null) return bundled;
+  return walkUpForUi(ctx.cwd);
 }
 function resolveExplicitUiDist(ctx, raw) {
   return isAbsolute5(raw) ? raw : resolve19(ctx.cwd, raw);
@@ -13134,6 +13280,39 @@ function isUiBundleDir(path) {
     return false;
   }
 }
+function resolvePackageBundledUi() {
+  let here;
+  try {
+    here = dirname9(fileURLToPath5(import.meta.url));
+  } catch {
+    return null;
+  }
+  return resolvePackageBundledUiFrom(here);
+}
+function resolvePackageBundledUiFrom(here) {
+  let current = here;
+  for (let i = 0; i < 8; i++) {
+    const candidate = join14(current, PACKAGE_UI_REL);
+    if (isUiBundleDir(candidate)) return candidate;
+    const distHere = join14(current, "dist", PACKAGE_UI_REL);
+    if (isUiBundleDir(distHere)) return distHere;
+    const parent = dirname9(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  return null;
+}
+function walkUpForUi(startDir) {
+  let current = resolve19(startDir);
+  for (let i = 0; i < 64; i++) {
+    const candidate = join14(current, DEFAULT_UI_REL);
+    if (isUiBundleDir(candidate)) return candidate;
+    const parent = dirname9(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  return null;
+}
 
 // server/index.ts
 async function createServer(options, extra = {}) {
@@ -14064,11 +14243,39 @@ var logLevel = resolveLogLevel({
   errStream: process.stderr
 });
 configureLogger(new Logger({ level: logLevel, stream: process.stderr }));
-var routedArgs = routeHelpArgs(args, cli);
+var bareArgs = args.length === 0 ? resolveBareDefault() : null;
+var routedArgs = routeHelpArgs(bareArgs ?? args, cli);
+try {
+  cli.process(routedArgs, {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr
+  });
+} catch (err) {
+  if (isClipanionParseError(err)) {
+    process.stderr.write(
+      formatParseError({
+        args: routedArgs,
+        verbPaths: registeredVerbPaths(cli),
+        error: err
+      })
+    );
+    process.exit(ExitCode.Error);
+  }
+  throw err;
+}
 var exitCode = await cli.run(routedArgs, {
   stdin: process.stdin,
   stdout: process.stdout,
   stderr: process.stderr
 });
 process.exit(exitCode);
+function resolveBareDefault() {
+  const ctx = defaultRuntimeContext();
+  if (existsSync19(defaultProjectDbPath(ctx))) {
+    return ["serve"];
+  }
+  process.stderr.write(tx(ENTRY_TEXTS.bareNoProject, { cwd: ctx.cwd }));
+  process.exit(ExitCode.Error);
+}
 //# sourceMappingURL=cli.js.map