@skill-map/cli 0.60.4 → 0.61.1

package/dist/cli/tutorial/sm-tutorial/scripts/state.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/**
+ * state.js, the sm-tutorial state engine.
+ *
+ * Owns `tutorial-state.json` entirely; the orchestrating agent calls
+ * these verbs instead of hand-editing the file. Zero-dep, Node 24+,
+ * ESM. This is backstage machinery (same class as `Write`), NOT a
+ * teaching `sm` verb the tester runs.
+ *
+ * Every verb prints ONE JSON line to stdout and exits 0 on success, or
+ * a `{ ok: false, code, error }` envelope with a non-zero exit on
+ * failure. The agent parses stdout.
+ *
+ * Verbs:
+ *   init --cwd <abs> --sm-version <s> --provider <p> --lang <l> [--force]
+ *   pick <partId>
+ *   mark <partId> <chapterId> <done|failed|skipped>
+ *   set-part <partId> <not_started|in_progress|done|declined|skipped>
+ *   set-identity --name <s> --tagline <s>
+ *   status
+ *   wipe-list
+ *   wipe --confirm
+ *
+ * State path is `<cwd>/tutorial-state.json` (cwd = process.cwd()). The
+ * stored `tutorial.cwd` is the safety anchor for wipe.
+ */
+
+import { join } from 'node:path';
+import { rmSync, rmdirSync, readdirSync } from 'node:fs';
+
+import { parseArgs } from './lib/args.js';
+import { exists, readJson, writeJson, succeed, die } from './lib/io.js';
+import { loadManifest, findPart } from './lib/manifest.js';
+import { providerDir } from './lib/paths.js';
+import { loadFixturesManifest, resolveFootprint } from './lib/fixtures-manifest.js';
+
+const STATE_FILE = 'tutorial-state.json';
+const STATE_VERSION = 2;
+const PART_STATUS = new Set(['not_started', 'in_progress', 'done', 'declined', 'skipped']);
+const CHAPTER_STATUS = new Set(['done', 'failed', 'skipped']);
+
+const statePath = () => join(process.cwd(), STATE_FILE);
+const now = () => new Date().toISOString();
+
+function loadState() {
+  const p = statePath();
+  if (!exists(p)) {
+    die('no-state', `${STATE_FILE} not found in ${process.cwd()}; run \`state init\` first.`);
+  }
+  return readJson(p);
+}
+
+function saveState(state) {
+  writeJson(statePath(), state);
+}
+
+function seedPart(manifest, id) {
+  const def = findPart(manifest, id);
+  if (!def) die('unknown-part', `part '${id}' is not in the manifest.`);
+  const chapters = {};
+  for (const ch of def.chapters) chapters[ch.id] = { status: 'pending' };
+  return { status: 'in_progress', chapters };
+}
+
+const VERBS = {
+  init(args) {
+    const p = statePath();
+    if (exists(p) && !args.flags.force) {
+      die('exists', `${STATE_FILE} already exists; pass --force to overwrite.`);
+    }
+    const state = {
+      tutorial: {
+        version: STATE_VERSION,
+        started_at: now(),
+        cwd: args.flags.cwd ?? process.cwd(),
+        sm_version: args.flags['sm-version'] ?? null,
+        provider: args.flags.provider ?? 'claude',
+        lang: args.flags.lang ?? 'en',
+      },
+      tester: { level: 2 },
+      parts: {},
+      findings_file: './findings.md',
+    };
+    saveState(state);
+    succeed({ state });
+  },
+
+  pick(args) {
+    const id = args.positional[0];
+    if (!id) die('bad-args', 'usage: pick <partId>');
+    const state = loadState();
+    const manifest = loadManifest();
+    if (!state.parts[id]) {
+      state.parts[id] = seedPart(manifest, id);
+      saveState(state);
+    }
+    succeed({ part: { id, ...state.parts[id] } });
+  },
+
+  mark(args) {
+    const [id, chapterId, status] = args.positional;
+    if (!id || !chapterId || !status) {
+      die('bad-args', 'usage: mark <partId> <chapterId> <done|failed|skipped>');
+    }
+    if (!CHAPTER_STATUS.has(status)) {
+      die('bad-status', `chapter status must be one of ${[...CHAPTER_STATUS].join(', ')}`);
+    }
+    const state = loadState();
+    const part = state.parts[id];
+    if (!part) die('not-picked', `part '${id}' has not been picked; run \`pick ${id}\` first.`);
+    if (!part.chapters[chapterId]) die('unknown-chapter', `chapter '${chapterId}' not in part '${id}'.`);
+
+    part.chapters[chapterId] = { status, at: now() };
+    const statuses = Object.values(part.chapters).map((c) => c.status);
+    const allDone = !statuses.includes('pending');
+    // Auto-promote the part only on a clean finish (every chapter done
+    // or skipped). A `failed` chapter leaves the part in_progress so the
+    // agent decides how to surface it; `allDone` still reports the walk
+    // is complete.
+    if (allDone && !statuses.includes('failed')) part.status = 'done';
+    saveState(state);
+    succeed({ part: { id, ...part }, allDone });
+  },
+
+  'set-part'(args) {
+    const [id, status] = args.positional;
+    if (!id || !status) die('bad-args', 'usage: set-part <partId> <status>');
+    if (!PART_STATUS.has(status)) {
+      die('bad-status', `part status must be one of ${[...PART_STATUS].join(', ')}`);
+    }
+    const state = loadState();
+    const manifest = loadManifest();
+    if (!state.parts[id]) state.parts[id] = seedPart(manifest, id);
+    state.parts[id].status = status;
+    saveState(state);
+    succeed({ part: { id, ...state.parts[id] } });
+  },
+
+  'set-identity'(args) {
+    const { name, tagline } = args.flags;
+    if (!name || !tagline) die('bad-args', 'usage: set-identity --name <s> --tagline <s>');
+    const state = loadState();
+    state.tester.site_identity = { name: String(name), tagline: String(tagline) };
+    saveState(state);
+    succeed({ site_identity: state.tester.site_identity });
+  },
+
+  status() {
+    const state = loadState();
+    const manifest = loadManifest();
+    const parts = manifest.parts
+      .filter((p) => p.status === 'active' || state.parts[p.id])
+      .map((p) => {
+        const tracked = state.parts[p.id];
+        return {
+          id: p.id,
+          title: p.title,
+          order: p.order,
+          status: tracked?.status ?? 'not_started',
+          chapters: p.chapters.map((c) => ({
+            id: c.id,
+            title: c.title,
+            status: tracked?.chapters?.[c.id]?.status ?? 'pending',
+          })),
+        };
+      });
+    succeed({ tutorial: state.tutorial, tester: state.tester, parts });
+  },
+
+  'wipe-list'() {
+    const state = loadState();
+    const guard = cwdGuard(state);
+    if (guard) die(guard.code, guard.error);
+    succeed({ cwd: state.tutorial.cwd, paths: computeWipePaths(state) });
+  },
+
+  wipe(args) {
+    if (!args.flags.confirm) {
+      die('confirm-required', 'pass --confirm to delete; use `wipe-list` to preview.');
+    }
+    const state = loadState();
+    const guard = cwdGuard(state);
+    if (guard) die(guard.code, guard.error);
+    const deleted = [];
+    for (const rel of computeWipePaths(state)) {
+      const abs = join(process.cwd(), rel);
+      if (exists(abs)) {
+        rmSync(abs, { recursive: true, force: true });
+        deleted.push(rel);
+      }
+    }
+    rmdirEmptyParents(state);
+    succeed({ deleted });
+  },
+};
+
+function cwdGuard(state) {
+  const stored = state.tutorial?.cwd;
+  if (stored && stored !== process.cwd()) {
+    return {
+      code: 'cwd-mismatch',
+      error: `state cwd (${stored}) != current dir (${process.cwd()}); refusing. Move to the saved dir or delete ${STATE_FILE} by hand.`,
+    };
+  }
+  return null;
+}
+
+/**
+ * The exact paths to remove on start-over, derived from which parts the
+ * state records as run. The per-fixture footprints (the on-disk reach
+ * of each fixture, including files taught later in its chapters) live
+ * once in `fixtures-data/manifest.json` and are shared with
+ * `fixtures.js clear`; here we union the footprints of the tracked
+ * parts with the universals. Never lists a bare user dir (`notes/`);
+ * empty parents are rmdir'd afterwards.
+ */
+function computeWipePaths(state) {
+  const provider = state.tutorial?.provider ?? 'claude';
+  const has = (id) => Boolean(state.parts?.[id]);
+  const manifest = loadFixturesManifest();
+  const paths = new Set(['tutorial-state.json', 'findings.md', '.skillmapignore', '.skill-map']);
+  const addFootprint = (name) => resolveFootprint(manifest, name, provider).forEach((p) => paths.add(p));
+
+  if (has('fundamentals')) addFootprint('prologue');
+  if (has('project-kickoff') || has('connect-harness') || has('daily-loop')) addFootprint('portfolio');
+  if (has('extend')) addFootprint('master');
+  // `cli` seeds the prologue demo fixture plus its external-ref demo.
+  if (has('cli')) { addFootprint('prologue'); addFootprint('cli-external'); }
+
+  try {
+    for (const entry of readdirSync(process.cwd())) {
+      if (/^export\./.test(entry) || entry === 'dump.sql') paths.add(entry);
+    }
+  } catch { /* cwd unreadable, skip the glob */ }
+
+  return [...paths];
+}
+
+function rmdirEmptyParents(state) {
+  const pd = providerDir(state.tutorial?.provider ?? 'claude');
+  // Children before parents; `rmdirSync` only removes empty dirs, so the
+  // tutorial's own skill dir under `<pd>/skills/` keeps `<pd>` alive.
+  const candidates = ['notes', 'docs', 'public', `${pd}/agents`, `${pd}/skills`, `${pd}/commands`, pd];
+  for (const rel of candidates) {
+    try {
+      rmdirSync(join(process.cwd(), rel));
+    } catch { /* not empty or missing, leave it */ }
+  }
+}
+
+function main() {
+  const [verb, ...rest] = process.argv.slice(2);
+  const handler = VERBS[verb];
+  if (!handler) {
+    die('unknown-verb', `unknown verb '${verb ?? ''}'; expected one of ${Object.keys(VERBS).join(', ')}`);
+  }
+  handler(parseArgs(rest));
+}
+
+main();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="547a8c8d-f962-571c-ae72-8edbb1fc756c")}catch(e){}}();
+//# debugId=547a8c8d-f962-571c-ae72-8edbb1fc756c

