@straussenl/opencode-craft 1.0.0

package/index.ts

@@ -0,0 +1,422 @@
+import { type Plugin, tool } from "@opencode-ai/plugin"
+import {
+  readActivePlan,
+  writeActivePlan,
+  clearActivePlan,
+  readPlan,
+  writePlan,
+  listPlans,
+  generatePlanId,
+  getActivePlan,
+  requireNoActivePlan,
+} from "./storage"
+import { isValidTransition, isActiveStatus } from "./state"
+import type { PlanMeta, PlanStatus, TaskStatus } from "./types"
+
+const craftPlugin: Plugin = async (_ctx) => {
+  return {
+    config: (cfg: Record<string, unknown>) => {
+      const agents = (cfg.agent ?? {}) as Record<string, unknown>
+      cfg.agent = agents
+
+      agents.craft = {
+        description:
+          "Craft Planner — create structured, executable plans for your work. Use when you want to design a plan before starting implementation.",
+        mode: "primary",
+        color: "#EF4444",
+        permission: { edit: "deny", bash: "deny" },
+        prompt: `You are a **Craft Planner** in read-only mode — you cannot edit project files or run shell commands. Your tools are for creating and managing craft plan files only.
+
+## Your Workflow
+
+1. **Understand the request** — When the user describes what they want, first ask clarifying questions to understand the scope. Then summarize what the plan would cover and ask **"Shall I create this plan?"** Only call \`craft_create_plan\` after the user explicitly says yes. The plan starts in "forming" status.
+
+2. **Ask clarifying questions** — Before finalizing, ask questions to understand scope, constraints, and priorities. The plan should be thorough enough for another agent to execute.
+
+3. **Write the plan content** — Use \`craft_update_plan\` to write the plan body in Markdown:
+   - **Goal**: What the user wants to achieve
+   - **Context**: Relevant background, constraints, existing code
+   - **Approach**: High-level strategy and technical decisions
+   - **Steps**: Ordered implementation steps
+
+4. **Add tasks** — Use \`craft_add_task\` to break the plan into concrete, actionable tasks. Each task should be independently verifiable. Add acceptance criteria inline when helpful.
+
+5. **Iterate** — The user may request changes. Use \`craft_update_plan\`, \`craft_add_task\`, and \`craft_list_tasks\` to refine until the user is satisfied.
+
+6. **Confirm and finalize** — When the plan is thorough and the user confirms, call \`craft_set_status("formed")\`. Then remind the user they can switch to Build mode to execute.
+
+7. **Cancel a plan** — If the user wants to abandon the plan at any stage (forming or formed), call \`craft_set_status("cancelled")\`. This frees up the active slot so a new plan can be created immediately.
+
+## Guidelines
+
+- Always check for an existing active plan with \`craft_get_active_plan\` before creating a new one.
+- If the user seems uncertain or changes their mind, proactively remind them they can cancel the plan.
+- Tasks should be ordered by dependency — a task should not depend on a later task.
+- Keep task scope reasonable — each task should represent 1-5 minutes of focused work.
+- When the user says "looks good", "approved", "go ahead" etc., confirm explicitly then call \`craft_set_status("formed")\`.
+- Never set status to "completed" yourself — that is the Build agent's responsibility after execution.`,
+      }
+    },
+
+    "experimental.chat.system.transform": async (
+      _input: unknown,
+      output: { system?: string }
+    ) => {
+      const active = readActivePlan()
+      if (!active || !isActiveStatus(active.status)) return
+
+      const plan = readPlan(active.planId)
+      const taskSummary =
+        plan && plan.meta.tasks.length > 0
+          ? plan.meta.tasks
+              .map(
+                (t) =>
+                  `  ${t.status === "completed" ? "[x]" : "[ ]"} ${t.title}`
+              )
+              .join("\n")
+          : "  (暂无任务)"
+
+      const block = [
+        "",
+        "---",
+        "## Active Craft Plan",
+        "",
+        `A craft plan is **${active.status}** and ready:`,
+        "",
+        `- **Plan ID**: \`${active.planId}\``,
+        `- **Name**: ${plan?.meta.name ?? active.planId}`,
+        "",
+        "**Tasks**:",
+        taskSummary,
+        "",
+        `Use \`craft_get_active_plan\` to read the full plan. Use \`craft_update_task\` to mark tasks complete as you work. When all tasks are done, call \`craft_set_status("completed")\`.`,
+      ].join("\n")
+
+      output.system = (output.system ?? "") + block
+    },
+
+    tool: {
+      craft_create_plan: tool({
+        description:
+          "Create a new craft plan. Only one active plan can exist at a time. Returns an error if another plan is already forming or formed.",
+        args: {
+          name: tool.schema
+            .string()
+            .describe(
+              "A short descriptive name for the plan, e.g. 'add-dark-mode'. Used to generate the plan ID."
+            ),
+          content: tool.schema
+            .string()
+            .optional()
+            .describe("Optional initial plan content in Markdown."),
+        },
+        async execute(args: { name: string; content?: string }) {
+          const err = requireNoActivePlan()
+          if (err) return err
+
+          const planId = generatePlanId(args.name)
+          const now = new Date().toISOString()
+          const meta: PlanMeta = {
+            name: args.name,
+            status: "forming",
+            created: now,
+            updated: now,
+            tasks: [],
+          }
+
+          writePlan(
+            planId,
+            meta,
+            args.content ??
+              `# Plan: ${args.name}\n\n## 目标\n\n待补充...\n\n## 实现步骤\n\n待补充...\n`
+          )
+          writeActivePlan({ planId, status: "forming" })
+
+          return [
+            `计划已创建:`,
+            `- **ID**: \`${planId}\``,
+            `- **名称**: ${args.name}`,
+            `- **状态**: forming`,
+            ``,
+            `现在可以完善计划内容了。使用 \`craft_update_plan\` 编写计划正文，使用 \`craft_add_task\` 添加任务项。`,
+          ].join("\n")
+        },
+      }),
+
+      craft_get_active_plan: tool({
+        description:
+          "Get the currently active craft plan. Returns null if no active plan exists.",
+        args: {},
+        async execute() {
+          const active = readActivePlan()
+          if (!active) return "当前没有活跃的计划。"
+          const plan = readPlan(active.planId)
+          if (!plan) {
+            clearActivePlan()
+            return "活跃计划文件丢失，已自动清除活跃状态。请重新创建计划。"
+          }
+          const tasks =
+            plan.meta.tasks.length > 0
+              ? plan.meta.tasks
+                  .map(
+                    (t) =>
+                      `  - [${t.id}] **${t.title}** (${t.status})`
+                  )
+                  .join("\n")
+              : "  (暂无任务)"
+          return [
+            `# Plan: ${plan.meta.name}`,
+            `- **ID**: \`${plan.planId}\``,
+            `- **状态**: ${plan.meta.status}`,
+            `- **创建**: ${plan.meta.created}`,
+            `- **更新**: ${plan.meta.updated}`,
+            ``,
+            `## 任务`,
+            tasks,
+            ``,
+            `## 内容`,
+            plan.content || "(空)",
+          ].join("\n")
+        },
+      }),
+
+      craft_update_plan: tool({
+        description:
+          "Update the active plan's content or name. The plan must be in 'forming' status.",
+        args: {
+          content: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Updated plan content in Markdown. If omitted, content is unchanged."
+            ),
+          name: tool.schema
+            .string()
+            .optional()
+            .describe("Updated plan name. If omitted, name is unchanged."),
+        },
+        async execute(args: { content?: string; name?: string }) {
+          const plan = getActivePlan()
+          if (!plan) return "没有活跃的计划。请先用 craft_create_plan 创建一个。"
+          if (plan.meta.status !== "forming") {
+            return `计划状态为 "${plan.meta.status}"，无法修改。只有 "forming" 状态的计划可以修改。`
+          }
+
+          const updatedMeta = { ...plan.meta, updated: new Date().toISOString() }
+          if (args.name) updatedMeta.name = args.name
+
+          writePlan(
+            plan.planId,
+            updatedMeta,
+            args.content !== undefined ? args.content : plan.content
+          )
+
+          const changed: string[] = []
+          if (args.content !== undefined) changed.push("内容")
+          if (args.name) changed.push("名称")
+          return `计划已更新 (${changed.join(", ")}).`
+        },
+      }),
+
+      craft_set_status: tool({
+        description:
+          "Set the plan status. Valid transitions: forming→formed, forming→cancelled, formed→completed, formed→cancelled.",
+        args: {
+          status: tool.schema
+            .string()
+            .describe(
+              "Target status: 'formed' (plan ready for execution), 'completed' (all tasks done), or 'cancelled' (abandon plan)."
+            ),
+        },
+        async execute(args: { status: string }) {
+          const to = args.status as PlanStatus
+          if (!["formed", "completed", "cancelled"].includes(to)) {
+            return `无效的状态: "${to}"。可选值: formed, completed, cancelled。`
+          }
+
+          const plan = getActivePlan()
+          if (!plan) return "没有活跃的计划。"
+
+          if (!isValidTransition(plan.meta.status, to)) {
+            return `无法从 "${plan.meta.status}" 转换到 "${to}"。允许的转换: forming→formed/cancelled, formed→completed/cancelled。`
+          }
+
+          const updatedMeta = { ...plan.meta, status: to, updated: new Date().toISOString() }
+          writePlan(plan.planId, updatedMeta, plan.content)
+
+          if (to === "completed" || to === "cancelled") {
+            clearActivePlan()
+          } else {
+            writeActivePlan({ planId: plan.planId, status: to })
+          }
+
+          const messages: Record<PlanStatus, string> = {
+            formed:
+              "计划已标记为 **formed** (已成型)。你可以切换到 Build 模式开始执行了。",
+            completed:
+              "计划已标记为 **completed** (已完成)。所有任务已完成，计划已归档。",
+            cancelled:
+              "计划已 **取消**。现在可以创建新计划了。",
+          }
+          return messages[to]
+        },
+      }),
+
+      craft_add_task: tool({
+        description:
+          "Add a task to the active plan. The plan must be in 'forming' status.",
+        args: {
+          title: tool.schema
+            .string()
+            .describe(
+              "Task description. Should be a concrete, actionable item."
+            ),
+        },
+        async execute(args: { title: string }) {
+          const plan = getActivePlan()
+          if (!plan) return "没有活跃的计划。"
+          if (plan.meta.status !== "forming") {
+            return `计划状态为 "${plan.meta.status}"，无法添加任务。`
+          }
+
+          const nextId = String(plan.meta.tasks.length + 1)
+          const newTask = { id: nextId, title: args.title, status: "pending" as TaskStatus }
+          const updatedMeta = {
+            ...plan.meta,
+            tasks: [...plan.meta.tasks, newTask],
+            updated: new Date().toISOString(),
+          }
+
+          writePlan(plan.planId, updatedMeta, plan.content)
+
+          return `任务已添加: [${nextId}] **${args.title}** (状态: pending)`
+        },
+      }),
+
+      craft_update_task: tool({
+        description:
+          "Update a task's status. Use this during Build mode to mark tasks as in_progress or completed as you work through the plan.",
+        args: {
+          taskId: tool.schema
+            .string()
+            .describe("The task ID (as shown in craft_list_tasks)."),
+          status: tool.schema
+            .string()
+            .describe(
+              "New status: 'pending', 'in_progress', or 'completed'."
+            ),
+        },
+        async execute(args: { taskId: string; status: string }) {
+          const to = args.status as TaskStatus
+          if (!["pending", "in_progress", "completed"].includes(to)) {
+            return `无效的任务状态: "${to}"。可选: pending, in_progress, completed。`
+          }
+
+          const plan = getActivePlan()
+          if (!plan) return "没有活跃的计划。"
+
+          const idx = plan.meta.tasks.findIndex((t) => t.id === args.taskId)
+          if (idx === -1) {
+            return `找不到任务 ID: ${args.taskId}。使用 craft_list_tasks 查看所有任务。`
+          }
+
+          const updatedTasks = plan.meta.tasks.map((t, i) =>
+            i === idx ? { ...t, status: to } : t
+          )
+          const updatedMeta = {
+            ...plan.meta,
+            tasks: updatedTasks,
+            updated: new Date().toISOString(),
+          }
+
+          writePlan(plan.planId, updatedMeta, plan.content)
+
+          const task = updatedTasks[idx]
+          const allDone = updatedTasks.every((t) => t.status === "completed")
+          const pending = updatedTasks.filter((t) => t.status !== "completed").length
+
+          let msg = `任务 [${args.taskId}] "${task.title}" 状态已更新为 **${to}**。`
+          if (allDone && plan.meta.status === "formed") {
+            msg += `\n\n所有 ${updatedTasks.length} 个任务已完成！请调用 craft_set_status("completed") 标记计划为已完成。`
+          } else {
+            msg += `\n剩余 ${pending}/${updatedTasks.length} 个任务待完成。`
+          }
+          return msg
+        },
+      }),
+
+      craft_list_tasks: tool({
+        description:
+          "List all tasks in the active craft plan with their statuses.",
+        args: {},
+        async execute() {
+          const plan = getActivePlan()
+          if (!plan) return "没有活跃的计划。"
+
+          if (plan.meta.tasks.length === 0) {
+            return "当前计划暂无任务。"
+          }
+
+          const lines = plan.meta.tasks.map((t) => {
+            const icon =
+              t.status === "completed"
+                ? "✅"
+                : t.status === "in_progress"
+                  ? "🔄"
+                  : "⬜"
+            return `  ${icon} [${t.id}] **${t.title}**`
+          })
+
+          const done = plan.meta.tasks.filter(
+            (t) => t.status === "completed"
+          ).length
+          return [
+            `## 任务清单 (${done}/${plan.meta.tasks.length} 完成)`,
+            ...lines,
+          ].join("\n")
+        },
+      }),
+
+      craft_list_plans: tool({
+        description:
+          "List all craft plans, optionally filtered by status. Includes both active and archived plans.",
+        args: {
+          status: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Filter by status: 'forming', 'formed', 'completed', 'cancelled'. Omit for all."
+            ),
+        },
+        async execute(args: { status?: string }) {
+          const status = args.status as PlanStatus | undefined
+          const plans = listPlans(status)
+
+          if (plans.length === 0) {
+            const filter = status ? `(状态: ${status}) ` : ""
+            return `没有${filter}计划。`
+          }
+
+          const lines = plans.map((p) => {
+            const taskDone = p.meta.tasks.filter(
+              (t) => t.status === "completed"
+            ).length
+            const taskTotal = p.meta.tasks.length
+            const taskInfo =
+              taskTotal > 0 ? ` | ${taskDone}/${taskTotal} 任务` : ""
+            return `  - \`${p.planId}\` — **${p.meta.name}** [${p.meta.status}]${taskInfo}`
+          })
+
+          const active = readActivePlan()
+          const activeNote = active
+            ? `\n> 当前活跃计划: \`${active.planId}\` (${active.status})\n`
+            : "\n> 当前没有活跃计划。使用 craft_create_plan 创建一个。\n"
+
+          return [activeNote, `## 所有计划`, ...lines].join("\n")
+        },
+      }),
+    },
+  }
+}
+
+export default craftPlugin

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@straussenl/opencode-craft",
+  "version": "1.0.0",
+  "description": "Craft Planner plugin for OpenCode — create structured, executable plans for your work",
+  "type": "module",
+  "exports": "./index.ts",
+  "files": [
+    "index.ts",
+    "state.ts",
+    "storage.ts",
+    "types.ts"
+  ],
+  "dependencies": {
+    "@opencode-ai/plugin": "latest",
+    "gray-matter": "^4.0.3"
+  },
+  "license": "MIT"
+}

