4runr-cursor-setup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 4Runr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { init } from "./commands/init.js";
+const args = process.argv.slice(2);
+const cmd = args[0];
+async function main() {
+    if (cmd === "init") {
+        await init({ cwd: process.cwd() });
+        return;
+    }
+    console.log("4runr-cursor-setup");
+    console.log("Usage: 4runr-cursor-setup init");
+    process.exit(1);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/commands/init.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function ensureDir(p) {
+    fs.mkdirSync(p, { recursive: true });
+}
+function writeFileIfMissing(filePath, content) {
+    if (!fs.existsSync(filePath))
+        fs.writeFileSync(filePath, content, "utf8");
+}
+function copyDir(srcDir, destDir) {
+    ensureDir(destDir);
+    for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+        const src = path.join(srcDir, entry.name);
+        const dst = path.join(destDir, entry.name);
+        if (entry.isDirectory())
+            copyDir(src, dst);
+        else if (entry.isFile()) {
+            const content = fs.readFileSync(src, "utf8");
+            writeFileIfMissing(dst, content);
+        }
+    }
+}
+export async function init({ cwd }) {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    // src/commands -> src
+    const srcRoot = path.resolve(__dirname, "..");
+    const templatesRoot = path.join(srcRoot, "templates");
+    copyDir(path.join(templatesRoot, "docs"), path.join(cwd, "docs"));
+    copyDir(path.join(templatesRoot, "plans"), path.join(cwd, "plans"));
+    const cursorRulesDir = path.join(cwd, ".cursor", "rules");
+    ensureDir(cursorRulesDir);
+    const projectRuleSrc = path.join(templatesRoot, "cursor", "project.md");
+    const projectRuleDst = path.join(cursorRulesDir, "project.md");
+    writeFileIfMissing(projectRuleDst, fs.readFileSync(projectRuleSrc, "utf8"));
+    const promptSrc = path.join(templatesRoot, "PROMPT_START.md");
+    const promptDst = path.join(cwd, "PROMPT_START.md");
+    writeFileIfMissing(promptDst, fs.readFileSync(promptSrc, "utf8"));
+    console.log("Created Cursor project scaffold:");
+    console.log(" - docs/*");
+    console.log(" - .cursor/rules/project.md");
+    console.log(" - plans/*");
+    console.log(" - PROMPT_START.md");
+}

package/dist/templates/PROMPT_START.md

@@ -0,0 +1,60 @@
+# Project Initialization Prompt
+
+You are now operating inside a specific project context.
+
+Before doing anything else, you must:
+
+1. Read and internalize the following files (if they exist):
+   - `docs/scope.md`
+   - `docs/architecture.md`
+   - `docs/constraints.md`
+   - `docs/decisions.md`
+   - `docs/todo.md`
+   - `.cursor/rules/project.md`
+
+2. Treat these files as the source of truth for this project.
+   - If chat instructions conflict with these files, the files override chat.
+   - Do not invent requirements, architecture, or constraints that are not explicitly stated.
+
+3. If any of these files are missing, incomplete, or ambiguous:
+   - Call it out explicitly.
+   - Ask targeted clarifying questions.
+   - Do NOT guess.
+
+---
+
+## Operating Mode for This Project
+
+### Planning-First Workflow
+- Do not jump into implementation.
+- Always propose a step-by-step plan before non-trivial work.
+- Ask clarifying questions if you are less than 90% confident.
+- Wait for approval before executing the plan.
+
+### Atomic Execution
+- Break work into small, isolated steps.
+- Do not batch large changes.
+- Do not refactor multiple systems at once.
+- Request confirmation before large or structural changes.
+
+### Context Discipline
+- Treat context as limited system memory.
+- Warn if context may be insufficient.
+- Prefer file-based memory over chat memory.
+- Ask for missing information instead of guessing.
+
+### Transparency
+- Be explicit about what you change and why.
+- Never claim something works unless it was actually verified.
+- Clearly distinguish between theoretical correctness and verified correctness.
+
+---
+
+## Confirmation
+
+First, confirm that you have:
+1. Read the project files
+2. Understood the scope and constraints
+3. Identified any missing or unclear information
+
+Then summarize your understanding of the system in 5–10 bullet points before doing any work.

