@duypham93/openkit 0.2.0

package/.opencode/lib/runtime-paths.js

@@ -0,0 +1,95 @@
+const crypto = require("crypto")
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+
+function getOpenCodeHome(env = process.env) {
+  if (env.OPENCODE_HOME) {
+    return path.resolve(env.OPENCODE_HOME)
+  }
+
+  if (process.platform === "win32") {
+    const base = env.APPDATA || path.join(os.homedir(), "AppData", "Roaming")
+    return path.join(base, "opencode")
+  }
+
+  const base = env.XDG_CONFIG_HOME ? path.resolve(env.XDG_CONFIG_HOME) : path.join(os.homedir(), ".config")
+  return path.join(base, "opencode")
+}
+
+function detectProjectRoot(startDir) {
+  let current = path.resolve(startDir || process.cwd())
+
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git")) || fs.existsSync(path.join(current, "package.json"))) {
+      return current
+    }
+
+    const parent = path.dirname(current)
+    if (parent === current) {
+      return path.resolve(startDir || process.cwd())
+    }
+    current = parent
+  }
+}
+
+function createWorkspaceId(projectRoot) {
+  const seed = process.platform === "win32" ? projectRoot.toLowerCase() : projectRoot
+  return crypto.createHash("sha256").update(seed).digest("hex").slice(0, 16)
+}
+
+function resolveProjectRoot(customStatePath) {
+  if (process.env.OPENKIT_PROJECT_ROOT) {
+    return path.resolve(process.env.OPENKIT_PROJECT_ROOT)
+  }
+
+  if (customStatePath) {
+    if (process.env.OPENKIT_GLOBAL_MODE === "1" || process.env.OPENKIT_KIT_ROOT || process.env.OPENCODE_HOME) {
+      return detectProjectRoot(process.cwd())
+    }
+
+    return path.dirname(path.dirname(path.resolve(customStatePath)))
+  }
+
+  return detectProjectRoot(process.cwd())
+}
+
+function resolveKitRoot(projectRoot) {
+  if (process.env.OPENKIT_KIT_ROOT) {
+    return path.resolve(process.env.OPENKIT_KIT_ROOT)
+  }
+
+  return projectRoot
+}
+
+function resolveStatePath(customStatePath) {
+  if (customStatePath) {
+    return path.resolve(customStatePath)
+  }
+
+  if (process.env.OPENKIT_WORKFLOW_STATE) {
+    return path.resolve(process.env.OPENKIT_WORKFLOW_STATE)
+  }
+
+  if (process.env.OPENKIT_GLOBAL_MODE === "1" || process.env.OPENKIT_KIT_ROOT || process.env.OPENCODE_HOME) {
+    const projectRoot = resolveProjectRoot(customStatePath)
+    const workspaceId = createWorkspaceId(projectRoot)
+    return path.join(getOpenCodeHome(), "workspaces", workspaceId, "openkit", ".opencode", "workflow-state.json")
+  }
+
+  return path.resolve(process.cwd(), ".opencode", "workflow-state.json")
+}
+
+function resolveRuntimeRoot(customStatePath) {
+  return path.dirname(path.dirname(resolveStatePath(customStatePath)))
+}
+
+module.exports = {
+  createWorkspaceId,
+  detectProjectRoot,
+  getOpenCodeHome,
+  resolveKitRoot,
+  resolveProjectRoot,
+  resolveRuntimeRoot,
+  resolveStatePath,
+}

package/.opencode/lib/runtime-summary.js

