@esneiderbravo/speclaw 0.1.4 → 0.1.6

package/README.md

@@ -29,24 +29,28 @@ One command. No cloud, no LLM, no API keys — <b>everything runs on your machin
 <br/>
 
 > [!TIP]
-> **One command sets everything up.** Run `npx @esneiderbravo/speclaw init`, pick the agents you
-> use, and speclaw scaffolds the project, indexes your code, and hands your agent
-> a ready-to-paste prompt to finish the setup.
+> **Install once, then one command sets everything up.** Install speclaw globally, run
+> `speclaw init`, pick the agents you use, and speclaw scaffolds the project, indexes
+> your code, and hands your agent a ready-to-paste prompt to finish the setup.
 
 <br/>
 
 ## ◆ Quick start
 
-In your project root:
+Install speclaw globally (once), then run `init` in your project root:
 
 ```bash
-npx @esneiderbravo/speclaw init
+npm i -g @esneiderbravo/speclaw
+speclaw init
 ```
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-quickstart.png" width="800" alt="npx @esneiderbravo/speclaw init">
+  <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-quickstart.png" width="800" alt="speclaw init">
 </p>
 
+The `speclaw` command is now available everywhere — run `speclaw index`,
+`speclaw visualize`, or `speclaw lawbook …` directly in any project.
+
 `init` will:
 
 1. **Ask which agents you use** (Claude Code, Cursor, Codex, …) — and configure
@@ -57,7 +61,9 @@ npx @esneiderbravo/speclaw init
 5. Print a prompt to paste into your agent so it fills the constitution with your
    project's real architecture and conventions.
 
-Works with `npm`, `pnpm` (`pnpm dlx @esneiderbravo/speclaw init`), and `yarn`.
+Prefer not to install globally? A one-off `npx @esneiderbravo/speclaw init` works
+too (also `pnpm dlx` / `yarn dlx`) — but installing globally means you can run the
+`speclaw` commands directly afterwards.
 
 <br/>
 
@@ -118,6 +124,25 @@ still use Compass and the lawbook engine by calling the CLI from its shell.
 
 <br/>
 
+## ◆ Staying up to date
+
+speclaw checks for new releases in the background (at most once a day) and nudges
+you when one lands. To upgrade:
+
+```bash
+speclaw update
+```
+
+`update` upgrades the global package **and** brings the current project up to date
+without a re-init: any new standards, skills, commands, or feature steps are added
+**additively** — your existing files are never touched. It re-applies only the tool
+packs this project already uses.
+
+- `speclaw update --check` — report whether an update exists, change nothing.
+- `NO_UPDATE_NOTIFIER=1` — silence the reminder.
+
+<br/>
+
 ## ◆ Requirements
 
 - **Node.js ≥ 22** — uses the built-in `node:sqlite`.

package/dist/cli/commands/init.js

@@ -11,7 +11,8 @@ import { ui, c, banner, renderProgress, clearProgress } from "../lib/ui.js";
 const PACK_LABELS = {
     agents: "dev-agents (backend · frontend · product)",
 };
