@skill-map/cli 0.15.0 → 0.16.0

package/README.md

@@ -25,6 +25,22 @@ npx @skill-map/cli --version
 
 Both `sm` (short, daily use) and `skill-map` (full name, scripts) are registered as binaries after install. The package name is scoped (`@skill-map/cli`) to sit alongside `@skill-map/spec` under the same npm org; the binaries keep the unprefixed names for ergonomics.
 
+## Interactive tutorial (recommended starting point)
+
+If you use [Claude Code](https://claude.ai/code), `sm tutorial` is the fastest way to learn the CLI and the live UI without committing your real project to anything:
+
+```bash
+mkdir try-skill-map && cd try-skill-map
+sm tutorial                  # writes sm-tutorial.md into the empty dir
+claude                       # open Claude Code in the same dir
+# Inside Claude:
+ejecutá @sm-tutorial.md
+```
+
+Claude loads the SKILL.md and runs the demo (~7 min): fixture, `sm init`, live UI, four "reveals" that show the watcher in action, plus the `.skillmapignore` hide-a-file flow. An optional deep-dive (~30-40 min) covers the rest of the CLI surface (`list`, `graph`, `export`, `orphans`, `plugins`, `db ops`).
+
+The verb `sm tutorial` writes a single self-contained file; the SKILL.md ships inside this package, so no extra install needed.
+
 ## Usage
 
 ```bash

package/dist/cli/tutorial/sm-tutorial.md

@@ -349,7 +349,7 @@ Mark `1-version: done`.
 
 **Context**: `sm init` creates a hidden `.skill-map/` folder in the
 cwd holding the database where skill-map stores what it learns about
-the project. It also drops a `.skill-mapignore` in the cwd with
+the project. It also drops a `.skillmapignore` in the cwd with
 default exclusions. Mandatory first step.
 
 ```bash
@@ -358,10 +358,10 @@ ls -la .skill-map/
 ```
 
 Expected: `.skill-map/skill-map.db` appears (plus config files), and
-a `.skill-mapignore` shows up at the root.
+a `.skillmapignore` shows up at the root.
 
 **After init**, you append the tutorial's entries to the
-`.skill-mapignore` that `sm init` just created (do not create a new
+`.skillmapignore` that `sm init` just created (do not create a new
 file — append to the existing one with `Edit`). This prevents
 `sm scan` from picking up the tutorial's internal files as graph nodes:
 
@@ -605,8 +605,76 @@ Tell the tester:
 > Confirmá / confirm. If a connector is missing, refresh the
 > browser and tell me.
 
-Once they confirm, ask them to stop the server with **Ctrl+C** in
-the terminal before continuing.
+Wait for confirmation. **Do NOT move on to Reveal 4** until the
+connectors are confirmed visible — Reveal 4 reuses the same live UI
+session.
+
+#### Reveal 4 — silence a private file via `.skillmapignore`
+
+The first three reveals showed the watcher picking up new files and
+edits. Reveal 4 flips the direction: a file the tester DOES NOT want
+in the graph (a draft, a scratch file, a secret) gets hidden by a
+single line in `.skillmapignore`. Same live mechanism — no restart.
+
+`sm init` already wrote a starter `.skillmapignore` at the scope
+root. The tester edits that file plus creates one new fixture node:
+
+1. Create (`Write`) `notes/private-credentials.md` — kind `note`,
+   simulates a file the tester would never want surfacing publicly:
+   ```markdown
+   ---
+   name: private-credentials
+   description: |
+     Personal API tokens — exists in the repo but should not show
+     up in the skill-map graph. Demonstrates the .skillmapignore
+     flow.
+   metadata:
+     version: "0.0.1"
+   ---
+
+   # Private
+
+   API_TOKEN: example-not-real
+   ```
+
+2. Confirm the file appears in the graph as a sixth node
+   (`notes/private-credentials`). The watcher sees it like any
+   other `.md` — that's the point of the demo.
+
+3. Edit (`Edit`) `.skillmapignore` and append a single new line at
+   the end:
+   ```
+   notes/private-*.md
+   ```
+   (Pattern syntax mirrors `.gitignore` — kaelzhang's `ignore`
+   under the hood. A literal path like `notes/private-credentials.md`
+   would also work; the glob teaches the broader habit.)
+
+4. Confirm the node disappears from the graph in the browser, no
+   refresh needed. Six nodes back to five.
+
+Tell the tester:
+
+> Última magia / one last trick: skill-map stops tracking a file
+> the moment it matches a pattern in `.skillmapignore`. No restart
+> needed — same watcher, opposite direction.
+>
+> Two steps:
+>
+> 1. Create `notes/private-credentials.md` with the content I'll
+>    paste → a new node appears on the graph (watcher magic again,
+>    expected).
+> 2. Open `.skillmapignore` and append `notes/private-*.md` on a
+>    new line → the node disappears from the graph.
+>
+> Use this whenever you have drafts, scratch files, or anything
+> you don't want surfacing in the map. Syntax is the same as
+> `.gitignore`: globs, `!pattern` to re-include, `#` for comments.
+>
+> Did the node vanish?
+
+Wait for confirmation. Once they confirm, ask them to stop the
+server with **Ctrl+C** in the terminal before continuing.
 
 Mark `3-ui-live: done`.
 
@@ -845,7 +913,7 @@ the cwd, start like this (do NOT repeat pre-flight from scratch):
 
 If they pick "start over", confirm explicitly. Only after
 confirmation, delete the tutorial files in the cwd
-(`tutorial-state.yml`, `findings.md`, `.skill-mapignore`, `.claude/`,
+(`tutorial-state.yml`, `findings.md`, `.skillmapignore`, `.claude/`,
 `notes/`, `.skill-map/`, and any `export.*`, `dump.sql`, or
 `sm-tutorial-report.md` that may have been left behind) and start
 everything from pre-flight.

package/dist/cli.js

@@ -225,7 +225,7 @@ 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 IGNORE_FILENAME = ".skillmapignore";
 var DEFAULT_DB_REL = `${SKILL_MAP_DIR}/${DB_FILENAME}`;
 var GITIGNORE_ENTRIES = [
   `${SKILL_MAP_DIR}/${LOCAL_SETTINGS_FILENAME}`,
@@ -609,7 +609,7 @@ function loadBundledIgnoreText() {
   return loadDefaultsText();
 }
 function readIgnoreFileText(scopeRoot) {
-  const path = resolve2(scopeRoot, ".skill-mapignore");
+  const path = resolve2(scopeRoot, ".skillmapignore");
   if (!existsSync2(path)) return void 0;
   try {
     return readFileSync(path, "utf8");
@@ -626,11 +626,11 @@ function loadDefaultsText() {
 function readDefaultsFromDisk() {
   const here = dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    resolve2(here, "../../config/defaults/skill-mapignore"),
+    resolve2(here, "../../config/defaults/skillmapignore"),
     // src/kernel/scan/ → src/config/defaults/
-    resolve2(here, "../config/defaults/skill-mapignore"),
+    resolve2(here, "../config/defaults/skillmapignore"),
     // dist/cli.js → dist/config/defaults/ (siblings)
-    resolve2(here, "config/defaults/skill-mapignore")
+    resolve2(here, "config/defaults/skillmapignore")
   ];
   for (const candidate of candidates) {
     if (existsSync2(candidate)) {
@@ -2958,7 +2958,7 @@ var AsyncMutex = class {
       this.#locked = true;
       return;
     }
-    await new Promise((resolve21) => this.#waiters.push(resolve21));
+    await new Promise((resolve23) => this.#waiters.push(resolve23));
     this.#locked = true;
   }
   unlock() {
@@ -7362,7 +7362,7 @@ import { Command as Command8, Option as Option8 } from "clipanion";
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.15.0",
+  version: "0.16.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -7421,7 +7421,7 @@ var package_default = {
   },
   dependencies: {
     "@hono/node-server": "2.0.1",
-    "@skill-map/spec": "0.15.0",
+    "@skill-map/spec": "0.16.0",
     ajv: "8.18.0",
     "ajv-formats": "3.0.1",
     chokidar: "5.0.0",
@@ -8850,11 +8850,14 @@ import { resolve as resolve14, relative as relative4, sep as sep2 } from "path";
 import chokidar from "chokidar";
 function createChokidarWatcher(opts) {
   const absRoots = opts.roots.map((r) => resolve14(opts.cwd, r));
-  const ignoreFilter = opts.ignoreFilter;
-  const ignored = ignoreFilter ? (path) => {
+  const ignoreFilterOpt = opts.ignoreFilter;
+  const getFilter = ignoreFilterOpt === void 0 ? void 0 : typeof ignoreFilterOpt === "function" ? ignoreFilterOpt : () => ignoreFilterOpt;
+  const ignored = getFilter ? (path) => {
+    const filter = getFilter();
+    if (!filter) return false;
     const rel = relativePathFromRoots(path, absRoots);
     if (rel === null) return false;
-    return ignoreFilter.ignores(rel);
+    return filter.ignores(rel);
   } : void 0;
   const watcher = chokidar.watch(absRoots, {
     ignoreInitial: true,
@@ -9101,7 +9104,7 @@ var InitCommand = class extends SmCommand {
     details: `
       Project scope (default): creates ./.skill-map/ with settings.json,
       settings.local.json, and skill-map.db. Drops a starter
-      .skill-mapignore at the scope root and appends the DB + local
+      .skillmapignore at the scope root and appends the DB + local
       settings to .gitignore.
 
       Global scope (-g): same scaffolding under ~/.skill-map/. No
@@ -9123,7 +9126,7 @@ var InitCommand = class extends SmCommand {
     description: "Skip the first scan after scaffolding."
   });
   force = Option9.Boolean("--force", false, {
-    description: "Overwrite an existing settings.json / settings.local.json / .skill-mapignore."
+    description: "Overwrite an existing settings.json / settings.local.json / .skillmapignore."
   });
   strict = Option9.Boolean("--strict", false, {
     description: "Strict mode: fail on any layered-loader warning AND promote frontmatter warnings to errors during the first scan. Same flag as sm scan / sm config."
@@ -11563,6 +11566,7 @@ async function runEphemeralPath(opts, dbPath, strict, loadPrior, runScanWith) {
 }
 
 // cli/commands/watch.ts
+import { resolve as resolve19 } from "path";
 import { Command as Command16, Option as Option16 } from "clipanion";
 
 // cli/i18n/watch.texts.ts
@@ -11586,20 +11590,24 @@ async function runWatchLoop(opts) {
   const { context } = opts;
   const runtimeCtx = defaultRuntimeContext();
   const { cwd } = runtimeCtx;
+  const loadEffectiveConfig = () => loadConfig({ scope: "project", strict: opts.strict, ...runtimeCtx }).effective;
+  const buildCurrentIgnoreFilter = (cfgIn) => {
+    const text = readIgnoreFileText(cwd);
+    const filterOpts = {};
+    if (cfgIn.ignore.length > 0) filterOpts.configIgnore = cfgIn.ignore;
+    if (text !== void 0) filterOpts.ignoreFileText = text;
+    return buildIgnoreFilter(filterOpts);
+  };
   let cfg;
   try {
-    cfg = loadConfig({ scope: "project", strict: opts.strict, ...runtimeCtx }).effective;
+    cfg = loadEffectiveConfig();
   } catch (err) {
     const message = formatErrorMessage(err);
     context.stderr.write(tx(WATCH_TEXTS.configLoadFailure, { message }));
     return ExitCode.Error;
   }
-  const ignoreFileText = readIgnoreFileText(cwd);
-  const ignoreFilterOpts = {};
-  if (cfg.ignore.length > 0) ignoreFilterOpts.configIgnore = cfg.ignore;
-  if (ignoreFileText !== void 0) ignoreFilterOpts.ignoreFileText = ignoreFileText;
-  const ignoreFilter = buildIgnoreFilter(ignoreFilterOpts);
-  const strict = opts.strict || cfg.scan.strict === true;
+  let ignoreFilter = buildCurrentIgnoreFilter(cfg);
+  let strict = opts.strict || cfg.scan.strict === true;
   const debounceMs = cfg.scan.watch.debounceMs;
   const dbPath = defaultProjectDbPath(runtimeCtx);
   const pluginRuntime = opts.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: "project" });
@@ -11708,7 +11716,11 @@ async function runWatchLoop(opts) {
     roots: opts.roots,
     cwd,
     debounceMs,
-    ignoreFilter,
+    // Pass a getter, NOT the filter directly: the meta-file watcher
+    // below mutates `ignoreFilter` after a `.skillmapignore` /
+    // `.skill-map/settings.json` edit, and chokidar's `ignored`
+    // predicate must read the current value on every event.
+    ignoreFilter: () => ignoreFilter,
     onBatch: async () => {
       const next = await handleBatch();
       if (next === "stop") {
@@ -11720,6 +11732,29 @@ async function runWatchLoop(opts) {
       context.stderr.write(tx(WATCH_TEXTS.watcherError, { message: err.message }));
     }
   });
+  const metaWatcher = createChokidarWatcher({
+    roots: [
+      resolve19(cwd, ".skillmapignore"),
+      resolve19(cwd, ".skill-map", "settings.json")
+    ],
+    cwd,
+    debounceMs,
+    onBatch: async () => {
+      if (stopRequested) return;
+      try {
+        cfg = loadEffectiveConfig();
+        ignoreFilter = buildCurrentIgnoreFilter(cfg);
+        strict = opts.strict || cfg.scan.strict === true;
+        await handleBatch();
+      } catch (err) {
+        const message = formatErrorMessage(err);
+        context.stderr.write(tx(WATCH_TEXTS.batchFailed, { message }));
+      }
+    },
+    onError: (err) => {
+      context.stderr.write(tx(WATCH_TEXTS.watcherError, { message: err.message }));
+    }
+  });
   const onSignal = () => {
     if (stopRequested) return;
     stopRequested = true;
@@ -11728,12 +11763,14 @@ async function runWatchLoop(opts) {
   process.once("SIGINT", onSignal);
   process.once("SIGTERM", onSignal);
   await watcher.ready;
+  await metaWatcher.ready;
   if (!opts.json) {
     context.stderr.write(WATCH_TEXTS.ready);
   }
   await stopped;
   process.removeListener("SIGINT", onSignal);
   process.removeListener("SIGTERM", onSignal);
+  await metaWatcher.close();
   await watcher.close();
   if (!opts.json) {
     context.stderr.write(tx(WATCH_TEXTS.stopped, { batchCount }));
@@ -11748,7 +11785,7 @@ var WatchCommand = class extends SmCommand {
     details: `
       Long-running version of 'sm scan --changed'. Subscribes to the
       given roots via chokidar, applies the same ignore chain
-      (.skill-mapignore + config.ignore + bundled defaults), and
+      (.skillmapignore + config.ignore + bundled defaults), and
       triggers an incremental scan after each debounced batch.
 
       Default debounce is 300ms; configure via 'scan.watch.debounceMs'
@@ -13166,6 +13203,9 @@ function buildKindRegistry(providers) {
   return registry;
 }
 
+// server/watcher.ts
+import { resolve as resolve20 } from "path";
+
 // server/events.ts
 function buildWatcherStartedEvent(data) {
   return {
@@ -13188,18 +13228,24 @@ function buildWatcherErrorEvent(data) {
 var WATCH_ROOT = ".";
 function createWatcherService(opts) {
   let chokidarHandle = null;
+  let metaHandle = null;
   let stopped = false;
   const start = async () => {
-    const cfg = loadConfig({
+    const cwd = opts.runtimeContext.cwd;
+    const loadEffectiveConfig = () => loadConfig({
       scope: opts.options.scope,
-      cwd: opts.runtimeContext.cwd,
+      cwd,
       homedir: opts.runtimeContext.homedir
     }).effective;
-    const ignoreFileText = readIgnoreFileText(opts.runtimeContext.cwd);
-    const ignoreFilterOpts = {};
-    if (cfg.ignore.length > 0) ignoreFilterOpts.configIgnore = cfg.ignore;
-    if (ignoreFileText !== void 0) ignoreFilterOpts.ignoreFileText = ignoreFileText;
-    const ignoreFilter = buildIgnoreFilter(ignoreFilterOpts);
+    const buildCurrentIgnoreFilter = (cfgIn) => {
+      const ignoreFileText = readIgnoreFileText(cwd);
+      const filterOpts = {};
+      if (cfgIn.ignore.length > 0) filterOpts.configIgnore = cfgIn.ignore;
+      if (ignoreFileText !== void 0) filterOpts.ignoreFileText = ignoreFileText;
+      return buildIgnoreFilter(filterOpts);
+    };
+    let cfg = loadEffectiveConfig();
+    let ignoreFilter = buildCurrentIgnoreFilter(cfg);
     const debounceMs = opts.debounceMsOverride ?? cfg.scan.watch.debounceMs;
     const pluginRuntime = opts.options.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: opts.options.scope });
     for (const warn of pluginRuntime.warnings) {
@@ -13230,7 +13276,12 @@ function createWatcherService(opts) {
       roots: [WATCH_ROOT],
       cwd: opts.runtimeContext.cwd,
       debounceMs,
-      ignoreFilter,
+      // Pass a getter, NOT the filter directly: the meta-file watcher
+      // below mutates `ignoreFilter` after a `.skillmapignore` /
+      // `.skill-map/settings.json` edit, and chokidar's `ignored`
+      // predicate must read the current value on every event. See
+      // `kernel/scan/watcher.ts` for the supported shapes.
+      ignoreFilter: () => ignoreFilter,
       onBatch: async () => {
         if (stopped) return;
         try {
@@ -13257,6 +13308,42 @@ function createWatcherService(opts) {
     if ("ready" in chokidarHandle && chokidarHandle.ready instanceof Promise) {
       await chokidarHandle.ready;
     }
+    metaHandle = createChokidarWatcher({
+      roots: [
+        resolve20(cwd, ".skillmapignore"),
+        resolve20(cwd, ".skill-map", "settings.json")
+      ],
+      cwd,
+      debounceMs,
+      // No `ignoreFilter` — these specific paths must always be observed,
+      // regardless of any user pattern.
+      onBatch: async () => {
+        if (stopped) return;
+        try {
+          cfg = loadEffectiveConfig();
+          ignoreFilter = buildCurrentIgnoreFilter(cfg);
+          await runOneBatch();
+        } catch (err) {
+          const message = formatErrorMessage(err);
+          log.warn(
+            tx(SERVER_TEXTS.watcherBatchFailed, {
+              message: sanitizeForTerminal(message)
+            })
+          );
+        }
+      },
+      onError: (err) => {
+        const message = err.message;
+        log.warn(
+          tx(SERVER_TEXTS.watcherError, {
+            message: sanitizeForTerminal(message)
+          })
+        );
+      }
+    });
+    if ("ready" in metaHandle && metaHandle.ready instanceof Promise) {
+      await metaHandle.ready;
+    }
     await runInitialBatch({ isStopped: () => stopped, runOneBatch });
     opts.broadcaster.broadcast(
       buildWatcherStartedEvent({ roots: [WATCH_ROOT], debounceMs })
@@ -13271,19 +13358,23 @@ function createWatcherService(opts) {
   const stop = async () => {
     if (stopped) return;
     stopped = true;
-    if (chokidarHandle) {
+    const closeQuietly = async (handle, label) => {
+      if (!handle) return;
       try {
-        await chokidarHandle.close();
+        await handle.close();
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         log.warn(
           tx(SERVER_TEXTS.watcherCloseFailed, {
-            message: sanitizeForTerminal(message)
+            message: sanitizeForTerminal(`${label}: ${message}`)
           })
         );
       }
-      chokidarHandle = null;
-    }
+    };
+    await closeQuietly(metaHandle, "meta-watcher");
+    metaHandle = null;
+    await closeQuietly(chokidarHandle, "primary");
+    chokidarHandle = null;
   };
   return { start, stop };
 }
@@ -13458,7 +13549,7 @@ 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";
+import { dirname as dirname9, isAbsolute as isAbsolute5, join as join14, resolve as resolve21 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 var DEFAULT_UI_REL = join14("ui", "dist", "ui", "browser");
 var PACKAGE_UI_REL = "ui";
@@ -13469,7 +13560,7 @@ function resolveDefaultUiDist(ctx) {
   return walkUpForUi(ctx.cwd);
 }
 function resolveExplicitUiDist(ctx, raw) {
-  return isAbsolute5(raw) ? raw : resolve19(ctx.cwd, raw);
+  return isAbsolute5(raw) ? raw : resolve21(ctx.cwd, raw);
 }
 function isUiBundleDir(path) {
   if (!existsSync17(path)) return false;
@@ -13503,7 +13594,7 @@ function resolvePackageBundledUiFrom(here) {
   return null;
 }
 function walkUpForUi(startDir) {
-  let current = resolve19(startDir);
+  let current = resolve21(startDir);
   for (let i = 0; i < 64; i++) {
     const candidate = join14(current, DEFAULT_UI_REL);
     if (isUiBundleDir(candidate)) return candidate;
@@ -14467,7 +14558,7 @@ var STUB_COMMANDS = [
 // cli/commands/tutorial.ts
 import { existsSync as existsSync19, readFileSync as readFileSync12 } from "fs";
 import { writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname10, join as join15, resolve as resolve20 } from "path";
+import { dirname as dirname10, join as join15, resolve as resolve22 } from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
 import { Command as Command22, Option as Option22 } from "clipanion";
 
@@ -14543,11 +14634,11 @@ function readTutorialFromDisk() {
   const here = dirname10(fileURLToPath6(import.meta.url));
   const candidates = [
     // dev: src/cli/commands/ → repo-root .claude/skills/sm-tutorial/SKILL.md
-    resolve20(here, "../../../.claude/skills/sm-tutorial/SKILL.md"),
+    resolve22(here, "../../../.claude/skills/sm-tutorial/SKILL.md"),
     // bundled: dist/cli.js → dist/cli/tutorial/sm-tutorial.md (sibling)
-    resolve20(here, "cli/tutorial/sm-tutorial.md"),
+    resolve22(here, "cli/tutorial/sm-tutorial.md"),
     // bundled fallback: any-depth → cli/tutorial/sm-tutorial.md
-    resolve20(here, "../cli/tutorial/sm-tutorial.md")
+    resolve22(here, "../cli/tutorial/sm-tutorial.md")
   ];
   for (const candidate of candidates) {
     if (existsSync19(candidate)) {