package/dist/cli.js

@@ -1,6 +1,6 @@
 // cli/entry.ts
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a3a95cfb-0211-5740-8f29-a22970fcc2b6")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9a536139-6f70-53a7-b32a-eed4fc49b7a4")}catch(e){}}();
 import { existsSync as existsSync33 } from "fs";
 import { Builtins, Cli as Cli2 } from "clipanion";
 
@@ -250,7 +250,7 @@ function bucketByKind(kind, instance, bag) {
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.60.4",
+  version: "0.61.1",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -305,9 +305,11 @@ var package_default = {
     "built-ins:check": "node ../scripts/generate-built-ins.js --check",
     "view-catalog": "node ../scripts/generate-view-catalog.js",
     "view-catalog:check": "node ../scripts/generate-view-catalog.js --check",
+    "tutorial-manifest": "node scripts/generate-tutorial-manifest.js",
+    "tutorial-manifest:check": "node scripts/generate-tutorial-manifest.js --check",
     prebuild: "pnpm build-built-ins",
     validate: "pnpm validate:compile && pnpm validate:test",
-    "validate:compile": "pnpm typecheck && pnpm lint && pnpm build && pnpm built-ins:check && pnpm view-catalog:check",
+    "validate:compile": "pnpm typecheck && pnpm lint && pnpm build && pnpm built-ins:check && pnpm view-catalog:check && pnpm tutorial-manifest:check",
     "validate:test": "pnpm test:ci && pnpm conformance",
     conformance: "SKILL_MAP_TELEMETRY=0 SM_NO_UPDATE_CHECK=1 node --import tsx cli/entry.ts conformance run",
     pretest: "tsup",
@@ -30861,21 +30863,19 @@ var VersionCommand = class extends SmCommand {
   static paths = [["version"]];
   static usage = Command39.Usage({
     category: "Introspection",
-    description: "Print the CLI / kernel / spec / runtime / db-schema version matrix."
+    description: "Print the CLI / spec / runtime / db-schema version matrix."
   });
   // Informational verb, no `done in <…>` line; the version matrix is
   // the entire output.
   emitElapsed = false;
   async run() {
     const runtime = `Node ${process.version}`;
-    const kernelVersion = VERSION;
     const specVersion = await resolveSpecVersion3();
     const dbSchema = await resolveDbSchemaVersion();
     const dev = isDevBuild();
     if (this.json) {
       const payload = {
         sm: VERSION,
-        kernel: kernelVersion,
         spec: specVersion,
         dbSchema
       };
@@ -30887,7 +30887,6 @@ var VersionCommand = class extends SmCommand {
     const smValue = dev ? `${VERSION} ${ansi.yellow("[dev]")}` : VERSION;
     const lines = [
       ["sm", smValue],
-      ["kernel", kernelVersion],
       ["spec", specVersion],
       ["runtime", runtime],
       ["db-schema", dbSchema]
@@ -31058,4 +31057,4 @@ function resolveBareDefault() {
   process.exit(ExitCode.Error);
 }
 //# sourceMappingURL=cli.js.map
-//# debugId=a3a95cfb-0211-5740-8f29-a22970fcc2b6
+//# debugId=9a536139-6f70-53a7-b32a-eed4fc49b7a4

package/dist/index.js

@@ -1,6 +1,6 @@
 // kernel/i18n/registry.texts.ts
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b9788d58-3cfb-5087-85e4-ffa9b13dd658")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3bc6390b-70e8-568a-835e-870172658869")}catch(e){}}();
 var REGISTRY_TEXTS = {
   duplicateExtension: "Extension already registered: {{kind}}:{{qualifiedId}}",
   unknownKind: "Unknown extension kind: {{kind}}",
@@ -102,7 +102,7 @@ import { Tiktoken as Tiktoken2 } from "js-tiktoken/lite";
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.60.4",
+  version: "0.61.1",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -157,9 +157,11 @@ var package_default = {
     "built-ins:check": "node ../scripts/generate-built-ins.js --check",
     "view-catalog": "node ../scripts/generate-view-catalog.js",
     "view-catalog:check": "node ../scripts/generate-view-catalog.js --check",
+    "tutorial-manifest": "node scripts/generate-tutorial-manifest.js",
+    "tutorial-manifest:check": "node scripts/generate-tutorial-manifest.js --check",
     prebuild: "pnpm build-built-ins",
     validate: "pnpm validate:compile && pnpm validate:test",
-    "validate:compile": "pnpm typecheck && pnpm lint && pnpm build && pnpm built-ins:check && pnpm view-catalog:check",
+    "validate:compile": "pnpm typecheck && pnpm lint && pnpm build && pnpm built-ins:check && pnpm view-catalog:check && pnpm tutorial-manifest:check",
     "validate:test": "pnpm test:ci && pnpm conformance",
     conformance: "SKILL_MAP_TELEMETRY=0 SM_NO_UPDATE_CHECK=1 node --import tsx cli/entry.ts conformance run",
     pretest: "tsup",
@@ -3845,4 +3847,4 @@ export {
   runScanWithRenames
 };
 //# sourceMappingURL=index.js.map
-//# debugId=b9788d58-3cfb-5087-85e4-ffa9b13dd658
+//# debugId=3bc6390b-70e8-568a-835e-870172658869

package/dist/kernel/index.js

@@ -1,6 +1,6 @@
 // kernel/i18n/registry.texts.ts
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="87952569-58dc-5c27-9436-d46ca8ea5fab")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1b30d8c8-edea-5922-be87-39c4ebe079c0")}catch(e){}}();
 var REGISTRY_TEXTS = {
   duplicateExtension: "Extension already registered: {{kind}}:{{qualifiedId}}",
   unknownKind: "Unknown extension kind: {{kind}}",
@@ -102,7 +102,7 @@ import { Tiktoken as Tiktoken2 } from "js-tiktoken/lite";
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.60.4",
+  version: "0.61.1",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -157,9 +157,11 @@ var package_default = {
     "built-ins:check": "node ../scripts/generate-built-ins.js --check",
     "view-catalog": "node ../scripts/generate-view-catalog.js",
     "view-catalog:check": "node ../scripts/generate-view-catalog.js --check",
+    "tutorial-manifest": "node scripts/generate-tutorial-manifest.js",
+    "tutorial-manifest:check": "node scripts/generate-tutorial-manifest.js --check",
     prebuild: "pnpm build-built-ins",
     validate: "pnpm validate:compile && pnpm validate:test",
-    "validate:compile": "pnpm typecheck && pnpm lint && pnpm build && pnpm built-ins:check && pnpm view-catalog:check",
+    "validate:compile": "pnpm typecheck && pnpm lint && pnpm build && pnpm built-ins:check && pnpm view-catalog:check && pnpm tutorial-manifest:check",
     "validate:test": "pnpm test:ci && pnpm conformance",
     conformance: "SKILL_MAP_TELEMETRY=0 SM_NO_UPDATE_CHECK=1 node --import tsx cli/entry.ts conformance run",
     pretest: "tsup",
@@ -3845,4 +3847,4 @@ export {
   runScanWithRenames
 };
 //# sourceMappingURL=index.js.map
-//# debugId=87952569-58dc-5c27-9436-d46ca8ea5fab
+//# debugId=1b30d8c8-edea-5922-be87-39c4ebe079c0