package/dist/templates/cursor/project.md

@@ -0,0 +1,33 @@
+# Project Rules
+
+## Stack
+- Language(s):
+- Framework(s):
+- Runtime:
+- Package manager:
+- DB / storage:
+- Hosting:
+
+## Commands
+- Install:
+- Dev:
+- Build:
+- Test:
+- Lint:
+- Typecheck:
+
+## Architecture Rules
+- Where does business logic live:
+- Where do API routes live:
+- Data access patterns:
+- Error handling pattern:
+- Logging / observability pattern:
+
+## Code Style
+- Naming conventions:
+- Formatting:
+- Testing style:
+
+## Forbidden / Avoid
+- Do not:
+- Avoid:

package/dist/templates/docs/architecture.md

@@ -0,0 +1,16 @@
+# Architecture
+
+## Overview
+- 
+
+## Components
+- 
+
+## Data Flow
+- 
+
+## External Services
+- 
+
+## Security Model
+- 

package/dist/templates/docs/constraints.md

@@ -0,0 +1,16 @@
+# Constraints
+
+## Technical
+- 
+
+## Security
+- 
+
+## Performance
+- 
+
+## Compliance (if any)
+- 
+
+## Scale Assumptions
+- 

package/dist/templates/docs/decisions.md

@@ -0,0 +1,21 @@
+# Decisions
+
+Use this format for each decision:
+
+## Decision: <title>
+**Date:** YYYY-MM-DD  
+**Status:** Proposed | Accepted | Deprecated
+
+### Context
+- 
+
+### Options Considered
+1. 
+2. 
+3. 
+
+### Decision
+- 
+
+### Trade-offs / Consequences
+- 

package/dist/templates/docs/scope.md

@@ -0,0 +1,16 @@
+# Scope
+
+## Purpose
+- 
+
+## Users
+- 
+
+## Core Features
+- 
+
+## Non-goals
+- 
+
+## Success Criteria
+- 

package/dist/templates/docs/todo.md

@@ -0,0 +1,13 @@
+# TODO
+
+## Now
+- 
+
+## Next
+- 
+
+## Blocked
+- 
+
+## Open Questions
+- 

package/dist/templates/plans/README.md

@@ -0,0 +1,4 @@
+# Plans
+
+Store approved plans here (one file per feature).
+Example: plans/auth.md, plans/dashboard.md

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "4runr-cursor-setup",
+  "version": "0.1.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "dev": "tsx src/cli.ts",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "postbuild": "node scripts/copy-templates.cjs && node scripts/add-shebang.cjs"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "bin": {
+    "4runr-cursor-setup": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src/templates",
+    "README.md",
+    "LICENSE",
+    "scripts"
+  ]
+}

package/scripts/add-shebang.cjs

@@ -0,0 +1,18 @@
+const fs = require("fs");
+
+const file = "dist/cli.js";
+if (!fs.existsSync(file)) {
+  console.error(`[add-shebang] Missing ${file}. Run build first.`);
+  process.exit(1);
+}
+
+let content = fs.readFileSync(file, "utf8");
+
+// Add shebang only if it's not already there
+if (!content.startsWith("#!/usr/bin/env node")) {
+  content = "#!/usr/bin/env node\n" + content;
+  fs.writeFileSync(file, content, "utf8");
+  console.log("[add-shebang] Added shebang to dist/cli.js");
+} else {
+  console.log("[add-shebang] Shebang already present");
+}

package/scripts/copy-templates.cjs

@@ -0,0 +1,23 @@
+const fs = require("fs");
+const path = require("path");
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(srcPath, destPath);
+    else fs.copyFileSync(srcPath, destPath);
+  }
+}
+
+const srcTemplates = path.join(process.cwd(), "src", "templates");
+const distTemplates = path.join(process.cwd(), "dist", "templates");
+
+if (!fs.existsSync(srcTemplates)) {
+  console.error(`[copy-templates] Missing ${srcTemplates}`);
+  process.exit(1);
+}
+
+copyDir(srcTemplates, distTemplates);
+console.log("[copy-templates] Copied src/templates -> dist/templates");

package/src/templates/PROMPT_START.md

