pi-openspec 1.0.0

package/src/index.ts

@@ -0,0 +1,778 @@
+/**
+ * Pi OpenSpec Extension
+ *
+ * Wraps the OpenSpec CLI into pi /openspec commands with:
+ *   - Auto-naming: NNNNN-<date>-<slug> for change directories
+ *   - Number shorthand: /openspec status 3 → resolves to full name
+ *   - Session-start detection of openspec projects
+ *   - Auto-refresh hooks on spec file edits
+ *
+ * Commands:
+ *   /openspec new <name>              — create a new change
+ *   /openspec status [id]             — show artifact status
+ *   /openspec next [id] [artifact]    — get instructions for next artifact
+ *   /openspec validate [id]           — validate a change
+ *   /openspec archive [id]            — archive a completed change
+ *   /openspec list                    — list all changes
+ *   /openspec list --specs            — list all specs
+ *   /openspec init                    — initialize openspec in project
+ *   /openspec schemas                 — list available schemas
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { execSync } from "node:child_process"
+import type {
+    ExtensionAPI,
+    ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent"
+import type { AutocompleteItem } from "@earendil-works/pi-tui"
+
+// ───────────────────────────────────────────────────────────────────
+// Types
+// ───────────────────────────────────────────────────────────────────
+
+interface ChangeEntry {
+    name: string
+    completedTasks: number
+    totalTasks: number
+    lastModified: string
+    status: string
+}
+
+interface ArtifactInfo {
+    id: string
+    outputPath: string
+    status: string
+    missingDeps?: string[]
+}
+
+interface StatusResult {
+    changeName: string
+    schemaName: string
+    isComplete: boolean
+    artifacts: ArtifactInfo[]
+    nextSteps: string[]
+}
+
+// ───────────────────────────────────────────────────────────────────
+// Constants
+// ───────────────────────────────────────────────────────────────────
+
+// Matches: NNNNN-YYYY-MM-DD-slug-name
+const NAMED_RE = /^(\d{5})-(\d{4}-\d{2}-\d{2})-(.+)$/
+
+const ARTIFACT_COLORS: Record<string, string> = {
+    done: "✅",
+    ready: "🔵",
+    blocked: "⏳",
+}
+
+// ───────────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────────
+
+function changesDir(cwd: string): string {
+    return path.join(cwd, "openspec", "changes")
+}
+
+function hasOpenSpec(cwd: string): boolean {
+    return fs.existsSync(path.join(cwd, "openspec"))
+}
+
+function today(): string {
+    return new Date().toISOString().slice(0, 10)
+}
+
+function toSlug(name: string): string {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9-]/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+}
+
+/**
+ * Scan existing change directories and return sorted list.
+ * Supports both our NNNNN-date-name format and plain openspec names.
+ */
+function scanChanges(cwd: string): string[] {
+    const dir = changesDir(cwd)
+    if (!fs.existsSync(dir)) return []
+    return fs
+        .readdirSync(dir)
+        .filter((entry) => {
+            const full = path.join(dir, entry)
+            return fs.statSync(full).isDirectory()
+        })
+        .sort()
+}
+
+/**
+ * Extract the numeric prefix from a NNNNN-date-name directory.
+ * Returns 0 for directories without our naming scheme.
+ */
+function extractNumber(dirname: string): number {
+    const m = NAMED_RE.exec(dirname)
+    return m ? parseInt(m[1], 10) : 0
+}
+
+/**
+ * Get the next sequential number across all changes.
+ */
+function nextNumber(cwd: string): number {
+    const changes = scanChanges(cwd)
+    if (changes.length === 0) return 1
+    const max = Math.max(...changes.map(extractNumber))
+    return max + 1
+}
+
+/**
+ * Resolve a user-provided identifier to a change directory name.
+ * Accepts:
+ *   - A number (e.g. "3") → finds change with that prefix
+ *   - A full name (e.g. "00003-2026-06-04-add-auth")
+ *   - A partial slug (e.g. "add-auth") → fuzzy match
+ */
+function resolveChange(cwd: string, id: string): string | null {
+    const changes = scanChanges(cwd)
+    if (changes.length === 0) return null
+
+    const trimmed = id.trim()
+
+    // Try numeric lookup
+    const num = parseInt(trimmed, 10)
+    if (!Number.isNaN(num) && String(num) === trimmed) {
+        const padded = String(num).padStart(5, "0")
+        const match = changes.find((c) => c.startsWith(padded + "-"))
+        if (match) return match
+    }
+
+    // Exact match
+    if (changes.includes(trimmed)) return trimmed
+
+    // Suffix/substring match
+    const lower = trimmed.toLowerCase()
+    const suffixMatch = changes.find((c) =>
+        c.toLowerCase().endsWith("-" + lower),
+    )
+    if (suffixMatch) return suffixMatch
+
+    const substringMatch = changes.find((c) => c.toLowerCase().includes(lower))
+    if (substringMatch) return substringMatch
+
+    return null
+}
+
+/**
+ * Run an openspec CLI command and return stdout.
+ * Throws on non-zero exit.
+ */
+function run(cwd: string, args: string, opts?: { json?: boolean }): string {
+    const jsonFlag = opts?.json ? " --json" : ""
+    const cmd = `openspec ${args}${jsonFlag}`
+    try {
+        return execSync(cmd, {
+            cwd,
+            encoding: "utf8",
+            timeout: 30_000,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim()
+    } catch (err: unknown) {
+        const e = err as { stderr?: string; message?: string }
+        throw new Error(
+            e.stderr?.trim() || e.message || "openspec command failed",
+            { cause: err },
+        )
+    }
+}
+
+/**
+ * Run openspec and parse JSON output.
+ */
+function runJSON<T>(cwd: string, args: string): T {
+    const raw = run(cwd, args, { json: true })
+    return JSON.parse(raw) as T
+}
+
+/**
+ * Find the most recent or only active change.
+ * Returns null if zero or multiple changes exist.
+ */
+function inferActiveChange(cwd: string): string | null {
+    const changes = scanChanges(cwd)
+    if (changes.length === 1) return changes[0]
+    if (changes.length === 0) return null
+
+    // Multiple changes — pick most recently modified
+    const dir = changesDir(cwd)
+    let latest = ""
+    let latestTime = 0
+    for (const name of changes) {
+        const stat = fs.statSync(path.join(dir, name))
+        if (stat.mtimeMs > latestTime) {
+            latestTime = stat.mtimeMs
+            latest = name
+        }
+    }
+    return latest || null
+}
+
+// ───────────────────────────────────────────────────────────────────
+// Formatting helpers
+// ───────────────────────────────────────────────────────────────────
+
+function formatStatus(status: StatusResult): string {
+    const lines: string[] = []
+    const icon = status.isComplete ? "✅" : "🔄"
+    lines.push(`${icon} **${status.changeName}** (${status.schemaName})`)
+    lines.push("")
+
+    // Artifact table
+    lines.push("| Artifact | Status | Dependencies |")
+    lines.push("|----------|--------|--------------|")
+    for (const a of status.artifacts) {
+        const statusIcon = ARTIFACT_COLORS[a.status] ?? a.status
+        const deps = a.missingDeps?.join(", ") ?? "—"
+        lines.push(`| ${a.id} | ${statusIcon} ${a.status} | ${deps} |`)
+    }
+
+    if (status.nextSteps.length > 0) {
+        lines.push("")
+        lines.push("**Next steps:**")
+        for (const step of status.nextSteps) {
+            lines.push(`- ${step}`)
+        }
+    }
+
+    return lines.join("\n")
+}
+
+function formatChangeList(changes: ChangeEntry[], _cwd: string): string {
+    if (changes.length === 0) {
+        return "No active changes. Create one with `/openspec new <name>`"
+    }
+
+    const lines: string[] = []
+    lines.push("| # | Change | Tasks | Status | Modified |")
+    lines.push("|---|--------|-------|--------|----------|")
+
+    for (const c of changes) {
+        const m = NAMED_RE.exec(c.name)
+        const num = m ? m[1] : "—"
+        const tasks =
+            c.totalTasks > 0 ? `${c.completedTasks}/${c.totalTasks}` : "—"
+        const date = c.lastModified.slice(0, 10)
+        lines.push(`| ${num} | ${c.name} | ${tasks} | ${c.status} | ${date} |`)
+    }
+
+    return lines.join("\n")
+}
+
+// ───────────────────────────────────────────────────────────────────
+// Subcommand handlers
+// ───────────────────────────────────────────────────────────────────
+
+async function handleNew(
+    name: string,
+    ctx: ExtensionCommandContext,
+    pi: ExtensionAPI,
+): Promise<void> {
+    if (!hasOpenSpec(ctx.cwd)) {
+        ctx.ui.notify(
+            "No openspec/ directory found. Run `/openspec init` first.",
+            "error",
+        )
+        return
+    }
+
+    const cleaned = name.replace(/^["']|["']$/g, "").trim()
+    if (!cleaned) {
+        // No name — ask the agent to infer one
+        const num = nextNumber(ctx.cwd)
+        const padded = String(num).padStart(5, "0")
+        pi.sendUserMessage(
+            `The user ran \`/openspec new\` with no name. ` +
+                `Infer a concise change name from the current conversation ` +
+                `context.\n\n` +
+                `Then run: \`/openspec new <inferred-name>\`\n\n` +
+                `Next number: **${padded}**, today: ${today()}`,
+        )
+        return
+    }
+
+    const slug = toSlug(cleaned)
+    if (!slug) {
+        ctx.ui.notify(
+            "Name produced an empty slug — use letters and numbers.",
+            "error",
+        )
+        return
+    }
+
+    const num = nextNumber(ctx.cwd)
+    const padded = String(num).padStart(5, "0")
+    const fullName = `${padded}-${today()}-${slug}`
+
+    try {
+        run(ctx.cwd, `new change "${fullName}"`)
+        ctx.ui.notify(`✅ Created change: ${fullName}`, "info")
+
+        // Feed the agent instructions for the first artifact
+        pi.sendUserMessage(
+            `New OpenSpec change **${fullName}** created.\n\n` +
+                `The spec-driven workflow is: ` +
+                `proposal → specs → design → tasks.\n\n` +
+                `The first artifact to write is **proposal**. ` +
+                `Run \`/openspec next ${num} proposal\` to get ` +
+                `enriched instructions, or start writing ` +
+                `\`openspec/changes/${fullName}/proposal.md\` ` +
+                `directly.`,
+        )
+    } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err)
+        ctx.ui.notify(`❌ Failed to create change: ${msg}`, "error")
+    }
+}
+
+async function handleStatus(
+    arg: string,
+    ctx: ExtensionCommandContext,
+): Promise<void> {
+    if (!hasOpenSpec(ctx.cwd)) {
+        ctx.ui.notify(
+            "No openspec/ directory found. Run `/openspec init` first.",
+            "error",
+        )
+        return
+    }
+
+    const trimmed = arg.trim()
+    const changeName = trimmed
+        ? resolveChange(ctx.cwd, trimmed)
+        : inferActiveChange(ctx.cwd)
+
+    if (!changeName) {
+        if (trimmed) {
+            ctx.ui.notify(
+                `Change "${trimmed}" not found. ` +
+                    `Run \`/openspec list\` to see available changes.`,
+                "error",
+            )
+        } else {
+            ctx.ui.notify(
+                "No active changes found. " +
+                    "Create one with `/openspec new <name>`.",
+                "info",
+            )
+        }
+        return
+    }
+
+    try {
+        const result = runJSON<StatusResult>(
+            ctx.cwd,
+            `status --change "${changeName}"`,
+        )
+        ctx.ui.notify(formatStatus(result), "info")
+    } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err)
+        ctx.ui.notify(`❌ Status failed: ${msg}`, "error")
+    }
+}
+
+async function handleNext(
+    arg: string,
+    ctx: ExtensionCommandContext,
+    pi: ExtensionAPI,
+): Promise<void> {
+    if (!hasOpenSpec(ctx.cwd)) {
+        ctx.ui.notify(
+            "No openspec/ directory found. Run `/openspec init` first.",
+            "error",
+        )
+        return
+    }
+
+    const parts = arg.trim().split(/\s+/)
+    const idPart = parts[0] ?? ""
+    const artifactPart = parts[1] ?? ""
+
+    // Resolve the change
+    const changeName = idPart
+        ? resolveChange(ctx.cwd, idPart)
+        : inferActiveChange(ctx.cwd)
+
+    if (!changeName) {
+        if (idPart) {
+            ctx.ui.notify(`Change "${idPart}" not found.`, "error")
+        } else {
+            ctx.ui.notify(
+                "No active changes. Create one with `/openspec new <name>`.",
+                "info",
+            )
+        }
+        return
+    }
+
+    // If no artifact specified, find the next ready one
+    let artifact = artifactPart
+    if (!artifact) {
+        try {
+            const status = runJSON<StatusResult>(
+                ctx.cwd,
+                `status --change "${changeName}"`,
+            )
+            const ready = status.artifacts.find((a) => a.status === "ready")
+            if (ready) {
+                artifact = ready.id
+            } else if (status.isComplete) {
+                ctx.ui.notify(
+                    `✅ All artifacts for **${changeName}** are complete. ` +
+                        `Run \`/openspec archive ${changeName}\` ` +
+                        `when ready.`,
+                    "info",
+                )
+                return
+            } else {
+                ctx.ui.notify(
+                    `No ready artifacts for **${changeName}**. ` +
+                        `Check status with \`/openspec status\`.`,
+                    "warning",
+                )
+                return
+            }
+        } catch {
+            ctx.ui.notify(
+                "Could not determine next artifact. " +
+                    "Specify one: proposal, specs, design, tasks",
+                "warning",
+            )
+            return
+        }
+    }
+
+    try {
+        const result = runJSON<{
+            instruction: string
+            template: string
+            resolvedOutputPath: string
+            description: string
+            unlocks: string[]
+        }>(ctx.cwd, `instructions ${artifact} --change "${changeName}"`)
+
+        const relPath = path.relative(ctx.cwd, result.resolvedOutputPath)
+
+        pi.sendUserMessage(
+            `## OpenSpec: Write **${artifact}** for ${changeName}\n\n` +
+                `**Output:** \`${relPath}\`\n\n` +
+                `**Description:** ${result.description}\n\n` +
+                `**Unlocks:** ${result.unlocks.join(", ") || "nothing"}\n\n` +
+                `---\n\n` +
+                `### Instructions\n\n${result.instruction}\n\n` +
+                `---\n\n` +
+                `### Template\n\n\`\`\`markdown\n${result.template}\`\`\`\n\n` +
+                `Write the artifact at \`${relPath}\` following ` +
+                `the instructions above. When done, run ` +
+                `\`/openspec status\` to check progress.`,
+        )
+    } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err)
+        ctx.ui.notify(`❌ Failed to get instructions: ${msg}`, "error")
+    }
+}
+
+async function handleValidate(
+    arg: string,
+    ctx: ExtensionCommandContext,
+): Promise<void> {
+    if (!hasOpenSpec(ctx.cwd)) {
+        ctx.ui.notify("No openspec/ directory found.", "error")
+        return
+    }
+
+    const trimmed = arg.trim()
+
+    try {
+        let output: string
+        if (trimmed) {
+            const changeName = resolveChange(ctx.cwd, trimmed)
+            if (!changeName) {
+                ctx.ui.notify(`Change "${trimmed}" not found.`, "error")
+                return
+            }
+            output = run(ctx.cwd, `validate "${changeName}" --type change`)
+        } else {
+            output = run(ctx.cwd, "validate --all")
+        }
+        ctx.ui.notify(output || "✅ Validation passed.", "info")
+    } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err)
+        ctx.ui.notify(`❌ Validation failed:\n${msg}`, "error")
+    }
+}
+
+async function handleArchive(
+    arg: string,
+    ctx: ExtensionCommandContext,
+    pi: ExtensionAPI,
+): Promise<void> {
+    if (!hasOpenSpec(ctx.cwd)) {
+        ctx.ui.notify("No openspec/ directory found.", "error")
+        return
+    }
+
+    const parts = arg.trim().split(/\s+/)
+    const idPart = parts[0] ?? ""
+    const confirmed = parts.includes("--yes")
+
+    if (!idPart) {
+        ctx.ui.notify("Usage: /openspec archive <id> [--yes]", "warning")
+        return
+    }
+
+    const changeName = resolveChange(ctx.cwd, idPart)
+    if (!changeName) {
+        ctx.ui.notify(`Change "${idPart}" not found.`, "error")
+        return
+    }
+
+    if (!confirmed) {
+        // Gate: validate first, then ask agent to confirm
+        pi.sendUserMessage(
+            `Archiving change **${changeName}**.\n\n` +
+                `Before archiving, please:\n` +
+                `1. Run \`/openspec validate ${idPart}\` ` +
+                `to check the change is valid\n` +
+                `2. Verify all tasks are complete with ` +
+                `\`/openspec status ${idPart}\`\n` +
+                `3. Run any project quality gates ` +
+                `(build, test, lint)\n\n` +
+                `If everything passes, run ` +
+                `\`/openspec archive ${idPart} --yes\` ` +
+                `to finalize.`,
+        )
+        return
+    }
+
+    try {
+        const output = run(ctx.cwd, `archive "${changeName}" --yes`)
+        ctx.ui.notify(`✅ Archived: ${changeName}\n${output}`, "info")
+    } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err)
+        ctx.ui.notify(`❌ Archive failed: ${msg}`, "error")
+    }
+}
+
+async function handleList(
+    arg: string,
+    ctx: ExtensionCommandContext,
+): Promise<void> {
+    if (!hasOpenSpec(ctx.cwd)) {
+        ctx.ui.notify(
+            "No openspec/ directory found. Run `/openspec init` first.",
+            "error",
+        )
+        return
+    }
+
+    const isSpecs = arg.trim() === "--specs"
+
+    try {
+        if (isSpecs) {
+            const output = run(ctx.cwd, "list --specs")
+            ctx.ui.notify(output || "No specs found.", "info")
+        } else {
+            const result = runJSON<{ changes: ChangeEntry[] }>(ctx.cwd, "list")
+            ctx.ui.notify(formatChangeList(result.changes, ctx.cwd), "info")
+        }
+    } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err)
+        ctx.ui.notify(`❌ List failed: ${msg}`, "error")
+    }
+}
+
+async function handleInit(ctx: ExtensionCommandContext): Promise<void> {
+    if (hasOpenSpec(ctx.cwd)) {
+        ctx.ui.notify(
+            "OpenSpec is already initialized in this project.",
+            "info",
+        )
+        return
+    }
+
+    try {
+        const output = run(ctx.cwd, "init --tools pi")
+        ctx.ui.notify(`✅ OpenSpec initialized.\n${output}`, "info")
+    } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err)
+        ctx.ui.notify(`❌ Init failed: ${msg}`, "error")
+    }
+}
+
+async function handleSchemas(ctx: ExtensionCommandContext): Promise<void> {
+    try {
+        const output = run(ctx.cwd, "schemas")
+        ctx.ui.notify(output || "No schemas found.", "info")
+    } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err)
+        ctx.ui.notify(`❌ ${msg}`, "error")
+    }
+}
+
+function showHelp(ctx: ExtensionCommandContext): void {
+    ctx.ui.notify(
+        [
+            "OpenSpec commands:",
+            "",
+            "  /openspec new <name>           — create a new change",
+            "  /openspec status [id]          — artifact status",
+            "  /openspec next [id] [artifact] — instructions for next artifact",
+            "  /openspec validate [id]        — validate a change",
+            "  /openspec archive <id> [--yes] — archive completed change",
+            "  /openspec list                 — list active changes",
+            "  /openspec list --specs         — list specs",
+            "  /openspec init                 — initialize openspec",
+            "  /openspec schemas              — list workflow schemas",
+            "",
+            "Identifiers: use number (3), full name, or slug (add-auth).",
+        ].join("\n"),
+        "info",
+    )
+}
+
+// ───────────────────────────────────────────────────────────────────
+// Extension entry point
+// ───────────────────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+    // ─── /openspec command ───────────────────────────────────────
+    pi.registerCommand("openspec", {
+        description:
+            "OpenSpec — new | status | next | validate | " +
+            "archive | list | init | schemas",
+
+        getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
+            const subs = [
+                "new ",
+                "status ",
+                "next ",
+                "validate ",
+                "archive ",
+                "list",
+                "list --specs",
+                "init",
+                "schemas",
+            ]
+            const items = subs
+                .filter((s) => s.startsWith(prefix))
+                .map((s) => ({
+                    value: s,
+                    label: s.trim(),
+                }))
+            return items.length > 0 ? items : null
+        },
+
+        handler: async (args, ctx) => {
+            const parts = (args ?? "").trim().split(/\s+/)
+            const sub = parts[0]?.toLowerCase() ?? ""
+            const rest = parts.slice(1).join(" ")
+
+            switch (sub) {
+                case "new":
+                    return handleNew(rest, ctx, pi)
+                case "status":
+                    return handleStatus(rest, ctx)
+                case "next":
+                    return handleNext(rest, ctx, pi)
+                case "validate":
+                    return handleValidate(rest, ctx)
+                case "archive":
+                    return handleArchive(rest, ctx, pi)
+                case "list":
+                    return handleList(rest, ctx)
+                case "init":
+                    return handleInit(ctx)
+                case "schemas":
+                    return handleSchemas(ctx)
+                default:
+                    showHelp(ctx)
+            }
+        },
+    })
+
+    // ─── Session start: detect openspec projects ─────────────────
+    pi.on("session_start", async (_event, ctx) => {
+        if (!hasOpenSpec(ctx.cwd)) return
+
+        try {
+            const result = runJSON<{ changes: ChangeEntry[] }>(ctx.cwd, "list")
+            const count = result.changes.length
+            if (count > 0) {
+                ctx.ui.notify(
+                    `📋 OpenSpec: ${count} active change(s). ` +
+                        `Use \`/openspec list\` to view.`,
+                    "info",
+                )
+            }
+        } catch {
+            // CLI not available or not an openspec project — skip
+        }
+    })
+
+    // ─── Auto-refresh: notify on spec file edits ─────────────────
+    pi.on("tool_result", async (event, ctx) => {
+        if (event.toolName !== "write" && event.toolName !== "edit") {
+            return
+        }
+
+        const filePath = (event.input as { path: string }).path ?? ""
+        if (!filePath.includes("openspec/changes/")) return
+
+        // Resolve to absolute path
+        const abs = path.isAbsolute(filePath)
+            ? filePath
+            : path.join(ctx.cwd, filePath)
+
+        // Extract change name from path
+        const changesRoot = changesDir(ctx.cwd)
+        const rel = path.relative(changesRoot, abs)
+        const changeName = rel.split(path.sep)[0]
+        if (!changeName) return
+
+        try {
+            const result = runJSON<StatusResult>(
+                ctx.cwd,
+                `status --change "${changeName}"`,
+            )
+
+            const done = result.artifacts.filter(
+                (a) => a.status === "done",
+            ).length
+            const total = result.artifacts.length
+
+            if (result.isComplete) {
+                ctx.ui.notify(
+                    `✅ All artifacts complete for ` +
+                        `**${changeName}**! ` +
+                        `Run \`/openspec archive\` when ready.`,
+                    "info",
+                )
+            } else {
+                const ready = result.artifacts.find((a) => a.status === "ready")
+                if (ready) {
+                    ctx.ui.notify(
+                        `📋 ${changeName}: ${done}/${total} ` +
+                            `artifacts done. ` +
+                            `Next: **${ready.id}**`,
+                        "info",
+                    )
+                }
+            }
+        } catch {
+            // Status check failed — skip silently
+        }
+    })
+}