-function detectProjectName(cwd) {
+/** Best-effort project name: the package.json name (unscoped) or the directory name. */
+export function detectProjectName(cwd) {
     try {
         const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
         if (pkg.name)
@@ -67,15 +68,24 @@ export async function runInit(flags) {
         process.exit(1);
     }
     const profile = { project_name: projectName };
-    // 1. Content + chosen agents, with a check per piece installed
+    // 1. Content + chosen agents, with a check per piece installed. Re-running
+    // init is safe: every writer skips files that already exist, so anything you
+    // (or your agent) filled in is preserved — init only adds what's missing.
+    const reinit = fs.existsSync(path.join(cwd, "LAWS.md"));
     ui.step(`Setting up ${c.bold(c.cyan(projectName))}`);
-    scaffold(cwd, profile, packs, agents);
+    if (reinit) {
+        ui.info("speclaw is already set up here — your existing files are kept; only missing pieces are added.");
+    }
+    const report = scaffold(cwd, profile, packs, agents);
     ui.ok(`Foundation ${c.muted("— LAWS.md + 8 standards + CLAUDE.md/AGENTS.md")}`);
     ui.ok(`Lawbook workflow ${c.muted("— draft · build · sync · archive · explore")}`);
     for (const p of packs)
         ui.ok(`${PACK_LABELS[p] ?? p + " pack"}`);
     specInit(cwd);
     ui.ok(`Lawbook workspace ${c.muted("— lawbook/")}`);
+    if (reinit && report.skipped.length) {
+        ui.info(`${report.written.length} added · ${c.cream(String(report.skipped.length))} preserved untouched`);
+    }
     ui.step("Configuring agents");
     for (const id of agents)
         ui.ok(`${agentById(id).label} ${c.muted("— symlinks + MCP")}`);

package/dist/cli/commands/update.js

@@ -0,0 +1,100 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { ui, c } from "../lib/ui.js";
+import { checkForUpdates, isNewer } from "../lib/update-check.js";
+import { pkgName, pkgVersion } from "../../shared/version.js";
+import { scaffold } from "../../modules/foundation/scaffold.js";
+import { detectConfiguredAgents } from "../../shared/agents.js";
+import { readManifest } from "../../shared/manifest.js";
+import { loadPacks } from "../../modules/tools/packs.js";
+import { detectProjectName } from "./init.js";
+const MIGRATIONS = [
+// e.g. { version: "0.3.0", describe: "…", run: (p, r) => { … } }
+];
+/**
+ * Update speclaw and bring the current project up to date without a full re-init:
+ * upgrade the global package, then additively apply any new standards, skills,
+ * commands, and feature steps this project is missing (existing files untouched).
+ *
+ * @param flags - `--check` reports without changing anything; `--migrate-only`
+ *   skips the global upgrade and only applies project changes (used internally
+ *   after the package is upgraded, so migrations run from the new version).
+ */
+export async function runUpdate(flags) {
+    const cwd = process.cwd();
+    const migrateOnly = Boolean(flags["migrate-only"]);
+    const checkOnly = Boolean(flags.check);
+    const winShell = process.platform === "win32";
+    if (!migrateOnly) {
+        ui.step("Checking for updates");
+        const { current, latest, updateAvailable } = await checkForUpdates({ force: true });
+        if (!latest) {
+            ui.warn("Could not reach the npm registry — skipping the version check.");
+        }
+        else if (updateAvailable) {
+            ui.info(`${c.muted(current)} ${c.muted("→")} ${c.cyan(latest)}`);
+            if (checkOnly) {
+                ui.info(`Run ${ui.code("speclaw update")} to upgrade and apply what's new.`);
+                return;
+            }
+            ui.step(`Updating ${pkgName()} globally`);
+            const install = spawnSync("npm", ["install", "-g", `${pkgName()}@latest`], { stdio: "inherit", shell: winShell });
+            if (install.status !== 0) {
+                ui.err("Global update failed. Try again with elevated permissions (e.g. sudo), or check your npm setup.");
+                process.exit(1);
+            }
+            ui.ok(`Updated to ${latest}`);
+            // Re-exec the NEWLY installed binary so migrations run with the new assets
+            // and any new feature steps — not this (now-stale) process.
+            const re = spawnSync("speclaw", ["update", "--migrate-only"], { stdio: "inherit", shell: winShell });
+            if (re.error) {
+                ui.warn(`Upgraded — now run ${ui.code("speclaw update --migrate-only")} to apply project changes.`);
+                return;
+            }
+            process.exit(re.status ?? 0);
+        }
+        else {
+            ui.ok(`Already on the latest version (${current}).`);
+            if (checkOnly)
+                return;
+        }
+    }
+    applyProjectMigrations(cwd);
+}
+/**
+ * Additively apply the current version's content and feature steps to a project.
+ * No-op with a hint when the directory isn't a speclaw project.
+ */
+function applyProjectMigrations(cwd) {
+    const initialized = fs.existsSync(path.join(cwd, "ai-specs")) || fs.existsSync(path.join(cwd, "LAWS.md"));
+    if (!initialized) {
+        ui.step("Project");
+        ui.info(`No speclaw project here — run ${ui.code("speclaw init")} to set one up.`);
+        return;
+    }
+    ui.step("Applying what's new to this project");
+    const fromVersion = readManifest(cwd)?.version ?? "0.0.0";
+    const agents = detectConfiguredAgents(cwd);
+    const known = loadPacks();
+    const packs = (readManifest(cwd)?.packs ?? []).filter((p) => p in known);
+    // scaffold is non-destructive: only missing files are written, and it refreshes
+    // the manifest to the current version. Existing files are left exactly as-is.
+    const report = scaffold(cwd, { project_name: detectProjectName(cwd) }, packs, agents);
+    const newFiles = report.written.filter((w) => !w.includes(".gitignore"));
+    if (newFiles.length) {
+        for (const w of newFiles)
+            ui.ok(c.cream(path.relative(cwd, w.split(" (")[0])));
+        ui.info(`${newFiles.length} new file(s) added · ${report.skipped.length} left untouched.`);
+    }
+    else {
+        ui.ok("Content already up to date — nothing new to add.");
+    }
+    const pending = MIGRATIONS.filter((m) => isNewer(m.version, fromVersion));
+    for (const m of pending) {
+        ui.step(`Step for ${m.version}: ${m.describe}`);
+        m.run(cwd, report);
+    }
+    ui.plain();
+    ui.ok(`On ${c.cyan(pkgVersion())}. No re-init needed.`);
+}

package/dist/cli/index.js

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
 import { parseFlags } from "./lib/args.js";
 import { ui } from "./lib/ui.js";
-const HELP = `speclaw — spec-driven, agent-ready projects (foundation + Compass + Spec)
+import { maybeNotifyUpdate } from "./lib/update-check.js";
+const HELP = `speclaw — spec-driven, agent-ready projects (foundation + Compass + Lawbook)
 
 Usage: speclaw <command> [options]
 
+Install globally so the command is always available:
+  npm i -g @esneiderbravo/speclaw
+
 Setup
   init                     Interactive setup: pick agents, scaffold, index, get the prompt
+  update                   Upgrade speclaw and apply only what's new (no re-init)
   agent list               Show which agents are configured
   agent add <id>           Configure another agent later (symlinks + MCP)
 
@@ -32,10 +37,8 @@ Other
   mcp                      Start the MCP server (used by your agent's config)
   help                     Show this help
 `;
-/** Parse argv and dispatch to the matching command handler. */
-async function main() {
-    const [cmd, ...rest] = process.argv.slice(2);
-    const flags = parseFlags(rest);
+/** Run the handler for a single command. Returns when the command completes. */
+async function dispatch(cmd, flags) {
     switch (cmd) {
         case undefined:
         case "help":
@@ -50,6 +53,8 @@ async function main() {
         }
         case "init":
             return (await import("./commands/init.js")).runInit(flags);
+        case "update":
+            return (await import("./commands/update.js")).runUpdate(flags);
         case "agent":
             return (await import("./commands/agent.js")).runAgent(flags);
         case "index":
@@ -74,6 +79,13 @@ async function main() {
             process.exit(1);
     }
 }
+/** Parse argv, run the command, then surface an update notice if one is due. */
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    const flags = parseFlags(rest);
+    await dispatch(cmd, flags);
+    await maybeNotifyUpdate(cmd);
+}
 main().catch((err) => {
     ui.err(err.message);
     process.exit(1);

package/dist/cli/lib/update-check.js

@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pkgName, pkgVersion } from "../../shared/version.js";
+import { c } from "./ui.js";
+// A lightweight, best-effort update notifier. The registry is queried at most
+// once a day (result cached under ~/.speclaw/), the lookup is time-boxed, and
+// every failure is swallowed — checking for updates must never slow down or
+// break a command. Notices go to stderr so piped stdout stays clean.
+const TTL_MS = 24 * 60 * 60 * 1000;
+function cacheFile() {
+    return path.join(os.homedir(), ".speclaw", "update-check.json");
+}
+function readCache() {
+    try {
+        const c = JSON.parse(fs.readFileSync(cacheFile(), "utf8"));
+        if (typeof c.checkedAt === "number" && typeof c.latest === "string")
+            return c;
+    }
+    catch {
+        /* no cache yet */
+    }
+    return null;
+}
+function writeCache(latest) {
+    try {
+        const f = cacheFile();
+        fs.mkdirSync(path.dirname(f), { recursive: true });
+        fs.writeFileSync(f, JSON.stringify({ checkedAt: Date.now(), latest }));
+    }
+    catch {
+        /* cache is an optimization; ignore failures */
+    }
+}
+async function fetchLatest(name) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 2500);
+    try {
+        const url = `https://registry.npmjs.org/${name.replace("/", "%2F")}/latest`;
+        const res = await fetch(url, { signal: ctrl.signal });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === "string" ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Compare two dotted versions (ignoring any prerelease suffix).
+ *
+ * @returns True when `latest` is strictly newer than `current`.
+ */
+export function isNewer(latest, current) {
+    const parse = (v) => v.split("-")[0].split(".").map((n) => parseInt(n, 10) || 0);
+    const a = parse(latest);
+    const b = parse(current);
+    for (let i = 0; i < 3; i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x > y)
+            return true;
+        if (x < y)
+            return false;
+    }
+    return false;
+}
+/**
+ * Resolve the current version and the latest published one, using the daily
+ * cache unless `force` is set. Falls back to stale cache when offline.
+ *
+ * @param opts - `force` bypasses the cache and always queries the registry.
+ * @returns The current/latest versions and whether an upgrade is available.
+ */
+export async function checkForUpdates(opts = {}) {
+    const current = pkgVersion();
+    const cache = readCache();
+    let latest = null;
+    if (!opts.force && cache && Date.now() - cache.checkedAt < TTL_MS) {
+        latest = cache.latest;
+    }
+    else {
+        latest = await fetchLatest(pkgName());
+        if (latest)
+            writeCache(latest);
+        else if (cache)
+            latest = cache.latest; // offline: use whatever we last knew
+    }
+    return { current, latest, updateAvailable: !!latest && isNewer(latest, current) };
+}
+/**
+ * Print a one-line "update available" notice to stderr when a newer version
+ * exists. No-op for the `mcp`/`update`/`help` commands, on non-TTY stderr, or
+ * when NO_UPDATE_NOTIFIER / SPECLAW_NO_UPDATE_NOTIFIER is set. Never throws.
+ *
+ * @param cmd - The command that just ran (used to skip noisy contexts).
+ */
+export async function maybeNotifyUpdate(cmd) {
+    try {
+        if (process.env.NO_UPDATE_NOTIFIER || process.env.SPECLAW_NO_UPDATE_NOTIFIER)
+            return;
+        if (!process.stderr.isTTY)
+            return;
+        if (!cmd || ["mcp", "update", "help", "--help", "-h"].includes(cmd))
+            return;
+        const { current, latest, updateAvailable } = await checkForUpdates();
+        if (!updateAvailable || !latest)
+            return;
+        process.stderr.write("\n" +
+            "  " + c.amber("⬆ speclaw ") + c.muted(current + " → ") + c.cyan(latest) + c.muted(" available") + "\n" +
+            "  " + c.muted("run ") + c.cyan("speclaw update") + c.muted(" — upgrades and applies only what's new") + "\n\n");
+    }
+    catch {
+        /* the notifier is best-effort — never let it break a command */
+    }
+}

package/dist/modules/compass/db.js

@@ -49,13 +49,53 @@ CREATE TABLE IF NOT EXISTS node_embeddings (
 );
 `;
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "2";
+export const SCHEMA_VERSION = "3";
+/** The stamped schema version, or null if the db predates versioning / has no meta table. */
+function readSchemaVersion(db) {
+    try {
+        const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
+        return row ? String(row.value) : null;
+    }
+    catch {
+        return null; // meta table doesn't exist yet
+    }
+}
+/**
+ * Decide whether an existing database is from an incompatible schema and must be
+ * rebuilt. A fresh database (no tables) needs no reset — the schema will create
+ * them. An existing one is stale if its stamped version differs from the current
+ * one, or if the `edges` table is missing a column the current code writes to
+ * (guards against past schema changes that weren't version-bumped).
+ */
+function isStale(db) {
+    const hasEdges = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'edges'")
+        .get();
+    if (!hasEdges)
+        return false;
+    if (readSchemaVersion(db) !== SCHEMA_VERSION)
+        return true;
+    const cols = db.prepare("PRAGMA table_info(edges)").all().map((c) => c.name);
+    return !cols.includes("src_node_id") || !cols.includes("dst_node_id");
+}
+/** Drop every table (children first) so the current schema can be recreated cleanly. */
+function resetSchema(db) {
+    db.exec(`
+    DROP TABLE IF EXISTS node_embeddings;
+    DROP TABLE IF EXISTS edges;
+    DROP TABLE IF EXISTS nodes;
+    DROP TABLE IF EXISTS files;
+    DROP TABLE IF EXISTS meta;
+  `);
+}
 /**
  * Open (creating if needed) the index database at `<projectPath>/.speclaw/index.db`.
  *
- * Ensures the `.speclaw` directory exists, applies the schema (idempotently),
- * enables WAL journaling and foreign keys, and stamps the schema version on a
- * fresh database.
+ * Ensures the `.speclaw` directory exists, enables WAL journaling and foreign
+ * keys, and applies the schema. If an existing database is from an incompatible
+ * schema (e.g. after a speclaw upgrade), it is dropped and rebuilt — `.speclaw`
+ * is fully regenerable, so the next index just repopulates it. The schema
+ * version is stamped on a fresh (or freshly reset) database.
  *
  * @param projectPath - Absolute path to the project root.
  * @returns An open connection to the index database.
@@ -65,6 +105,8 @@ export function openDb(projectPath) {
     fs.mkdirSync(dir, { recursive: true });
     const db = new DatabaseSync(path.join(dir, "index.db"));
     db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
+    if (isStale(db))
+        resetSchema(db);
     db.exec(SCHEMA);
     const row = db
         .prepare("SELECT value FROM meta WHERE key = 'schema_version'")

package/dist/modules/foundation/scaffold.js

@@ -6,6 +6,8 @@ import { emptyReport, ensureGitignore } from "../../shared/install.js";
 import { configureAgent } from "../../shared/agents.js";
 import { installWorkflow } from "../lawbook/register.js";
 import { installPack, loadPacks } from "../tools/packs.js";
+import { writeManifest } from "../../shared/manifest.js";
+import { pkgVersion } from "../../shared/version.js";
 const ASSETS = assetsDir(import.meta.url);
 // Every {{var}} the foundation templates may reference. Ones the agent didn't
 // provide default to empty so a bare `scaffold` never leaves a raw {{tag}}.
@@ -88,6 +90,9 @@ export function scaffold(projectPath, profile, packNames, agents = []) {
     ensureGitignore(projectPath, ".speclaw/", "speclaw local code Compass (never commit)", report);
     for (const id of agents)
         configureAgent(projectPath, id, report); // only the chosen agents
+    // Record what was installed so `speclaw update` can re-apply only these packs
+    // (additively) and gate feature migrations by version — no full re-init.
+    writeManifest(projectPath, pkgVersion(), packNames);
     report.nextSteps = [
         "Run the `lawbook_init` tool to set up the spec-driven workflow (creates lawbook/). No external CLI needed — it's built into speclaw.",
         "Run the `compass_index` tool to build the local code graph (.speclaw/). No install, no LLM — it's built into speclaw. Re-run it after significant edits.",

package/dist/shared/manifest.js

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import path from "node:path";
+function manifestPath(projectPath) {
+    return path.join(projectPath, "ai-specs", ".speclaw.json");
+}
+/**
+ * Read a project's speclaw manifest.
+ *
+ * @param projectPath - Project root to read from.
+ * @returns The manifest, or null if the project has none (e.g. an older init).
+ */
+export function readManifest(projectPath) {
+    try {
+        const m = JSON.parse(fs.readFileSync(manifestPath(projectPath), "utf8"));
+        return { version: String(m.version ?? "0.0.0"), packs: Array.isArray(m.packs) ? m.packs.map(String) : [] };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write (or refresh) a project's manifest, recording the current version and the
+ * union of previously-installed and newly-installed packs.
+ *
+ * @param projectPath - Project root to write into.
+ * @param version - The speclaw version doing the write.
+ * @param packs - Pack names installed in this run.
+ */
+export function writeManifest(projectPath, version, packs) {
+    const prev = readManifest(projectPath);
+    const merged = Array.from(new Set([...(prev?.packs ?? []), ...packs]));
+    const p = manifestPath(projectPath);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ version, packs: merged }, null, 2) + "\n");
+}

package/dist/shared/version.js

@@ -0,0 +1,27 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// The package.json sits at the package root — two levels up from this compiled
+// file (dist/shared/version.js -> dist -> <root>). Read once and cache.
+let cached = null;
+function readPkg() {
+    if (cached)
+        return cached;
+    const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        cached = { name: String(pkg.name ?? "@esneiderbravo/speclaw"), version: String(pkg.version ?? "0.0.0") };
+    }
+    catch {
+        cached = { name: "@esneiderbravo/speclaw", version: "0.0.0" };
+    }
+    return cached;
+}
+/** The published package name (e.g. `@esneiderbravo/speclaw`). */
+export function pkgName() {
+    return readPkg().name;
+}
+/** The currently installed package version (e.g. `0.1.4`). */
+export function pkgVersion() {
+    return readPkg().version;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "publishConfig": {
     "access": "public"
   },