@@ -0,0 +1,60 @@
+# Project Initialization Prompt
+
+You are now operating inside a specific project context.
+
+Before doing anything else, you must:
+
+1. Read and internalize the following files (if they exist):
+   - `docs/scope.md`
+   - `docs/architecture.md`
+   - `docs/constraints.md`
+   - `docs/decisions.md`
+   - `docs/todo.md`
+   - `.cursor/rules/project.md`
+
+2. Treat these files as the source of truth for this project.
+   - If chat instructions conflict with these files, the files override chat.
+   - Do not invent requirements, architecture, or constraints that are not explicitly stated.
+
+3. If any of these files are missing, incomplete, or ambiguous:
+   - Call it out explicitly.
+   - Ask targeted clarifying questions.
+   - Do NOT guess.
+
+---
+
+## Operating Mode for This Project
+
+### Planning-First Workflow
+- Do not jump into implementation.
+- Always propose a step-by-step plan before non-trivial work.
+- Ask clarifying questions if you are less than 90% confident.
+- Wait for approval before executing the plan.
+
+### Atomic Execution
+- Break work into small, isolated steps.
+- Do not batch large changes.
+- Do not refactor multiple systems at once.
+- Request confirmation before large or structural changes.
+
+### Context Discipline
+- Treat context as limited system memory.
+- Warn if context may be insufficient.
+- Prefer file-based memory over chat memory.
+- Ask for missing information instead of guessing.
+
+### Transparency
+- Be explicit about what you change and why.
+- Never claim something works unless it was actually verified.
+- Clearly distinguish between theoretical correctness and verified correctness.
+
+---
+
+## Confirmation
+
+First, confirm that you have:
+1. Read the project files
+2. Understood the scope and constraints
+3. Identified any missing or unclear information
+
+Then summarize your understanding of the system in 5–10 bullet points before doing any work.

package/src/templates/cursor/project.md

@@ -0,0 +1,33 @@
+# Project Rules
+
+## Stack
+- Language(s):
+- Framework(s):
+- Runtime:
+- Package manager:
+- DB / storage:
+- Hosting:
+
+## Commands
+- Install:
+- Dev:
+- Build:
+- Test:
+- Lint:
+- Typecheck:
+
+## Architecture Rules
+- Where does business logic live:
+- Where do API routes live:
+- Data access patterns:
+- Error handling pattern:
+- Logging / observability pattern:
+
+## Code Style
+- Naming conventions:
+- Formatting:
+- Testing style:
+
+## Forbidden / Avoid
+- Do not:
+- Avoid:

package/src/templates/docs/architecture.md

@@ -0,0 +1,16 @@
+# Architecture
+
+## Overview
+- 
+
+## Components
+- 
+
+## Data Flow
+- 
+
+## External Services
+- 
+
+## Security Model
+- 

package/src/templates/docs/constraints.md

@@ -0,0 +1,16 @@
+# Constraints
+
+## Technical
+- 
+
+## Security
+- 
+
+## Performance
+- 
+
+## Compliance (if any)
+- 
+
+## Scale Assumptions
+- 

package/src/templates/docs/decisions.md

@@ -0,0 +1,21 @@
+# Decisions
+
+Use this format for each decision:
+
+## Decision: <title>
+**Date:** YYYY-MM-DD  
+**Status:** Proposed | Accepted | Deprecated
+
+### Context
+- 
+
+### Options Considered
+1. 
+2. 
+3. 
+
+### Decision
+- 
+
+### Trade-offs / Consequences
+- 

package/src/templates/docs/scope.md

@@ -0,0 +1,16 @@
+# Scope
+
+## Purpose
+- 
+
+## Users
+- 
+
+## Core Features
+- 
+
+## Non-goals
+- 
+
+## Success Criteria
+- 

package/src/templates/docs/todo.md

@@ -0,0 +1,13 @@
+# TODO
+
+## Now
+- 
+
+## Next
+- 
+
+## Blocked
+- 
+
+## Open Questions
+- 

package/src/templates/plans/README.md

@@ -0,0 +1,4 @@
+# Plans
+
+Store approved plans here (one file per feature).
+Example: plans/auth.md, plans/dashboard.md