planforge 0.1.0

package/dist/providers/registry.js

@@ -0,0 +1,42 @@
+/**
+ * Provider registry: route plan/implement by provider name from planforge.json.
+ * Add new providers here and implement check + runPlan/runImplement in their module.
+ */
+import * as claude from "./claude.js";
+import * as codex from "./codex.js";
+const claudePlanner = {
+    check: () => claude.checkClaude(),
+    runPlan: (goal, opts) => claude.runPlan(goal, opts),
+};
+const codexPlanner = {
+    check: () => codex.checkCodex(),
+    runPlan: (goal, opts) => codex.runPlan(goal, opts),
+};
+const claudeImplementer = {
+    check: () => claude.checkClaude(),
+    runImplement: (prompt, opts) => claude.runImplement(prompt, opts),
+};
+const codexImplementer = {
+    check: () => codex.checkCodex(),
+    runImplement: (prompt, opts) => codex.runImplement(prompt, opts),
+};
+export function getPlannerRunner(provider) {
+    switch (provider) {
+        case "claude":
+            return claudePlanner;
+        case "codex":
+            return codexPlanner;
+        default:
+            return null;
+    }
+}
+export function getImplementerRunner(provider) {
+    switch (provider) {
+        case "claude":
+            return claudeImplementer;
+        case "codex":
+            return codexImplementer;
+        default:
+            return null;
+    }
+}

package/dist/templates/install.js

@@ -0,0 +1,34 @@
+/**
+ * Copy PlanForge templates (skills, rules, config) into project
+ */
+import fs from "fs-extra";
+import { resolve } from "path";
+import { getTemplatesRoot } from "../utils/paths.js";
+export async function installTemplates(projectRoot, options = {}) {
+    const templatesRoot = getTemplatesRoot();
+    const cursorDir = resolve(projectRoot, ".cursor");
+    const cursorTemplates = resolve(templatesRoot, "cursor");
+    await fs.ensureDir(cursorDir);
+    const skillsSrc = resolve(cursorTemplates, "skills");
+    const skillsDest = resolve(cursorDir, "skills");
+    await fs.ensureDir(skillsDest);
+    if (await fs.pathExists(resolve(skillsSrc, "p"))) {
+        await fs.copy(resolve(skillsSrc, "p"), resolve(skillsDest, "p"), { overwrite: true });
+    }
+    if (await fs.pathExists(resolve(skillsSrc, "i"))) {
+        await fs.copy(resolve(skillsSrc, "i"), resolve(skillsDest, "i"), { overwrite: true });
+    }
+    const rulesSrc = resolve(cursorTemplates, "rules");
+    const rulesDest = resolve(cursorDir, "rules");
+    if (await fs.pathExists(rulesSrc)) {
+        await fs.ensureDir(rulesDest);
+        await fs.copy(rulesSrc, rulesDest, { overwrite: true });
+    }
+    const configSrc = resolve(templatesRoot, "config", "planforge.json");
+    const configDest = resolve(projectRoot, "planforge.json");
+    if (await fs.pathExists(configSrc)) {
+        if (options.force || !(await fs.pathExists(configDest))) {
+            await fs.copy(configSrc, configDest, { overwrite: true });
+        }
+    }
+}

package/dist/utils/active-plan.js

