4runr-cursor-setup 0.1.11 → 0.1.15

package/README.md

@@ -0,0 +1,77 @@
+# 4runr-cursor-setup
+
+## Golden Path
+
+```bash
+# Repair / normalize any repo (safe)
+npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict
+
+# Install core commands
+npx -y 4runr-cursor-setup@latest add core
+
+# CI / health check (fails if issues)
+npx -y 4runr-cursor-setup@latest doctor --strict
+
+# Machine-readable audit (for automation)
+npx -y 4runr-cursor-setup@latest doctor --json
+```
+
+## Contract / Invariants
+
+- Tool never overwrites un-managed files (even with `--force`)
+- `--force` overwrites only tool-managed files (marker + manifest)
+- `remove <group>` deletes only manifest-owned files (marker + manifest entry)
+- `doctor --purge-orphans` deletes only marker files not in manifest
+- `doctor --strict` exits non-zero only when final issues exist
+
+## Usage
+
+```bash
+# List available command groups
+npx -y 4runr-cursor-setup@latest list
+
+# Add a command group
+npx -y 4runr-cursor-setup@latest add <group> [--force] [--dry-run]
+
+# Remove a command group
+npx -y 4runr-cursor-setup@latest remove <group> [--dry-run]
+
+# Audit and repair
+npx -y 4runr-cursor-setup@latest doctor [--fix] [--strict] [--json] [--dry-run] [--purge-orphans]
+```
+
+## Available Groups
+
+- `core`: Essential 4runr commands (start, close)
+- `planning`: Planning commands (phase, task)
+- `governance`: Governance commands (decision, scope-change)
+- `debugging`: Debugging commands (repro, verify)
+
+## Troubleshooting
+
+### npx Cache Issues
+
+If `npx -y 4runr-cursor-setup@latest` fails with `ETARGET` but the version exists on npm:
+
+This is an npx cache desync. Clear the cache and retry:
+
+```bash
+npm cache clean --force
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue
+```
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run smoke test
+npm run test:smoke
+
+# Development mode
+npm run dev
+```

package/dist/cli.js

@@ -9,7 +9,7 @@ function usage() {
     console.log("  list");
     console.log("  add <group> [--force] [--dry-run]");
     console.log("  remove <group> [--dry-run]");
-    console.log("  doctor [--fix] [--strict] [--json] [--dry-run] [--purge-orphans]");
+    console.log("  doctor [--fix] [--strict] [--json] [--dry-run] [--purge-orphans] [--plan]");
     console.log("");
     console.log("Groups: " + Object.keys(GROUPS).join(", "));
     console.log("");
@@ -69,6 +69,7 @@ if (cmd === "doctor") {
         strict: has("--strict"),
         dryRun: has("--dry-run"),
         purgeOrphans: has("--purge-orphans"),
+        plan: has("--plan"),
     });
     // Exit with the exit code set by doctor (or 0 if not set)
     process.exit(process.exitCode || 0);

package/dist/commands/doctor.js

@@ -185,24 +185,52 @@ export function doctor(cwd, toolVersion, opts) {
         }
     }
     const hasErrors = issues.some(i => i.level === "error");
+    // Generate plan if requested
+    let planItems = [];
+    if (opts.plan) {
+        planItems = generatePlan(issues, m || null);
+    }
     if (opts.json) {
         const jsonOutput = { ok: !hasErrors, issues };
         if (purgedInfo) {
             jsonOutput.purged = { count: purgedInfo.count, files: purgedInfo.files };
         }
+        if (opts.plan) {
+            jsonOutput.plan = planItems;
+        }
         console.log(JSON.stringify(jsonOutput, null, 2));
     }
     else {
-        if (issues.length === 0)
-            console.log("✅ doctor: OK");
+        if (opts.plan) {
+            // Plan output mode
+            if (planItems.length === 0) {
+                console.log("PLAN (doctor)");
+                console.log("No actions needed.");
+            }
+            else {
+                console.log("PLAN (doctor)");
+                for (let i = 0; i < planItems.length; i++) {
+                    const item = planItems[i];
+                    console.log(`${i + 1}) ${item.code}: ${item.detail}`);
+                    for (const step of item.steps) {
+                        console.log(`   - ${step}`);
+                    }
+                }
+            }
+        }
         else {
-            console.log("doctor report:");
-            for (const i of issues) {
-                let line = `- ${i.level.toUpperCase()} ${i.code}: ${i.detail}`;
-                if (i.hint) {
-                    line += `\n  ${i.hint}`;
+            // Normal output mode
+            if (issues.length === 0)
+                console.log("✅ doctor: OK");
+            else {
+                console.log("doctor report:");
+                for (const i of issues) {
+                    let line = `- ${i.level.toUpperCase()} ${i.code}: ${i.detail}`;
+                    if (i.hint) {
+                        line += `\n  ${i.hint}`;
+                    }
+                    console.log(line);
                 }
-                console.log(line);
             }
         }
     }
@@ -212,3 +240,103 @@ export function doctor(cwd, toolVersion, opts) {
     if (hasErrors)
         process.exitCode = 1;
 }
+function inferGroupFromPath(filePath, manifest) {
+    // Try to find the file in manifest to get templateId
+    if (manifest) {
+        const fileEntry = manifest.files.find((f) => f.path === filePath);
+        if (fileEntry && fileEntry.templateId) {
+            // templateId format: "commands/{group}/{filename}"
+            const parts = fileEntry.templateId.split("/");
+            if (parts.length >= 2 && parts[0] === "commands") {
+                return parts[1];
+            }
+        }
+    }
+    // Try to infer from filename pattern (e.g., "4runr-start.md" -> "core")
+    const filename = path.basename(filePath);
+    if (filename.startsWith("4runr-")) {
+        // Map common patterns (this is a fallback, not perfect)
+        if (filename.includes("start") || filename.includes("close"))
+            return "core";
+        if (filename.includes("task") || filename.includes("phase"))
+            return "planning";
+        if (filename.includes("decision") || filename.includes("scope"))
+            return "governance";
+        if (filename.includes("repro") || filename.includes("verify"))
+            return "debugging";
+    }
+    return null;
+}
+function generatePlan(issues, manifest) {
+    const planItems = [];
+    for (const issue of issues) {
+        let planItem = null;
+        switch (issue.code) {
+            case "MISSING_MANIFEST":
+                planItem = {
+                    code: issue.code,
+                    detail: issue.detail,
+                    action: "Create baseline manifest",
+                    steps: [
+                        "npx -y 4runr-cursor-setup@latest doctor --fix"
+                    ]
+                };
+                break;
+            case "ORPHAN_MARKER_FILE":
+                planItem = {
+                    code: issue.code,
+                    detail: issue.detail,
+                    action: "Purge orphan marker files",
+                    steps: [
+                        "npx -y 4runr-cursor-setup@latest doctor --purge-orphans",
+                        "npx -y 4runr-cursor-setup@latest doctor --strict"
+                    ]
+                };
+                break;
+            case "COLLISION_UNMANAGED_FILE":
+                const group = inferGroupFromPath(issue.detail, manifest);
+                const groupPlaceholder = group || "<group>";
+                planItem = {
+                    code: issue.code,
+                    detail: issue.detail,
+                    action: "Resolve collision at managed path",
+                    steps: [
+                        `Manual: rename or move ${issue.detail}`,
+                        `Then run: npx -y 4runr-cursor-setup@latest add ${groupPlaceholder}`
+                    ]
+                };
+                break;
+            case "MANIFEST_ENTRY_MISSING_ON_DISK":
+                const missingGroup = inferGroupFromPath(issue.detail, manifest);
+                const missingGroupPlaceholder = missingGroup || "<group>";
+                planItem = {
+                    code: issue.code,
+                    detail: issue.detail,
+                    action: "Restore missing tool-managed file",
+                    steps: [
+                        `Run: npx -y 4runr-cursor-setup@latest add ${missingGroupPlaceholder}`,
+                        `If still missing: npx -y 4runr-cursor-setup@latest add ${missingGroupPlaceholder} --force`
+                    ]
+                };
+                break;
+            case "MANIFEST_FILE_MODIFIED":
+                const modifiedGroup = inferGroupFromPath(issue.detail, manifest);
+                const modifiedGroupPlaceholder = modifiedGroup || "<group>";
+                planItem = {
+                    code: issue.code,
+                    detail: issue.detail,
+                    action: "Resolve modified managed file",
+                    steps: [
+                        `Manual: keep file as-is (tool will not overwrite), OR`,
+                        `Manual: delete ${issue.detail} if you want template restored`,
+                        `Then run: npx -y 4runr-cursor-setup@latest add ${modifiedGroupPlaceholder}`
+                    ]
+                };
+                break;
+        }
+        if (planItem) {
+            planItems.push(planItem);
+        }
+    }
+    return planItems;
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "4runr-cursor-setup",
-  "version": "0.1.11",
+  "version": "0.1.15",
   "description": "",
   "main": "index.js",
   "scripts": {
     "test": "node --test test/*.test.js",
+    "test:smoke": "powershell -ExecutionPolicy Bypass -File scripts/smoke.ps1",
     "dev": "tsx src/cli.ts",
     "build": "tsc",
     "prepublishOnly": "npm run build",

package/scripts/smoke.ps1

@@ -0,0 +1,87 @@
+# Smoke test for 4runr-cursor-setup golden path
+# Runs in a temp directory to avoid dirtying the repo
+
+$ErrorActionPreference = "Stop"
+
+# Get the repo root (where package.json lives)
+$repoRoot = Split-Path -Parent $PSScriptRoot
+$cliPath = Join-Path $repoRoot "dist\cli.js"
+
+if (-not (Test-Path $cliPath)) {
+    Write-Host "ERROR: dist/cli.js not found. Run 'npm run build' first." -ForegroundColor Red
+    exit 1
+}
+
+# Create temp directory for testing
+$tempDir = [System.IO.Path]::Combine([System.IO.Path]::GetTempPath(), "4runr-smoke-$(New-Guid)")
+New-Item -ItemType Directory -Path $tempDir -Force | Out-Null
+
+try {
+    Write-Host "=== Smoke Test: Golden Path ===" -ForegroundColor Cyan
+    Write-Host "Test directory: $tempDir" -ForegroundColor Gray
+    Write-Host ""
+
+    # Step 1: doctor --fix --purge-orphans --strict
+    Write-Host "Step 1: doctor --fix --purge-orphans --strict" -ForegroundColor Yellow
+    Push-Location $tempDir
+    $exitCode = 0
+    node $cliPath doctor --fix --purge-orphans --strict 2>&1 | Out-String | Write-Host
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "FAILED: doctor --fix --purge-orphans --strict exited with code $LASTEXITCODE" -ForegroundColor Red
+        $exitCode = 1
+    } else {
+        Write-Host "PASSED: doctor --fix --purge-orphans --strict" -ForegroundColor Green
+    }
+    Pop-Location
+    Write-Host ""
+
+    if ($exitCode -ne 0) {
+        exit $exitCode
+    }
+
+    # Step 2: add core
+    Write-Host "Step 2: add core" -ForegroundColor Yellow
+    Push-Location $tempDir
+    node $cliPath add core 2>&1 | Out-String | Write-Host
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "FAILED: add core exited with code $LASTEXITCODE" -ForegroundColor Red
+        $exitCode = 1
+    } else {
+        Write-Host "PASSED: add core" -ForegroundColor Green
+    }
+    Pop-Location
+    Write-Host ""
+
+    if ($exitCode -ne 0) {
+        exit $exitCode
+    }
+
+    # Step 3: doctor --strict (should pass after fix + add)
+    Write-Host "Step 3: doctor --strict" -ForegroundColor Yellow
+    Push-Location $tempDir
+    node $cliPath doctor --strict 2>&1 | Out-String | Write-Host
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "FAILED: doctor --strict exited with code $LASTEXITCODE" -ForegroundColor Red
+        $exitCode = 1
+    } else {
+        Write-Host "PASSED: doctor --strict" -ForegroundColor Green
+    }
+    Pop-Location
+    Write-Host ""
+
+    if ($exitCode -ne 0) {
+        exit $exitCode
+    }
+
+    Write-Host "=== All smoke tests passed ===" -ForegroundColor Green
+    exit 0
+
+} catch {
+    Write-Host "ERROR: $($_.Exception.Message)" -ForegroundColor Red
+    exit 1
+} finally {
+    # Cleanup temp directory
+    if (Test-Path $tempDir) {
+        Remove-Item -Path $tempDir -Recurse -Force -ErrorAction SilentlyContinue
+    }
+}