@@ -0,0 +1,82 @@
+const fs = require("fs")
+const path = require("path")
+
+const { readWorkItemIndex, resolveWorkItemPaths } = require("./work-item-store")
+
+const ACTIVE_TASK_STATUSES = new Set(["claimed", "in_progress", "qa_in_progress"])
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null
+  }
+
+  return JSON.parse(fs.readFileSync(filePath, "utf8"))
+}
+
+function getWorkItemIndexIfExists(projectRoot) {
+  const indexPath = path.join(projectRoot, ".opencode", "work-items", "index.json")
+  if (!fs.existsSync(indexPath)) {
+    return null
+  }
+
+  return readWorkItemIndex(projectRoot)
+}
+
+function formatActiveTask(task) {
+  if (task.status === "qa_in_progress" && task.qa_owner) {
+    return `${task.task_id} (${task.status}, qa: ${task.qa_owner})`
+  }
+
+  if (task.primary_owner) {
+    return `${task.task_id} (${task.status}, primary: ${task.primary_owner})`
+  }
+
+  return `${task.task_id} (${task.status})`
+}
+
+function getTaskBoardDetails(projectRoot, state) {
+  if (!state || state.mode !== "full" || !state.work_item_id) {
+    return {
+      present: false,
+      summary: null,
+    }
+  }
+
+  const boardPath = path.join(resolveWorkItemPaths(projectRoot, state.work_item_id).workItemDir, "tasks.json")
+  const board = readJsonIfExists(boardPath)
+  if (!board) {
+    return {
+      present: false,
+      summary: null,
+    }
+  }
+
+  const tasks = Array.isArray(board.tasks) ? board.tasks : []
+  const activeTasks = tasks.filter((task) => ACTIVE_TASK_STATUSES.has(task.status))
+
+  return {
+    present: true,
+    summary: {
+      total: tasks.length,
+      ready: tasks.filter((task) => task.status === "ready").length,
+      active: activeTasks.length,
+      activeTasks: activeTasks.map(formatActiveTask),
+    },
+  }
+}
+
+function getRuntimeContext(projectRoot, state) {
+  const index = getWorkItemIndexIfExists(projectRoot)
+  const taskBoard = getTaskBoardDetails(projectRoot, state)
+
+  return {
+    activeWorkItemId: index?.active_work_item_id ?? state?.work_item_id ?? null,
+    workItemCount: index?.work_items?.length ?? null,
+    taskBoardPresent: taskBoard.present,
+    taskBoardSummary: taskBoard.summary,
+  }
+}
+
+module.exports = {
+  getRuntimeContext,
+}

package/.opencode/lib/state-guard.js

@@ -0,0 +1,99 @@
+const crypto = require("crypto")
+
+function fail(message, details = {}) {
+  const error = new Error(message)
+  error.isStateGuardError = true
+  Object.assign(error, details)
+  throw error
+}
+
+function sortJsonValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJsonValue)
+  }
+
+  if (value && typeof value === "object") {
+    return Object.keys(value)
+      .sort()
+      .reduce((sorted, key) => {
+        sorted[key] = sortJsonValue(value[key])
+        return sorted
+      }, {})
+  }
+
+  return value
+}
+
+function captureRevision(state) {
+  return crypto.createHash("sha256").update(JSON.stringify(sortJsonValue(state))).digest("hex")
+}
+
+function guardWrite({ currentState, expectedRevision, nextState }) {
+  const currentRevision = captureRevision(currentState)
+
+  if (expectedRevision && currentRevision !== expectedRevision) {
+    fail("Rejected stale write because the expected revision no longer matches persisted state", {
+      code: "STALE_WRITE",
+      currentRevision,
+      expectedRevision,
+    })
+  }
+
+  return {
+    currentRevision,
+    nextRevision: captureRevision(nextState),
+    nextState,
+  }
+}
+
+function planGuardedMirrorRefresh({ activeWorkItemId, targetWorkItemId, nextState }) {
+  const shouldRefreshMirror = activeWorkItemId === targetWorkItemId
+
+  return {
+    shouldRefreshMirror,
+    phases: shouldRefreshMirror ? ["primary", "replica"] : ["primary"],
+    stateRevision: captureRevision(nextState),
+    mirrorRevision: shouldRefreshMirror ? captureRevision(nextState) : null,
+  }
+}
+
+function detectMirrorDivergence({ activeWorkItemId, activeState, mirrorState }) {
+  const activeRevision = captureRevision(activeState)
+
+  if (!mirrorState) {
+    return {
+      activeWorkItemId,
+      activeRevision,
+      mirrorRevision: null,
+      isDiverged: true,
+      reason: "mirror_missing",
+    }
+  }
+
+  const mirrorRevision = captureRevision(mirrorState)
+
+  if (mirrorRevision !== activeRevision) {
+    return {
+      activeWorkItemId,
+      activeRevision,
+      mirrorRevision,
+      isDiverged: true,
+      reason: "revision_mismatch",
+    }
+  }
+
+  return {
+    activeWorkItemId,
+    activeRevision,
+    mirrorRevision,
+    isDiverged: false,
+    reason: null,
+  }
+}
+
+module.exports = {
+  captureRevision,
+  detectMirrorDivergence,
+  guardWrite,
+  planGuardedMirrorRefresh,
+}

package/.opencode/lib/task-board-rules.js

