@skill-map/cli 0.3.1

package/README.md

@@ -0,0 +1,54 @@
+# 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).
+
+**Status**: pre-MVP / preview release. Steps 0a (spec), 0b (kernel shell), 0c (UI prototype), 1a-1c (kernel + registry + orchestrator), 2 (first extensions), and 3 (UI design refinement) are complete; the CLI currently exposes `sm scan` as a stub (full scan lands at Step 4). See [`ROADMAP.md`](../ROADMAP.md) for the full execution plan and the canonical completeness marker. Subsequent versions follow the standard changeset flow.
+
+## Requirements
+
+- **Node.js ≥ 24.0** (active LTS since October 2025). Older versions are unsupported.
+- Any platform Node 24 supports (Linux, macOS, Windows).
+
+`skill-map` checks the runtime version at the first `sm` invocation and exits with a human-readable message if Node is too old — no silent partial runs.
+
+If your system is on Node 22 or 20, install the latest LTS from [nodejs.org](https://nodejs.org) (or via `nvm`, `fnm`, `volta`, …) before installing this package.
+
+## Install
+
+```bash
+# Global
+npm install --global @skill-map/cli
+
+# Or run without installing
+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.
+
+## Usage
+
+```bash
+sm --version                    # single-line version
+sm version                      # multi-line matrix (sm / kernel / spec / runtime / db-schema)
+sm --help                       # top-level help
+sm scan [roots...] [--json]     # stub in 0b; full scan in Step 4
+```
+
+Exit codes follow [`spec/cli-contract.md`](../spec/cli-contract.md):
+
+| Code | Meaning |
+|---|---|
+| `0` | OK |
+| `1` | Issues found at error severity |
+| `2` | Operational error (bad flags, missing DB, unreadable file, runtime too old) |
+| `3` | Duplicate job conflict |
+| `4` | Nonce mismatch |
+| `5` | Resource not found |
+
+## Spec
+
+This binary implements the [skill-map spec](https://www.npmjs.com/package/@skill-map/spec). The spec package ships JSON Schemas, conformance cases, and prose contracts; `skill-map` conforms to a declared range via its `specCompat`.
+
+## License
+
+MIT. See [`LICENSE`](../LICENSE).

package/bin/sm.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Runtime guard — fail fast with a human message before importing anything
+// that uses Node 24 APIs (node:sqlite stable, built-in WebSocket, modern
+// ESM loader). Without this, a user on Node 20/22 gets an obscure
+// SyntaxError or "module not found" instead of guidance.
+const [major] = process.versions.node.split('.').map(Number);
+if (major < 24) {
+  process.stderr.write(
+`skill-map requires Node.js >= 24 (found v${process.versions.node}).
+
+Node 24 is the active LTS since October 2025 and brings:
+  - stable node:sqlite (used for the skill-map database)
+  - built-in WebSocket client
+  - modern ESM loader
+
+Install the latest LTS from https://nodejs.org and retry.
+`,
+  );
+  process.exit(2);
+}
+
+import('../dist/cli.js').catch((err) => {
+  process.stderr.write(`sm: failed to load CLI — ${err.message}\n`);
+  process.exit(2);
+});

package/migrations/001_initial.sql

@@ -0,0 +1,185 @@
+-- Kernel initial migration. Provisions the 11 kernel tables per
+-- spec/db-schema.md. Up-only. Wrapped in BEGIN / COMMIT by the runner.
+
+-- --- Scan zone -------------------------------------------------------------
+
+CREATE TABLE scan_nodes (
+  path TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  adapter TEXT NOT NULL,
+  title TEXT,
+  description TEXT,
+  stability TEXT,
+  version TEXT,
+  author TEXT,
+  frontmatter_json TEXT NOT NULL,
+  body_hash TEXT NOT NULL,
+  frontmatter_hash TEXT NOT NULL,
+  bytes_frontmatter INTEGER NOT NULL,
+  bytes_body INTEGER NOT NULL,
+  bytes_total INTEGER NOT NULL,
+  tokens_frontmatter INTEGER,
+  tokens_body INTEGER,
+  tokens_total INTEGER,
+  links_out_count INTEGER NOT NULL DEFAULT 0,
+  links_in_count INTEGER NOT NULL DEFAULT 0,
+  external_refs_count INTEGER NOT NULL DEFAULT 0,
+  scanned_at INTEGER NOT NULL,
+  CONSTRAINT ck_scan_nodes_kind CHECK (kind IN ('skill','agent','command','hook','note')),
+  CONSTRAINT ck_scan_nodes_stability CHECK (stability IS NULL OR stability IN ('experimental','stable','deprecated'))
+);
+CREATE INDEX ix_scan_nodes_kind ON scan_nodes(kind);
+CREATE INDEX ix_scan_nodes_adapter ON scan_nodes(adapter);
+CREATE INDEX ix_scan_nodes_body_hash ON scan_nodes(body_hash);
+
+CREATE TABLE scan_links (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  source_path TEXT NOT NULL,
+  target_path TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  confidence TEXT NOT NULL,
+  sources_json TEXT NOT NULL,
+  original_trigger TEXT,
+  normalized_trigger TEXT,
+  location_line INTEGER,
+  location_column INTEGER,
+  location_offset INTEGER,
+  raw TEXT,
+  CONSTRAINT ck_scan_links_kind CHECK (kind IN ('invokes','references','mentions','supersedes')),
+  CONSTRAINT ck_scan_links_confidence CHECK (confidence IN ('high','medium','low'))
+);
+CREATE INDEX ix_scan_links_source_path ON scan_links(source_path);
+CREATE INDEX ix_scan_links_target_path ON scan_links(target_path);
+CREATE INDEX ix_scan_links_normalized_trigger ON scan_links(normalized_trigger);
+
+CREATE TABLE scan_issues (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  rule_id TEXT NOT NULL,
+  severity TEXT NOT NULL,
+  node_ids_json TEXT NOT NULL,
+  link_indices_json TEXT,
+  message TEXT NOT NULL,
+  detail TEXT,
+  fix_json TEXT,
+  data_json TEXT,
+  CONSTRAINT ck_scan_issues_severity CHECK (severity IN ('error','warn','info'))
+);
+CREATE INDEX ix_scan_issues_rule_id ON scan_issues(rule_id);
+CREATE INDEX ix_scan_issues_severity ON scan_issues(severity);
+
+-- --- State zone ------------------------------------------------------------
+
+CREATE TABLE state_jobs (
+  id TEXT PRIMARY KEY,
+  action_id TEXT NOT NULL,
+  action_version TEXT NOT NULL,
+  node_id TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  nonce TEXT NOT NULL,
+  priority INTEGER NOT NULL DEFAULT 0,
+  status TEXT NOT NULL,
+  failure_reason TEXT,
+  runner TEXT,
+  ttl_seconds INTEGER NOT NULL,
+  file_path TEXT,
+  created_at INTEGER NOT NULL,
+  claimed_at INTEGER,
+  finished_at INTEGER,
+  expires_at INTEGER,
+  submitted_by TEXT,
+  CONSTRAINT ck_state_jobs_status CHECK (status IN ('queued','running','completed','failed')),
+  CONSTRAINT ck_state_jobs_failure_reason CHECK (failure_reason IS NULL OR failure_reason IN ('runner-error','report-invalid','timeout','abandoned','job-file-missing','user-cancelled')),
+  CONSTRAINT ck_state_jobs_runner CHECK (runner IS NULL OR runner IN ('cli','skill','in-process'))
+);
+CREATE INDEX ix_state_jobs_status ON state_jobs(status);
+-- Unique partial index for duplicate-job detection: at most one
+-- queued/running job per (action_id, node_id, content_hash).
+CREATE UNIQUE INDEX ix_state_jobs_action_node_hash
+  ON state_jobs(action_id, node_id, content_hash)
+  WHERE status IN ('queued','running');
+
+CREATE TABLE state_executions (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  extension_id TEXT NOT NULL,
+  extension_version TEXT NOT NULL,
+  node_ids_json TEXT NOT NULL DEFAULT '[]',
+  content_hash TEXT,
+  status TEXT NOT NULL,
+  failure_reason TEXT,
+  exit_code INTEGER,
+  runner TEXT,
+  started_at INTEGER NOT NULL,
+  finished_at INTEGER NOT NULL,
+  duration_ms INTEGER,
+  tokens_in INTEGER,
+  tokens_out INTEGER,
+  report_path TEXT,
+  job_id TEXT,
+  CONSTRAINT ck_state_executions_kind CHECK (kind IN ('action','audit')),
+  CONSTRAINT ck_state_executions_status CHECK (status IN ('completed','failed','cancelled'))
+);
+CREATE INDEX ix_state_executions_extension_id ON state_executions(extension_id);
+CREATE INDEX ix_state_executions_started_at ON state_executions(started_at);
+CREATE INDEX ix_state_executions_job_id ON state_executions(job_id);
+
+CREATE TABLE state_summaries (
+  node_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  summarizer_action_id TEXT NOT NULL,
+  summarizer_version TEXT NOT NULL,
+  body_hash_at_generation TEXT NOT NULL,
+  generated_at INTEGER NOT NULL,
+  summary_json TEXT NOT NULL,
+  PRIMARY KEY (node_id, summarizer_action_id),
+  CONSTRAINT ck_state_summaries_kind CHECK (kind IN ('skill','agent','command','hook','note'))
+);
+CREATE INDEX ix_state_summaries_generated_at ON state_summaries(generated_at);
+
+CREATE TABLE state_enrichments (
+  node_id TEXT NOT NULL,
+  provider_id TEXT NOT NULL,
+  data_json TEXT NOT NULL,
+  verified INTEGER,
+  fetched_at INTEGER NOT NULL,
+  stale_after INTEGER,
+  PRIMARY KEY (node_id, provider_id),
+  CONSTRAINT ck_state_enrichments_verified CHECK (verified IS NULL OR verified IN (0,1))
+);
+CREATE INDEX ix_state_enrichments_stale_after ON state_enrichments(stale_after);
+
+CREATE TABLE state_plugin_kvs (
+  plugin_id TEXT NOT NULL,
+  node_id TEXT NOT NULL DEFAULT '',
+  key TEXT NOT NULL,
+  value_json TEXT NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (plugin_id, node_id, key)
+);
+CREATE INDEX ix_state_plugin_kvs_plugin_id ON state_plugin_kvs(plugin_id);
+
+-- --- Config zone -----------------------------------------------------------
+
+CREATE TABLE config_plugins (
+  plugin_id TEXT PRIMARY KEY,
+  enabled INTEGER NOT NULL DEFAULT 1,
+  config_json TEXT,
+  updated_at INTEGER NOT NULL,
+  CONSTRAINT ck_config_plugins_enabled CHECK (enabled IN (0,1))
+);
+
+CREATE TABLE config_preferences (
+  key TEXT PRIMARY KEY,
+  value_json TEXT NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE TABLE config_schema_versions (
+  scope TEXT NOT NULL,
+  owner_id TEXT NOT NULL,
+  version INTEGER NOT NULL,
+  description TEXT NOT NULL,
+  applied_at INTEGER NOT NULL,
+  PRIMARY KEY (scope, owner_id, version),
+  CONSTRAINT ck_config_schema_versions_scope CHECK (scope IN ('kernel','plugin'))
+);

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@skill-map/cli",
+  "version": "0.3.1",
+  "description": "skill-map reference implementation — kernel + CLI + adapters.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://skill-map.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crystian/skill-map.git",
+    "directory": "src"
+  },
+  "bugs": {
+    "url": "https://github.com/crystian/skill-map/issues"
+  },
+  "keywords": [
+    "skill-map",
+    "markdown",
+    "ai-agents",
+    "claude-code",
+    "graph"
+  ],
+  "bin": {
+    "sm": "bin/sm.mjs",
+    "skill-map": "bin/sm.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./kernel": {
+      "types": "./dist/kernel/index.d.ts",
+      "import": "./dist/kernel/index.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance/index.d.ts",
+      "import": "./dist/conformance/index.js"
+    }
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "migrations/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test --test-reporter=spec 'test/**/*.test.ts' 'extensions/**/*.test.ts' 'kernel/**/*.test.ts'",
+    "test:ci": "node --import tsx --test 'test/**/*.test.ts' 'extensions/**/*.test.ts' 'kernel/**/*.test.ts'",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@skill-map/spec": "*",
+    "ajv": "8.18.0",
+    "ajv-formats": "3.0.1",
+    "clipanion": "4.0.0-rc.4",
+    "js-yaml": "4.1.1",
+    "kysely": "0.28.16",
+    "semver": "7.7.4",
+    "typanion": "3.14.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "4.0.9",
+    "@types/node": "24.12.2",
+    "@types/semver": "7.7.1",
+    "tsup": "8.5.1",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": ">=24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}