@@ -0,0 +1,51 @@
+/**
+ * Resolve which plan file to use for implement: index.json activePlan or latest .plan.md by mtime.
+ */
+import { existsSync, statSync, readFileSync, readdirSync } from "fs";
+import { resolve, join } from "path";
+import { getPlansDir } from "./paths.js";
+const INDEX_JSON = "index.json";
+export function getActivePlanPath(projectRoot) {
+    const plansDir = getPlansDir(projectRoot);
+    if (!existsSync(plansDir))
+        return null;
+    const indexPath = join(plansDir, INDEX_JSON);
+    if (existsSync(indexPath)) {
+        try {
+            const raw = readFileSync(indexPath, "utf-8");
+            const data = JSON.parse(raw);
+            const name = data.activePlan?.trim();
+            if (name) {
+                const candidate = resolve(plansDir, name);
+                if (existsSync(candidate))
+                    return candidate;
+                const withExt = name.endsWith(".plan.md") ? name : `${name}.plan.md`;
+                const candidate2 = resolve(plansDir, withExt);
+                if (existsSync(candidate2))
+                    return candidate2;
+            }
+        }
+        catch {
+            /* ignore invalid index.json */
+        }
+    }
+    let latestPath = null;
+    let latestMtime = 0;
+    try {
+        const entries = readdirSync(plansDir, { withFileTypes: true });
+        for (const e of entries) {
+            if (!e.isFile() || !e.name.endsWith(".plan.md"))
+                continue;
+            const full = join(plansDir, e.name);
+            const mtime = statSync(full).mtimeMs;
+            if (mtime > latestMtime) {
+                latestMtime = mtime;
+                latestPath = full;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return latestPath;
+}

package/dist/utils/fs.js

@@ -0,0 +1,15 @@
+/**
+ * File system utilities
+ */
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname } from "path";
+export async function ensureDir(path) {
+    await mkdir(dirname(path), { recursive: true });
+}
+export async function readText(path) {
+    return readFile(path, "utf-8");
+}
+export async function writeText(path, content) {
+    await ensureDir(path);
+    await writeFile(path, content, "utf-8");
+}

package/dist/utils/paths.js

@@ -0,0 +1,30 @@
+/**
+ * Path resolution for PlanForge (project root, .cursor, plans dir)
+ */
+import { existsSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Find project root by walking up from cwd until we find planforge.json or .cursor.
+ */
+export function getProjectRoot(cwd = process.cwd()) {
+    let dir = resolve(cwd);
+    const root = resolve(dir, "..");
+    while (dir !== root) {
+        if (existsSync(resolve(dir, "planforge.json")) || existsSync(resolve(dir, ".cursor"))) {
+            return dir;
+        }
+        dir = resolve(dir, "..");
+    }
+    return cwd;
+}
+export function getPlansDir(projectRoot) {
+    return resolve(projectRoot, ".cursor", "plans");
+}
+/**
+ * Resolve path relative to CLI package (for templates).
+ */
+export function getTemplatesRoot() {
+    return resolve(__dirname, "..", "..", "..", "..", "templates");
+}

package/dist/utils/plan-files.js

@@ -0,0 +1,42 @@
+/**
+ * Parse "## Files Likely to Change" section from plan markdown and return file paths/globs.
+ * Lines like "- path" or "- `path`" are extracted; globs are kept as-is for "files to focus on" text.
+ */
+const SECTION_HEADING = "## Files Likely to Change";
+const LIST_ITEM_RE = /^[-*]\s+(?:`([^`]+)`|(.+))$/;
+/**
+ * Extract file paths from the "Files Likely to Change" section of a plan document.
+ * Returns unique non-empty paths (backticks stripped). Globs are included as strings.
+ */
+export function parseFilesFromPlan(planContent) {
+    if (!planContent?.trim())
+        return [];
+    const lines = planContent.split(/\r?\n/);
+    let inSection = false;
+    const seen = new Set();
+    const paths = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("## ")) {
+            if (trimmed.toLowerCase().startsWith(SECTION_HEADING.toLowerCase())) {
+                inSection = true;
+                continue;
+            }
+            inSection = false;
+            continue;
+        }
+        if (!inSection)
+            continue;
+        const m = trimmed.match(LIST_ITEM_RE);
+        if (!m)
+            continue;
+        const path = (m[1] ?? m[2] ?? "").trim().replace(/^\/+/, "").replace(/\\/g, "/");
+        if (!path || path.includes(".."))
+            continue;
+        if (seen.has(path))
+            continue;
+        seen.add(path);
+        paths.push(path);
+    }
+    return paths;
+}

package/dist/utils/project-context.js

@@ -0,0 +1,30 @@
+/**
+ * Read AGENTS.md or CLAUDE.md from project root for plan/implement context. Capped in size.
+ */
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+const MAX_PROJECT_CONTEXT_CHARS = 3500;
+const CANDIDATES = ["AGENTS.md", "CLAUDE.md"];
+/**
+ * Read project context from AGENTS.md or CLAUDE.md (first existing). Returns undefined if none found or on error.
+ */
+export function getProjectContext(projectRoot) {
+    for (const name of CANDIDATES) {
+        const path = join(projectRoot, name);
+        try {
+            if (!existsSync(path))
+                continue;
+            const content = readFileSync(path, "utf-8").trim();
+            if (!content)
+                continue;
+            if (content.length > MAX_PROJECT_CONTEXT_CHARS) {
+                return content.slice(0, MAX_PROJECT_CONTEXT_CHARS) + "\n...(truncated)";
+            }
+            return content;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return undefined;
+}

package/dist/utils/repo-context.js

@@ -0,0 +1,238 @@
+/**
+ * Collect repository context (git status, diff stat, directory structure) for plan prompts.
+ * Optionally appends goal-based ripgrep results when goal is provided. Capped to avoid token overflow.
+ */
+import { spawnSync } from "child_process";
+import { readdirSync } from "fs";
+const MAX_REPO_CONTEXT_CHARS = 3500;
+const MAX_RIPGREP_CONTEXT_CHARS = 2000;
+const MAX_REPO_CONTEXT_WITH_RG_CHARS = 5000;
+const MAX_RIPGREP_FILES = 15;
+const MAX_RECENT_COMMITS_CHARS = 500;
+const MAX_GOAL_FILES_LOG_CHARS = 600;
+const MAX_GOAL_FILES_LOG_FILES = 5;
+const SKIP_DIRS = new Set([".git", "node_modules", ".cursor", "dist", "build", "__pycache__", ".venv", "venv"]);
+function runGit(cwd, args) {
+    try {
+        const result = spawnSync("git", args, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+        if (result.status !== 0)
+            return null;
+        return (result.stdout ?? "").trim();
+    }
+    catch {
+        return null;
+    }
+}
+function isGitRepo(cwd) {
+    const out = runGit(cwd, ["rev-parse", "--is-inside-work-tree"]);
+    return out === "true";
+}
+function getTopLevelDirs(cwd) {
+    try {
+        const names = readdirSync(cwd, { withFileTypes: true })
+            .filter((d) => d.isDirectory() && !SKIP_DIRS.has(d.name))
+            .map((d) => d.name)
+            .sort();
+        return names;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get recent commits as a single block for repo context. Capped at MAX_RECENT_COMMITS_CHARS.
+ */
+function getRecentCommitsContext(projectRoot) {
+    const out = runGit(projectRoot, ["log", "--oneline", "-n", "10"]);
+    if (!out)
+        return undefined;
+    const block = "## recent commits\n" + out;
+    if (block.length > MAX_RECENT_COMMITS_CHARS) {
+        return block.slice(0, MAX_RECENT_COMMITS_CHARS) + "\n...(truncated)";
+    }
+    return block;
+}
+/**
+ * Get list of goal-related file paths via ripgrep (same as getRipgrepContext but returns array). Up to MAX_GOAL_FILES_LOG_FILES.
+ */
+function getRipgrepFileList(projectRoot, goal) {
+    const pattern = goal.trim().slice(0, 100);
+    if (!pattern)
+        return [];
+    const globExcludes = [
+        "!.git/**",
+        "!node_modules/**",
+        "!.cursor/**",
+        "!dist/**",
+        "!build/**",
+        "!__pycache__/**",
+        "!.venv/**",
+        "!venv/**",
+    ];
+    const args = [
+        "-F",
+        "-l",
+        "--max-count",
+        "1",
+        "-g",
+        ...globExcludes,
+        "--max-filesize",
+        "100k",
+        "--",
+        pattern,
+    ];
+    try {
+        const result = spawnSync("rg", args, {
+            cwd: projectRoot,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 10000,
+        });
+        if (result.status !== 0 && result.status !== null)
+            return [];
+        return (result.stdout ?? "")
+            .trim()
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .slice(0, MAX_GOAL_FILES_LOG_FILES);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * For goal-related files (from ripgrep), get git log --oneline -n 2 per file. Capped at MAX_GOAL_FILES_LOG_CHARS.
+ */
+function getGoalRelatedFilesLogContext(projectRoot, goal) {
+    const files = getRipgrepFileList(projectRoot, goal);
+    if (files.length === 0)
+        return undefined;
+    const lines = [];
+    for (const file of files) {
+        const log = runGit(projectRoot, ["log", "--oneline", "-n", "2", "--", file]);
+        if (log) {
+            lines.push(file + ":");
+            lines.push(log.split(/\r?\n/).map((l) => "  " + l).join("\n"));
+        }
+    }
+    if (lines.length === 0)
+        return undefined;
+    let block = "## recent changes (goal-related files)\n" + lines.join("\n");
+    if (block.length > MAX_GOAL_FILES_LOG_CHARS) {
+        block = block.slice(0, MAX_GOAL_FILES_LOG_CHARS) + "\n...(truncated)";
+    }
+    return block;
+}
+/**
+ * Run ripgrep and return matching file paths (one per line), capped in count and length.
+ * Returns undefined if rg is not available or fails. Uses fixed-string search (-F) for safety.
+ */
+function getRipgrepContext(projectRoot, goal) {
+    const pattern = goal.trim().slice(0, 100);
+    if (!pattern)
+        return undefined;
+    const globExcludes = [
+        "!.git/**",
+        "!node_modules/**",
+        "!.cursor/**",
+        "!dist/**",
+        "!build/**",
+        "!__pycache__/**",
+        "!.venv/**",
+        "!venv/**",
+    ];
+    const args = [
+        "-F",
+        "-l",
+        "--max-count",
+        "1",
+        "-g",
+        ...globExcludes,
+        "--max-filesize",
+        "100k",
+        "--",
+        pattern,
+    ];
+    try {
+        const result = spawnSync("rg", args, {
+            cwd: projectRoot,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 10000,
+        });
+        if (result.status !== 0 && result.status !== null)
+            return undefined;
+        const lines = (result.stdout ?? "")
+            .trim()
+            .split(/\r?\n/)
+            .filter((line) => line.trim().length > 0)
+            .slice(0, MAX_RIPGREP_FILES);
+        if (lines.length === 0)
+            return undefined;
+        let out = "## ripgrep (goal-related)\n" + lines.join("\n");
+        if (out.length > MAX_RIPGREP_CONTEXT_CHARS) {
+            out = out.slice(0, MAX_RIPGREP_CONTEXT_CHARS) + "\n...(truncated)";
+        }
+        return out;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build a short repository context string for the planner.
+ * If goal is provided and ripgrep is available, appends goal-related file list.
+ * Returns undefined if not a git repo (or on error); otherwise git status, diff --stat, top-level dirs, and optionally ripgrep results.
+ */
+export function getRepoContext(projectRoot, goal) {
+    if (!isGitRepo(projectRoot))
+        return undefined;
+    const parts = [];
+    const status = runGit(projectRoot, ["status", "--short"]);
+    if (status) {
+        parts.push("## git status --short\n" + status);
+    }
+    const diffStat = runGit(projectRoot, ["diff", "--stat"]);
+    if (diffStat) {
+        parts.push("## git diff --stat\n" + diffStat);
+    }
+    const cachedStat = runGit(projectRoot, ["diff", "--cached", "--stat"]);
+    if (cachedStat) {
+        parts.push("## git diff --cached --stat\n" + cachedStat);
+    }
+    const dirs = getTopLevelDirs(projectRoot);
+    if (dirs.length > 0) {
+        parts.push("## top-level directories\n" + dirs.join(", "));
+    }
+    const recentCommits = getRecentCommitsContext(projectRoot);
+    if (recentCommits) {
+        parts.push(recentCommits);
+    }
+    if (parts.length === 0 && !goal?.trim())
+        return undefined;
+    const maxBase = goal?.trim()
+        ? MAX_REPO_CONTEXT_WITH_RG_CHARS - MAX_RIPGREP_CONTEXT_CHARS - MAX_RECENT_COMMITS_CHARS - MAX_GOAL_FILES_LOG_CHARS - 50
+        : MAX_REPO_CONTEXT_CHARS - MAX_RECENT_COMMITS_CHARS;
+    let out = parts.length > 0 ? parts.join("\n\n") : "";
+    if (out.length > maxBase) {
+        out = out.slice(0, maxBase) + "\n...(truncated)";
+    }
+    if (goal?.trim()) {
+        const rgBlock = getRipgrepContext(projectRoot, goal);
+        if (rgBlock) {
+            out = out ? out + "\n\n" + rgBlock : rgBlock;
+        }
+        const goalFilesLog = getGoalRelatedFilesLogContext(projectRoot, goal);
+        if (goalFilesLog) {
+            out = out ? out + "\n\n" + goalFilesLog : goalFilesLog;
+        }
+        if (out.length > MAX_REPO_CONTEXT_WITH_RG_CHARS) {
+            out = out.slice(0, MAX_REPO_CONTEXT_WITH_RG_CHARS) + "\n...(truncated)";
+        }
+    }
+    else if (out.length > MAX_REPO_CONTEXT_CHARS) {
+        out = out.slice(0, MAX_REPO_CONTEXT_CHARS) + "\n...(truncated)";
+    }
+    return out || undefined;
+}

package/dist/utils/shell.js

@@ -0,0 +1,47 @@
+/**
+ * Shell / process utilities (run claude, codex, etc.)
+ */
+import { execSync, spawnSync } from "child_process";
+import { existsSync } from "fs";
+const isWindows = process.platform === "win32";
+export function runCommand(cmd, args, cwd) {
+    const full = [cmd, ...args].join(" ");
+    return execSync(full, { encoding: "utf-8", cwd }).trim();
+}
+/**
+ * Run a command with stdio inherited so output is visible in the terminal. Returns true if exit code is 0.
+ */
+export function runCommandLive(cmd, args, cwd) {
+    const result = spawnSync(cmd, args, { stdio: "inherit", cwd, shell: true });
+    return result.status === 0;
+}
+export function hasCommand(cmd) {
+    try {
+        const check = isWindows ? `where ${cmd}` : `which ${cmd}`;
+        execSync(check, { encoding: "utf-8", stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve full path to command executable (for spawning without shell so arguments are preserved).
+ * On Windows, prefers .cmd so we get the real npm global wrapper (e.g. codex.cmd) not the extensionless entry.
+ */
+export function resolveCommandPath(cmd) {
+    try {
+        const check = isWindows ? `where ${cmd}` : `which ${cmd}`;
+        const out = execSync(check, { encoding: "utf-8", stdio: "pipe" });
+        const lines = out.split(/[\r\n]+/).map((s) => s.trim()).filter(Boolean);
+        if (isWindows && lines.length > 0) {
+            const preferred = lines.find((p) => p.toLowerCase().endsWith(".cmd"));
+            const chosen = preferred ?? lines.find((p) => existsSync(p)) ?? lines[0];
+            return chosen || null;
+        }
+        return lines[0] || null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "planforge",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "PlanForge CLI - Bring your own AI to Cursor",
+  "keywords": ["cursor", "claude", "codex", "ai", "cli", "planning", "planforge"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/planforge/planforge.git"
+  },
+  "bugs": "https://github.com/planforge/planforge/issues",
+  "homepage": "https://github.com/planforge/planforge#readme",
+  "files": ["dist"],
+  "bin": {
+    "planforge": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "planforge": "node dist/index.js",
+    "install:global": "pnpm run build && npm install -g .",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@daun_jung/korean-romanizer": "^1.0.1",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}