package/state.ts

@@ -0,0 +1,10 @@
+import type { PlanStatus } from "./types"
+import { VALID_TRANSITIONS } from "./types"
+
+export function isValidTransition(from: PlanStatus, to: PlanStatus): boolean {
+  return VALID_TRANSITIONS[from].includes(to)
+}
+
+export function isActiveStatus(status: PlanStatus): boolean {
+  return status === "forming" || status === "formed"
+}

package/storage.ts

@@ -0,0 +1,129 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from "node:fs"
+import { join } from "node:path"
+import { homedir } from "node:os"
+import matter from "gray-matter"
+import type { Plan, PlanMeta, ActivePlan, PlanStatus } from "./types"
+import { isActiveStatus } from "./state"
+
+function getCraftDir(): string {
+  return join(homedir(), ".config", "opencode", "craft")
+}
+
+function getPlansDir(): string {
+  return join(getCraftDir(), "plans")
+}
+
+function getActiveFilePath(): string {
+  return join(getCraftDir(), "active.json")
+}
+
+function getPlanPath(planId: string): string {
+  return join(getPlansDir(), `${planId}.md`)
+}
+
+function ensureDir(path: string): void {
+  if (!existsSync(path)) {
+    mkdirSync(path, { recursive: true })
+  }
+}
+
+export function readActivePlan(): ActivePlan | null {
+  const activeFile = getActiveFilePath()
+  if (!existsSync(activeFile)) return null
+  try {
+    const raw = readFileSync(activeFile, "utf-8")
+    return JSON.parse(raw) as ActivePlan
+  } catch {
+    return null
+  }
+}
+
+export function writeActivePlan(active: ActivePlan): void {
+  ensureDir(getCraftDir())
+  writeFileSync(getActiveFilePath(), JSON.stringify(active, null, 2), "utf-8")
+}
+
+export function clearActivePlan(): void {
+  const f = getActiveFilePath()
+  if (existsSync(f)) unlinkSync(f)
+}
+
+export function readPlan(planId: string): Plan | null {
+  const filePath = getPlanPath(planId)
+  if (!existsSync(filePath)) return null
+  try {
+    const raw = readFileSync(filePath, "utf-8")
+    const { data, content } = matter(raw)
+    return {
+      planId,
+      meta: {
+        name: data.name ?? planId,
+        status: data.status ?? "forming",
+        created: data.created ?? new Date(0).toISOString(),
+        updated: data.updated ?? new Date(0).toISOString(),
+        tasks: Array.isArray(data.tasks) ? data.tasks : [],
+      },
+      content: content.trim(),
+      filePath,
+    }
+  } catch {
+    return null
+  }
+}
+
+export function writePlan(planId: string, meta: PlanMeta, content: string): void {
+  ensureDir(getPlansDir())
+  const filePath = getPlanPath(planId)
+  const text = matter.stringify(content.trim(), meta as unknown as Record<string, unknown>)
+  writeFileSync(filePath, text, "utf-8")
+}
+
+export function listPlans(status?: PlanStatus): Plan[] {
+  const dir = getPlansDir()
+  if (!existsSync(dir)) return []
+  try {
+    const files = readdirSync(dir).filter(f => f.endsWith(".md"))
+    const plans: Plan[] = []
+    for (const f of files) {
+      const planId = f.replace(/\.md$/, "")
+      const plan = readPlan(planId)
+      if (plan && (!status || plan.meta.status === status)) {
+        plans.push(plan)
+      }
+    }
+    return plans.sort((a, b) => b.meta.created.localeCompare(a.meta.created))
+  } catch {
+    return []
+  }
+}
+
+export function generatePlanId(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fff]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 50)
+  const date = new Date().toISOString().slice(0, 10).replace(/-/g, "")
+  const suffix = Array.from(crypto.getRandomValues(new Uint8Array(2)))
+    .map(b => b.toString(16).padStart(2, "0"))
+    .join("")
+  return `${slug}-${date}-${suffix}`
+}
+
+export function getActivePlan(): Plan | null {
+  const active = readActivePlan()
+  if (!active) return null
+  return readPlan(active.planId)
+}
+
+export function requireNoActivePlan(): string | null {
+  const active = readActivePlan()
+  if (active && isActiveStatus(active.status)) {
+    return `一个活跃计划已存在: **${active.planId}** (状态: ${active.status})。请先完成或取消它再创建新计划。`
+  }
+  return null
+}
+
+export function getCraftDirPath(): string {
+  return getCraftDir()
+}

package/types.ts

@@ -0,0 +1,36 @@
+export type PlanStatus = "forming" | "formed" | "completed" | "cancelled"
+
+export type TaskStatus = "pending" | "in_progress" | "completed"
+
+export interface Task {
+  id: string
+  title: string
+  status: TaskStatus
+}
+
+export interface PlanMeta {
+  name: string
+  status: PlanStatus
+  created: string
+  updated: string
+  tasks: Task[]
+}
+
+export interface ActivePlan {
+  planId: string
+  status: PlanStatus
+}
+
+export interface Plan {
+  planId: string
+  meta: PlanMeta
+  content: string
+  filePath: string
+}
+
+export const VALID_TRANSITIONS: Record<PlanStatus, PlanStatus[]> = {
+  forming: ["formed", "cancelled"],
+  formed: ["completed", "cancelled"],
+  completed: [],
+  cancelled: [],
+}