4runr-cursor-setup 0.1.5 → 0.1.7

package/dist/cli.js

@@ -1,51 +1,59 @@
 #!/usr/bin/env node
-import { init } from "./commands/init.js";
-import { addGroup, listGroups, removeGroup, GROUPS } from "./commands/commands.js";
-const args = process.argv.slice(2);
-const cmd = args[0];
+import { listGroups, addGroup, removeGroup, GROUPS } from "./commands/commands.js";
+import { doctor } from "./commands/doctor.js";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const TOOL_VERSION = require("../package.json").version;
 function usage() {
-    console.log("4runr-cursor-setup");
     console.log("Usage:");
-    console.log("  4runr-cursor-setup init [--force]");
-    console.log("  4runr-cursor-setup list");
-    console.log("  4runr-cursor-setup add <group> [--force]");
-    console.log("  4runr-cursor-setup remove <group>");
+    console.log("  list");
+    console.log("  add <group> [--force] [--dry-run]");
+    console.log("  remove <group> [--dry-run]");
+    console.log("  doctor [--fix] [--strict] [--json] [--dry-run]");
     console.log("");
     console.log("Groups: " + Object.keys(GROUPS).join(", "));
 }
-async function main() {
-    const force = args.includes("--force");
-    if (cmd === "init") {
-        await init({ cwd: process.cwd() });
-        addGroup({ cwd: process.cwd(), group: "core", force });
-        return;
-    }
-    if (cmd === "list") {
-        listGroups();
-        return;
-    }
-    if (cmd === "add") {
-        const group = args[1];
-        if (!group || !(group in GROUPS)) {
-            usage();
-            process.exit(1);
-        }
-        addGroup({ cwd: process.cwd(), group, force });
-        return;
-    }
-    if (cmd === "remove") {
-        const group = args[1];
-        if (!group || !(group in GROUPS)) {
-            usage();
-            process.exit(1);
-        }
-        removeGroup({ cwd: process.cwd(), group });
-        return;
-    }
-    usage();
-    process.exit(1);
+const args = process.argv.slice(2);
+const cmd = args[0];
+const cwd = process.cwd();
+const flags = new Set(args.slice(1));
+const has = (f) => flags.has(f);
+function parseGroup(raw) {
+    if (!raw)
+        throw new Error("Missing group name");
+    const g = raw;
+    if (!(g in GROUPS))
+        throw new Error(`Unknown group: ${raw}`);
+    return g;
+}
+if (cmd === "list") {
+    listGroups();
+    process.exit(0);
+}
+if (cmd === "add") {
+    const group = parseGroup(args[1]);
+    addGroup({
+        cwd,
+        group,
+        force: has("--force"),
+        dryRun: has("--dry-run"),
+    });
+    process.exit(0);
+}
+if (cmd === "remove") {
+    const group = parseGroup(args[1]);
+    removeGroup({ cwd, group, dryRun: has("--dry-run") });
+    process.exit(0);
+}
+if (cmd === "doctor") {
+    doctor(cwd, TOOL_VERSION, {
+        fix: has("--fix"),
+        json: has("--json"),
+        strict: has("--strict"),
+        dryRun: has("--dry-run"),
+    });
+    // Exit with the exit code set by doctor (or 0 if not set)
+    process.exit(process.exitCode || 0);
 }
-main().catch((err) => {
-    console.error(err);
-    process.exit(1);
-});
+usage();
+process.exit(1);

package/dist/commands/commands.js

@@ -1,13 +1,23 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as url from "url";
+import { createRequire } from "module";
 import { ensureMemory } from "./memory.js";
+import { loadManifest, saveManifest, createEmptyManifest, upsertFile, removeFile, sha256, } from "./manifest.js";
 export const GROUPS = {
     core: ["4runr-start.md", "4runr-close.md"],
     planning: ["4runr-task.md", "4runr-phase.md"],
     governance: ["4runr-decision.md", "4runr-scope-change.md"],
     debugging: ["4runr-repro.md", "4runr-verify.md"],
 };
+function assertSafeRelPath(rel) {
+    const norm = rel.replace(/\\/g, "/");
+    if (norm.includes(".."))
+        throw new Error("Refusing unsafe path traversal: " + rel);
+    if (path.isAbsolute(rel))
+        throw new Error("Refusing absolute path: " + rel);
+    return norm;
+}
 const MANAGED_MARKER = "<!-- managed-by: 4runr-cursor-setup -->";
 function ensureDir(p) {
     fs.mkdirSync(p, { recursive: true });
@@ -46,6 +56,29 @@ function getTemplatesRoot() {
     const here = path.dirname(url.fileURLToPath(import.meta.url));
     return path.resolve(here, "..", "templates");
 }
+function getToolVersion() {
+    const require = createRequire(import.meta.url);
+    return require("../package.json").version;
+}
+function ensureManifest(cwd) {
+    let m = loadManifest(cwd);
+    if (!m) {
+        m = createEmptyManifest(getToolVersion());
+        saveManifest(cwd, m);
+    }
+    return m;
+}
+function assertPathUnderCommands(cwd, filePath) {
+    const resolved = path.resolve(cwd, filePath);
+    const commandsDir = path.resolve(cwd, ".cursor", "commands");
+    if (!resolved.startsWith(commandsDir + path.sep) && resolved !== commandsDir) {
+        throw new Error(`Path escapes .cursor/commands: ${filePath}`);
+    }
+}
+function getRelativePath(cwd, absolutePath) {
+    const rel = path.relative(cwd, absolutePath);
+    return assertSafeRelPath(rel);
+}
 export function listGroups() {
     console.log("Available groups:");
     Object.keys(GROUPS).forEach((g) => {
@@ -53,42 +86,217 @@ export function listGroups() {
     });
 }
 export function addGroup(opts) {
-    const { cwd, group, force = false } = opts;
+    const { cwd, group, force = false, dryRun = false } = opts;
     const templatesRoot = getTemplatesRoot();
     const srcBase = path.join(templatesRoot, "commands", group);
     const outBase = path.join(cwd, ".cursor", "commands");
-    ensureDir(outBase);
+    if (dryRun) {
+        console.log(`PLAN add ${group} (dry-run)`);
+    }
+    else {
+        ensureDir(outBase);
+    }
+    // Load or ensure manifest exists (for dry-run, we only read it)
+    let manifest = loadManifest(cwd) || createEmptyManifest(getToolVersion());
+    if (!dryRun && !loadManifest(cwd)) {
+        // For real runs, ensure manifest exists on disk
+        manifest = ensureManifest(cwd);
+    }
     const files = GROUPS[group];
     let copied = 0;
+    const writtenPaths = new Set();
+    const operations = [];
     for (const f of files) {
         const src = path.join(srcBase, f);
         const dst = path.join(outBase, f);
-        if (!fs.existsSync(src))
+        // Safety: ensure path is under .cursor/commands
+        assertPathUnderCommands(cwd, dst);
+        const relPath = getRelativePath(cwd, dst);
+        // Check for duplicates
+        if (writtenPaths.has(relPath)) {
+            const errorMsg = `ERROR duplicate destination path: ${relPath}`;
+            if (dryRun) {
+                operations.push(errorMsg);
+                continue;
+            }
+            throw new Error(`Duplicate destination path: ${relPath}`);
+        }
+        writtenPaths.add(relPath);
+        if (!fs.existsSync(src)) {
+            const errorMsg = `ERROR template missing: ${src}`;
+            if (dryRun) {
+                operations.push(errorMsg);
+                continue;
+            }
             throw new Error("Template missing: " + src);
-        if (copyIfMissing(src, dst, force))
-            copied++;
+        }
+        // Read template content to compute hash (needed for planning)
+        const templateBody = fs.readFileSync(src, "utf8");
+        const templateContent = templateBody.includes(MANAGED_MARKER) ? templateBody : `${MANAGED_MARKER}\n\n${templateBody}`;
+        const templateHash = sha256(templateContent);
+        const exists = fs.existsSync(dst);
+        const hasMarker = exists ? fileContainsMarker(dst) : false;
+        const inManifest = manifest.files.some((mf) => mf.path === relPath);
+        // Tool-managed = has marker AND in manifest
+        const isToolManaged = exists && hasMarker && inManifest;
+        if (!exists) {
+            // File doesn't exist - will create
+            if (dryRun) {
+                operations.push(`CREATE ${relPath}`);
+            }
+            else {
+                writeWithMarker(src, dst);
+                copied++;
+                const templateId = `commands/${group}/${f}`;
+                upsertFile(manifest, {
+                    path: relPath,
+                    templateId,
+                    templateVersion: 1,
+                    contentSha256: templateHash,
+                });
+            }
+        }
+        else if (isToolManaged && force) {
+            // File exists, is tool-managed (marker + manifest), and --force is set - will overwrite
+            if (dryRun) {
+                operations.push(`OVERWRITE ${relPath} (tool-managed, --force)`);
+            }
+            else {
+                writeWithMarker(src, dst);
+                copied++;
+                const templateId = `commands/${group}/${f}`;
+                upsertFile(manifest, {
+                    path: relPath,
+                    templateId,
+                    templateVersion: 1,
+                    contentSha256: templateHash,
+                });
+            }
+        }
+        else if (isToolManaged && !force) {
+            // File exists, is tool-managed, but no --force - will skip
+            if (dryRun) {
+                operations.push(`SKIP ${relPath} (exists, tool-managed)`);
+            }
+            else {
+                ensureMarkerOnFile(dst);
+            }
+        }
+        else {
+            // File exists but NOT tool-managed (user-modified, orphan marker, or collision)
+            // Always skip, even with --force
+            if (dryRun) {
+                operations.push(`SKIP ${relPath} (exists, un-managed)`);
+            }
+            else {
+                ensureMarkerOnFile(dst);
+            }
+        }
     }
+    if (dryRun) {
+        for (const op of operations) {
+            console.log(op);
+        }
+        return;
+    }
+    // Update manifest groups (add if not present)
+    if (!manifest.groups.includes(group)) {
+        manifest.groups.push(group);
+    }
+    manifest.updatedAt = new Date().toISOString();
+    saveManifest(cwd, manifest);
     console.log('Installed group "' + group + '" into .cursor/commands (' + copied + " file(s) written).");
     if (group === "core")
         ensureMemory(cwd);
 }
 export function removeGroup(opts) {
-    const { cwd, group } = opts;
+    const { cwd, group, dryRun = false } = opts;
+    // Load manifest (doctor guarantees it exists, but handle gracefully)
+    let manifest = loadManifest(cwd);
+    if (!manifest) {
+        if (dryRun) {
+            console.log(`PLAN remove ${group} (dry-run)`);
+            console.log("SKIP manifest missing");
+            return;
+        }
+        // If manifest doesn't exist, create empty one to avoid errors
+        manifest = ensureManifest(cwd);
+    }
+    if (dryRun) {
+        console.log(`PLAN remove ${group} (dry-run)`);
+    }
     const outBase = path.join(cwd, ".cursor", "commands");
-    const files = GROUPS[group];
     let removed = 0;
     let skipped = 0;
-    for (const f of files) {
-        const dst = path.join(outBase, f);
-        if (!fs.existsSync(dst))
+    const operations = [];
+    // Find files in manifest that belong to this group
+    // templateId pattern: "commands/{group}/{filename}"
+    const groupPrefix = `commands/${group}/`;
+    const manifestFiles = manifest.files.filter((f) => f.templateId.startsWith(groupPrefix));
+    for (const manifestFile of manifestFiles) {
+        const dst = path.join(cwd, manifestFile.path);
+        // Safety: ensure path is under .cursor/commands
+        assertPathUnderCommands(cwd, dst);
+        if (!fs.existsSync(dst)) {
+            // File missing on disk
+            if (dryRun) {
+                operations.push(`IGNORE ${manifestFile.path} (missing on disk)`);
+            }
+            else {
+                // File missing on disk, remove from manifest
+                removeFile(manifest, manifestFile.path);
+            }
             continue;
-        // Only delete files we manage.
+        }
+        // Only delete files that have marker AND are in manifest
+        // Never delete just because it has a marker
         if (!fileContainsMarker(dst)) {
             skipped++;
+            if (dryRun) {
+                operations.push(`SKIP ${manifestFile.path} (not managed)`);
+            }
             continue;
         }
-        fs.unlinkSync(dst);
-        removed++;
+        // File has marker and is in manifest - safe to delete
+        if (dryRun) {
+            operations.push(`DELETE ${manifestFile.path}`);
+        }
+        else {
+            fs.unlinkSync(dst);
+            removeFile(manifest, manifestFile.path);
+            removed++;
+        }
+    }
+    // Check for orphan marker files (files with marker but not in manifest for this group)
+    if (fs.existsSync(outBase)) {
+        const manifestPaths = new Set(manifest.files.map((f) => f.path));
+        const entries = fs.readdirSync(outBase, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile()) {
+                const filePath = path.join(outBase, entry.name);
+                const relPath = path.relative(cwd, filePath).replace(/\\/g, "/");
+                // If file has marker but is not in manifest, it's an orphan
+                if (fileContainsMarker(filePath) && !manifestPaths.has(relPath)) {
+                    if (dryRun) {
+                        operations.push(`IGNORE ${relPath} (orphan marker, not in manifest)`);
+                    }
+                }
+            }
+        }
+    }
+    if (dryRun) {
+        for (const op of operations) {
+            console.log(op);
+        }
+        return;
+    }
+    // Remove group from manifest.groups if no files remain for this group
+    // Re-check after removals
+    const remainingGroupFiles = manifest.files.filter((f) => f.templateId.startsWith(groupPrefix));
+    if (remainingGroupFiles.length === 0 && manifest.groups.includes(group)) {
+        manifest.groups = manifest.groups.filter((g) => g !== group);
     }
+    manifest.updatedAt = new Date().toISOString();
+    saveManifest(cwd, manifest);
     console.log('Removed group "' + group + '" from .cursor/commands (' + removed + " file(s) deleted, " + skipped + " skipped).");
 }

package/dist/commands/doctor.js

@@ -0,0 +1,113 @@
+import fs from "fs";
+import path from "path";
+import { ensureMemory } from "./memory.js";
+import { loadManifest, saveManifest, createEmptyManifest, MANIFEST_REL, sha256 } from "./manifest.js";
+const REQUIRED = [
+    "docs/status.md",
+    "docs/todo.md",
+    "docs/decisions.md",
+    ".cursor/rules/project.md",
+];
+const MANAGED_MARKER = "<!-- managed-by: 4runr-cursor-setup -->";
+const COMMANDS_DIR = ".cursor/commands";
+function fileContainsMarker(p) {
+    if (!fs.existsSync(p))
+        return false;
+    const s = fs.readFileSync(p, "utf8");
+    return s.includes(MANAGED_MARKER);
+}
+export function doctor(cwd, toolVersion, opts) {
+    // Run fixes first if requested
+    if (opts.fix) {
+        ensureMemory(cwd, { dryRun: !!opts.dryRun });
+        // Always ensure manifest exists when --fix is used
+        if (!loadManifest(cwd)) {
+            const nm = createEmptyManifest(toolVersion);
+            saveManifest(cwd, nm, !!opts.dryRun);
+        }
+    }
+    // Collect issues after fixes have run
+    const issues = [];
+    for (const rel of REQUIRED) {
+        if (!fs.existsSync(path.join(cwd, rel))) {
+            issues.push({ level: "error", code: "MISSING_FILE", detail: rel });
+        }
+    }
+    const m = loadManifest(cwd);
+    if (!m) {
+        issues.push({ level: "warn", code: "MISSING_MANIFEST", detail: MANIFEST_REL });
+    }
+    else {
+        // Check manifest entries for missing files
+        for (const f of m.files) {
+            const filePath = path.join(cwd, f.path);
+            if (!fs.existsSync(filePath)) {
+                issues.push({
+                    level: "warn",
+                    code: "MANIFEST_ENTRY_MISSING_ON_DISK",
+                    detail: f.path,
+                });
+            }
+            else {
+                // Check for collisions: file exists but doesn't have marker or has wrong content
+                if (!fileContainsMarker(filePath)) {
+                    issues.push({
+                        level: "error",
+                        code: "COLLISION_UNMANAGED_FILE",
+                        detail: f.path,
+                    });
+                }
+                else {
+                    // Verify content hash matches (optional strict check)
+                    const currentContent = fs.readFileSync(filePath, "utf8");
+                    const currentHash = sha256(currentContent);
+                    if (currentHash !== f.contentSha256) {
+                        issues.push({
+                            level: "warn",
+                            code: "MANIFEST_FILE_MODIFIED",
+                            detail: f.path,
+                        });
+                    }
+                }
+            }
+        }
+        // Check for orphan marker files in .cursor/commands (files with marker but not in manifest)
+        const commandsDir = path.join(cwd, COMMANDS_DIR);
+        if (fs.existsSync(commandsDir)) {
+            const manifestPaths = new Set(m.files.map((f) => f.path));
+            const entries = fs.readdirSync(commandsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isFile()) {
+                    const filePath = path.join(commandsDir, entry.name);
+                    const relPath = path.relative(cwd, filePath).replace(/\\/g, "/");
+                    // If file has marker but is not in manifest, it's an orphan
+                    if (fileContainsMarker(filePath) && !manifestPaths.has(relPath)) {
+                        issues.push({
+                            level: "warn",
+                            code: "ORPHAN_MARKER_FILE",
+                            detail: relPath,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    const hasErrors = issues.some(i => i.level === "error");
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: !hasErrors, issues }, null, 2));
+    }
+    else {
+        if (issues.length === 0)
+            console.log("✅ doctor: OK");
+        else {
+            console.log("doctor report:");
+            for (const i of issues) {
+                console.log(`- ${i.level.toUpperCase()} ${i.code}: ${i.detail}`);
+            }
+        }
+    }
+    if (opts.strict && issues.length > 0)
+        process.exitCode = 1;
+    if (hasErrors)
+        process.exitCode = 1;
+}

package/dist/commands/manifest.js

@@ -0,0 +1,43 @@
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+export const MANIFEST_REL = ".cursor/4runr.manifest.json";
+export function sha256(s) {
+    return crypto.createHash("sha256").update(s, "utf8").digest("hex");
+}
+export function loadManifest(cwd) {
+    const fp = path.join(cwd, MANIFEST_REL);
+    if (!fs.existsSync(fp))
+        return null;
+    return JSON.parse(fs.readFileSync(fp, "utf8"));
+}
+export function saveManifest(cwd, m, dryRun = false) {
+    if (dryRun)
+        return;
+    const fp = path.join(cwd, MANIFEST_REL);
+    fs.mkdirSync(path.dirname(fp), { recursive: true });
+    fs.writeFileSync(fp, JSON.stringify(m, null, 2) + "\n", "utf8");
+}
+export function createEmptyManifest(toolVersion) {
+    return {
+        schemaVersion: 1,
+        tool: "4runr-cursor-setup",
+        toolVersion,
+        updatedAt: new Date().toISOString(),
+        groups: [],
+        files: [],
+    };
+}
+export function upsertFile(m, rec) {
+    const i = m.files.findIndex(f => f.path === rec.path);
+    if (i >= 0)
+        m.files[i] = rec;
+    else
+        m.files.push(rec);
+}
+export function removeFile(m, relPath) {
+    m.files = m.files.filter(f => f.path !== relPath);
+}
+export function hasFile(m, relPath) {
+    return m.files.some(f => f.path === relPath);
+}

package/dist/commands/memory.js

@@ -1,35 +1,19 @@
-import * as fs from "fs";
-import * as path from "path";
-import * as url from "url";
-function ensureDir(p) {
-    fs.mkdirSync(p, { recursive: true });
-}
-function copyIfMissing(src, dst) {
-    if (fs.existsSync(dst))
-        return false;
-    ensureDir(path.dirname(dst));
-    fs.copyFileSync(src, dst);
-    return true;
-}
-function getTemplatesRoot() {
-    const here = path.dirname(url.fileURLToPath(import.meta.url));
-    return path.resolve(here, "..", "templates");
-}
-export function ensureMemory(cwd) {
-    const root = getTemplatesRoot();
-    const srcBase = path.join(root, "memory");
-    const mappings = [
-        { src: path.join(srcBase, "docs", "status.md"), dst: path.join(cwd, "docs", "status.md") },
-        { src: path.join(srcBase, "docs", "todo.md"), dst: path.join(cwd, "docs", "todo.md") },
-        { src: path.join(srcBase, "docs", "decisions.md"), dst: path.join(cwd, "docs", "decisions.md") },
-        { src: path.join(srcBase, "cursor", "project.md"), dst: path.join(cwd, ".cursor", "rules", "project.md") },
+import fs from "fs";
+import path from "path";
+export function ensureMemory(cwd, opts) {
+    const files = [
+        "docs/status.md",
+        "docs/todo.md",
+        "docs/decisions.md",
+        ".cursor/rules/project.md",
     ];
-    let created = 0;
-    for (const m of mappings) {
-        if (!fs.existsSync(m.src))
-            throw new Error("Template missing: " + m.src);
-        if (copyIfMissing(m.src, m.dst))
-            created++;
+    for (const rel of files) {
+        const fp = path.join(cwd, rel);
+        if (fs.existsSync(fp))
+            continue;
+        if (!opts?.dryRun) {
+            fs.mkdirSync(path.dirname(fp), { recursive: true });
+            fs.writeFileSync(fp, "", "utf8");
+        }
     }
-    console.log(`Memory ensured (created ${created} file(s), left existing untouched).`);
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "4runr-cursor-setup",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "node --test test/*.test.js",
     "dev": "tsx src/cli.ts",
     "build": "tsc",
     "prepublishOnly": "npm run build",