@@ -0,0 +1,375 @@
+const TASK_STATUS_VALUES = [
+  "queued",
+  "ready",
+  "claimed",
+  "in_progress",
+  "dev_done",
+  "qa_ready",
+  "qa_in_progress",
+  "done",
+  "blocked",
+  "cancelled",
+]
+
+const REQUIRED_TASK_FIELDS = {
+  task_id: "string",
+  title: "string",
+  summary: "string",
+  kind: "string",
+  status: "string",
+  depends_on: "array",
+  blocked_by: "array",
+  artifact_refs: "array",
+  plan_refs: "array",
+  branch_or_worktree: "nullable_string",
+  created_by: "string",
+  created_at: "string",
+  updated_at: "string",
+}
+
+const IMPLEMENTATION_READY_STATUSES = new Set([
+  "ready",
+  "claimed",
+  "in_progress",
+  "dev_done",
+  "qa_ready",
+  "qa_in_progress",
+])
+
+const DEPENDENCY_SATISFIED_STATUSES = new Set([
+  "dev_done",
+  "qa_ready",
+  "qa_in_progress",
+  "done",
+  "cancelled",
+])
+
+const FULL_QA_ALLOWED_STATUSES = new Set([
+  "dev_done",
+  "qa_ready",
+  "qa_in_progress",
+  "done",
+  "cancelled",
+])
+
+const TRANSITIONS = new Map([
+  ["queued", new Set(["ready", "cancelled"])],
+  ["ready", new Set(["claimed", "cancelled"])],
+  ["claimed", new Set(["in_progress", "cancelled"])],
+  ["in_progress", new Set(["dev_done", "cancelled"])],
+  ["dev_done", new Set(["qa_ready", "cancelled"])],
+  ["qa_ready", new Set(["qa_in_progress", "cancelled"])],
+  ["qa_in_progress", new Set(["done", "blocked", "claimed", "in_progress", "cancelled"])],
+  ["blocked", new Set(["claimed", "in_progress", "cancelled"])],
+  ["done", new Set(["cancelled"])],
+  ["cancelled", new Set()],
+])
+
+function fail(message) {
+  throw new Error(message)
+}
+
+function formatModeLabel(mode) {
+  return typeof mode === "string" && mode.length > 0 ? `${mode.charAt(0).toUpperCase()}${mode.slice(1)}` : "Unknown"
+}
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0
+}
+
+function validateStringArrayEntries(field, values) {
+  for (const value of values) {
+    if (!isNonEmptyString(value)) {
+      fail(`Task field '${field}' must contain only non-empty strings`)
+    }
+  }
+}
+
+function validateTaskStatus(status) {
+  if (!TASK_STATUS_VALUES.includes(status)) {
+    fail(`Unknown task status '${status}'`)
+  }
+
+  return status
+}
+
+function validateTaskShape(task) {
+  if (!task || typeof task !== "object" || Array.isArray(task)) {
+    fail("Task must be an object")
+  }
+
+  for (const [field, kind] of Object.entries(REQUIRED_TASK_FIELDS)) {
+    if (!(field in task) || task[field] === undefined) {
+      fail(`Task is missing required field '${field}'`)
+    }
+
+    if (kind === "string" && !isNonEmptyString(task[field])) {
+      fail(`Task field '${field}' must be a non-empty string`)
+    }
+
+    if (kind === "array" && !Array.isArray(task[field])) {
+      fail(`Task field '${field}' must be an array`)
+    }
+
+    if (kind === "array" && Array.isArray(task[field])) {
+      validateStringArrayEntries(field, task[field])
+    }
+
+    if (
+      kind === "nullable_string" &&
+      task[field] !== null &&
+      task[field] !== undefined &&
+      !isNonEmptyString(task[field])
+    ) {
+      fail(`Task field '${field}' must be null or a non-empty string`)
+    }
+  }
+
+  if (task.primary_owner !== null && task.primary_owner !== undefined && !isNonEmptyString(task.primary_owner)) {
+    fail("Task field 'primary_owner' must be null or a non-empty string")
+  }
+
+  if (task.qa_owner !== null && task.qa_owner !== undefined && !isNonEmptyString(task.qa_owner)) {
+    fail("Task field 'qa_owner' must be null or a non-empty string")
+  }
+
+  validateTaskStatus(task.status)
+  return task
+}
+
+function hasBlockedDependencies(task) {
+  return Array.isArray(task.blocked_by) && task.blocked_by.length > 0
+}
+
+function validateTaskTransition(task, nextStatus, options = {}) {
+  validateTaskShape(task)
+  validateTaskStatus(nextStatus)
+
+  const allowedTargets = TRANSITIONS.get(task.status)
+  if (!allowedTargets || !allowedTargets.has(nextStatus)) {
+    fail(`Invalid task transition '${task.status} -> ${nextStatus}'`)
+  }
+
+  if ((task.status === "queued" && nextStatus === "ready") || (task.status === "ready" && nextStatus === "claimed")) {
+    if (hasBlockedDependencies(task)) {
+      fail(`Task '${task.task_id}' cannot move to '${nextStatus}' with a blocked dependency`)
+    }
+  }
+
+  if (task.status === "claimed" && nextStatus === "in_progress" && !isNonEmptyString(task.primary_owner)) {
+    fail(`Task '${task.task_id}' requires a primary_owner before entering 'in_progress'`)
+  }
+
+  if (task.status === "in_progress" && nextStatus === "dev_done" && !isNonEmptyString(task.primary_owner)) {
+    fail(`Task '${task.task_id}' requires a primary_owner before entering 'dev_done'`)
+  }
+
+  if (
+    task.status === "dev_done" &&
+    nextStatus === "qa_ready" &&
+    !isNonEmptyString(task.qa_owner) &&
+    options.allowQaAssignment !== true
+  ) {
+    fail(`Task '${task.task_id}' requires a qa_owner or explicit QA assignment availability before entering 'qa_ready'`)
+  }
+
+  if (
+    task.status === "qa_ready" &&
+    nextStatus === "qa_in_progress" &&
+    !isNonEmptyString(task.qa_owner) &&
+    options.allowQaClaim !== true
+  ) {
+    fail(`Task '${task.task_id}' requires a qa_owner or explicit QA claim availability before entering 'qa_in_progress'`)
+  }
+
+  if (
+    task.status === "qa_in_progress" &&
+    (nextStatus === "done" || nextStatus === "blocked") &&
+    !isNonEmptyString(task.qa_owner)
+  ) {
+    fail(`Task '${task.task_id}' requires a qa_owner before entering '${nextStatus}'`)
+  }
+
+  if (task.status === "qa_in_progress" && (nextStatus === "claimed" || nextStatus === "in_progress")) {
+    if (!options.allowQaFailRework) {
+      fail(`QA fail rework transitions require explicit allowQaFailRework for task '${task.task_id}'`)
+    }
+
+    if (!options.finding || typeof options.finding !== "object") {
+      fail(`QA fail rework transitions require a task-scoped finding for task '${task.task_id}'`)
+    }
+
+    if (options.finding.task_id !== task.task_id || !isNonEmptyString(options.finding.summary)) {
+      fail(`QA fail rework transitions require a task-scoped finding for task '${task.task_id}'`)
+    }
+  }
+
+  return nextStatus
+}
+
+function buildTaskIndex(tasks) {
+  const index = new Map()
+
+  for (const task of tasks) {
+    if (index.has(task.task_id)) {
+      fail(`Duplicate task_id '${task.task_id}' in task board`)
+    }
+
+    index.set(task.task_id, task)
+  }
+
+  return index
+}
+
+function validateDependencyReferences(tasks, taskIndex) {
+  for (const task of tasks) {
+    for (const dependencyId of task.depends_on) {
+      if (!taskIndex.has(dependencyId)) {
+        fail(`Task '${task.task_id}' depends on unknown task '${dependencyId}'`)
+      }
+    }
+
+    for (const blockedId of task.blocked_by) {
+      if (!taskIndex.has(blockedId)) {
+        fail(`Task '${task.task_id}' is blocked by unknown task '${blockedId}'`)
+      }
+    }
+  }
+}
+
+function detectDependencyCycle(tasks) {
+  const visiting = new Set()
+  const visited = new Set()
+  const taskIndex = buildTaskIndex(tasks)
+
+  function visit(taskId, trail) {
+    if (visiting.has(taskId)) {
+      fail(`Dependency cycle detected: ${[...trail, taskId].join(" -> ")}`)
+    }
+
+    if (visited.has(taskId)) {
+      return
+    }
+
+    visiting.add(taskId)
+    const task = taskIndex.get(taskId)
+    for (const dependencyId of task.depends_on) {
+      visit(dependencyId, [...trail, taskId])
+    }
+    visiting.delete(taskId)
+    visited.add(taskId)
+  }
+
+  for (const task of tasks) {
+    visit(task.task_id, [])
+  }
+}
+
+function validateDependencyState(tasks, taskIndex) {
+  for (const task of tasks) {
+    const unresolvedDependencies = task.depends_on.filter((dependencyId) => {
+      const dependency = taskIndex.get(dependencyId)
+      return !DEPENDENCY_SATISFIED_STATUSES.has(dependency.status)
+    })
+
+    const activeWhileBlocked = ["ready", "claimed", "in_progress"].includes(task.status)
+    if (activeWhileBlocked && unresolvedDependencies.length > 0) {
+      fail(`Task '${task.task_id}' cannot be '${task.status}' while blocked by unresolved dependencies: ${unresolvedDependencies.join(", ")}`)
+    }
+
+    if (task.status === "claimed" && !isNonEmptyString(task.primary_owner)) {
+      fail(`Task '${task.task_id}' in 'claimed' status requires a primary_owner`)
+    }
+
+    if (task.status === "in_progress" && !isNonEmptyString(task.primary_owner)) {
+      fail(`Task '${task.task_id}' in 'in_progress' status requires a primary_owner`)
+    }
+
+    if (task.status === "dev_done" && !isNonEmptyString(task.primary_owner)) {
+      fail(`Task '${task.task_id}' in 'dev_done' status requires a primary_owner`)
+    }
+
+    if ((task.status === "qa_in_progress" || task.status === "done" || task.status === "blocked") && !isNonEmptyString(task.qa_owner)) {
+      fail(`Task '${task.task_id}' in '${task.status}' status requires a qa_owner`)
+    }
+  }
+}
+
+function validateBoardShape(board) {
+  if (!board || typeof board !== "object" || Array.isArray(board)) {
+    fail("Task board must be an object")
+  }
+
+  if (board.mode !== "full") {
+    fail(`${formatModeLabel(board.mode)} mode cannot carry a task board; task boards are full-delivery only`)
+  }
+
+  if (!Array.isArray(board.tasks)) {
+    fail("Task board must include a tasks array")
+  }
+
+  if (board.tasks.length === 0) {
+    fail("Full-delivery task board must include at least one task")
+  }
+
+  if (board.issues !== undefined && !Array.isArray(board.issues)) {
+    fail("Task board issues must be an array when provided")
+  }
+}
+
+function validateAggregateRules(board, tasks) {
+  if (board.current_stage === "full_implementation") {
+    const hasImplementationReadyTask = tasks.some((task) => IMPLEMENTATION_READY_STATUSES.has(task.status))
+    if (!hasImplementationReadyTask) {
+      fail("A full_implementation board must include at least one implementation-active task")
+    }
+  }
+
+  if (board.current_stage === "full_qa") {
+    const hasIncompleteImplementationTask = tasks.some((task) => !FULL_QA_ALLOWED_STATUSES.has(task.status))
+    if (hasIncompleteImplementationTask) {
+      fail("A full_qa board cannot include tasks with incomplete implementation work")
+    }
+  }
+
+  if (board.current_stage === "full_done") {
+    const hasRemainingTask = tasks.some((task) => !["done", "cancelled"].includes(task.status))
+    if (hasRemainingTask) {
+      fail("A full_done board requires every required task to be done or cancelled")
+    }
+
+    const hasBlockingIssue = (board.issues ?? []).some((issue) => {
+      if (!issue || typeof issue !== "object") {
+        return false
+      }
+
+      return issue.blocks_completion === true && issue.status !== "resolved" && issue.status !== "closed"
+    })
+
+    if (hasBlockingIssue) {
+      fail("A full_done board cannot close with an open blocking issue")
+    }
+  }
+}
+
+function validateTaskBoard(board) {
+  validateBoardShape(board)
+
+  const tasks = board.tasks.map((task) => validateTaskShape(task))
+  const taskIndex = buildTaskIndex(tasks)
+
+  validateDependencyReferences(tasks, taskIndex)
+  detectDependencyCycle(tasks)
+  validateDependencyState(tasks, taskIndex)
+  validateAggregateRules(board, tasks)
+
+  return board
+}
+
+module.exports = {
+  TASK_STATUS_VALUES,
+  validateTaskBoard,
+  validateTaskShape,
+  validateTaskStatus,
+  validateTaskTransition,
+}