opencode-overclock 0.3.0 → 0.5.0

package/src/features/workflow.ts

@@ -0,0 +1,256 @@
+import { existsSync } from "node:fs"
+import { resolve, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+import type { FeatureModule, WorkflowOptions } from "../core/types.ts"
+import { DEFINE_TEMPLATE } from "../workflow/templates/define.ts"
+import { PLAN_TEMPLATE } from "../workflow/templates/plan.ts"
+import { BUILD_TEMPLATE } from "../workflow/templates/build.ts"
+import { DIAGNOSE_TEMPLATE } from "../workflow/templates/diagnose.ts"
+import { SHIP_TEMPLATE } from "../workflow/templates/ship.ts"
+import { STANDARDS_REVIEWER_PROMPT } from "../workflow/agents/standards-reviewer.ts"
+import { SPEC_REVIEWER_PROMPT } from "../workflow/agents/spec-reviewer.ts"
+import { SECURITY_AUDITOR_PROMPT } from "../workflow/agents/security-auditor.ts"
+import { TEST_ENGINEER_PROMPT } from "../workflow/agents/test-engineer.ts"
+import { PERFORMANCE_AUDITOR_PROMPT } from "../workflow/agents/performance-auditor.ts"
+import { DOUBT_REVIEWER_PROMPT } from "../workflow/agents/doubt-reviewer.ts"
+import { CODEBASE_RESEARCHER_PROMPT } from "../workflow/agents/codebase-researcher.ts"
+import { DESIGN_EXPLORER_PROMPT } from "../workflow/agents/design-explorer.ts"
+import { ENGINEERING_COACH_PROMPT } from "../workflow/agents/engineering-coach.ts"
+
+function getBundledSkillsDir(customPath?: string): string {
+  if (customPath) return customPath
+  const currentDir =
+    typeof import.meta.dir === "string" ? import.meta.dir : dirname(fileURLToPath(import.meta.url))
+  return resolve(currentDir, "../../skills")
+}
+
+export const WORKFLOW_COMMANDS = {
+  define: {
+    description: "Interrogate requirements and draft SPEC.md with recommended defaults",
+    template: DEFINE_TEMPLATE,
+  },
+  plan: {
+    description: "Decompose spec into vertical tracer-bullet tasks in tasks/plan.md",
+    template: PLAN_TEMPLATE,
+  },
+  build: {
+    description: "Autonomous TDD implementation with tripwires and atomic commits",
+    template: BUILD_TEMPLATE,
+  },
+  diagnose: {
+    description: "Disciplined bug reproduction and isolation loop ([DEBUG-xxxx] tags)",
+    template: DIAGNOSE_TEMPLATE,
+  },
+  ship: {
+    description: "3-way parallel review (Standards, Spec, Security) with GO/NO-GO verdict",
+    template: SHIP_TEMPLATE,
+  },
+}
+
+export const WORKFLOW_AGENTS = {
+  "standards-reviewer": {
+    mode: "subagent" as const,
+    description: "Senior Staff Engineer auditing diffs for repo conventions and code smells",
+    prompt: STANDARDS_REVIEWER_PROMPT,
+    tools: {
+      write: false,
+      edit: false,
+    },
+    permission: {
+      edit: "deny" as const,
+    },
+  },
+  "spec-reviewer": {
+    mode: "subagent" as const,
+    description: "Product Engineer auditing diffs strictly against originating specifications",
+    prompt: SPEC_REVIEWER_PROMPT,
+    tools: {
+      write: false,
+      edit: false,
+    },
+    permission: {
+      edit: "deny" as const,
+    },
+  },
+  "security-auditor": {
+    mode: "subagent" as const,
+    description: "Adversarial Security Engineer auditing diffs for OWASP vulnerabilities and secrets",
+    prompt: SECURITY_AUDITOR_PROMPT,
+    tools: {
+      write: false,
+      edit: false,
+    },
+    permission: {
+      edit: "deny" as const,
+    },
+  },
+  "test-engineer": {
+    mode: "subagent" as const,
+    description: "QA Engineer auditing test strategy, coverage gaps, and Prove-It verification",
+    prompt: TEST_ENGINEER_PROMPT,
+    tools: {
+      write: false,
+      edit: false,
+    },
+    permission: {
+      edit: "deny" as const,
+    },
+  },
+  "performance-auditor": {
+    mode: "subagent" as const,
+    description: "Senior Performance Engineer auditing latency, N+1 queries, and resource leaks",
+    prompt: PERFORMANCE_AUDITOR_PROMPT,
+    tools: {
+      write: false,
+      edit: false,
+    },
+    permission: {
+      edit: "deny" as const,
+    },
+  },
+  "doubt-reviewer": {
+    mode: "subagent" as const,
+    description: "Adversarial Verification Engineer evaluating artifacts without author bias",
+    prompt: DOUBT_REVIEWER_PROMPT,
+    tools: {
+      write: false,
+      edit: false,
+    },
+    permission: {
+      edit: "deny" as const,
+    },
+  },
+  "codebase-researcher": {
+    mode: "subagent" as const,
+    description: "Scout Agent tracing seams, dependencies, and call graphs without polluting context",
+    prompt: CODEBASE_RESEARCHER_PROMPT,
+    tools: {
+      write: false,
+      edit: false,
+    },
+    permission: {
+      edit: "deny" as const,
+    },
+  },
+  "design-explorer": {
+    mode: "subagent" as const,
+    description: "Principal Architect producing contrasting 'Design It Twice' interface proposals",
+    prompt: DESIGN_EXPLORER_PROMPT,
+    tools: {
+      write: false,
+      edit: false,
+    },
+    permission: {
+      edit: "deny" as const,
+    },
+  },
+  "engineering-coach": {
+    mode: "subagent" as const,
+    description: "Elite Staff Mentor providing Socratic debugging guidance and design critique",
+    prompt: ENGINEERING_COACH_PROMPT,
+    tools: {
+      write: false,
+      edit: false,
+    },
+    permission: {
+      edit: "deny" as const,
+    },
+  },
+}
+
+export const workflow: FeatureModule = {
+  name: "workflow",
+  defaultEnabled: true,
+  tools: [],
+  async init(_ctx, options) {
+    const opts = (options ?? {}) as WorkflowOptions
+    if (opts.enabled === false) {
+      return {}
+    }
+
+    const skillsPath = getBundledSkillsDir(opts.skillsPath)
+
+    return {
+      config: async (cfg: any) => {
+        if (opts.commands !== false) {
+          cfg.command = {
+            ...WORKFLOW_COMMANDS,
+            ...(cfg.command ?? {}),
+          }
+        }
+
+        if (opts.subagents !== false) {
+          cfg.agent = {
+            ...WORKFLOW_AGENTS,
+            ...(cfg.agent ?? {}),
+          }
+        }
+
+        if (existsSync(skillsPath)) {
+          cfg.skills = typeof cfg.skills === "object" && cfg.skills !== null ? cfg.skills : {}
+          if (!Array.isArray(cfg.skills.paths)) {
+            cfg.skills.paths = []
+          }
+          if (!cfg.skills.paths.includes(skillsPath)) {
+            cfg.skills.paths.push(skillsPath)
+          }
+        }
+      },
+    }
+  },
+
+  setup: async (v2Context, options) => {
+    const opts = (options ?? {}) as WorkflowOptions
+    if (opts.enabled === false) return
+
+    if (opts.commands !== false && v2Context.command?.transform) {
+      await v2Context.command.transform(async (draft) => {
+        for (const [name, cmd] of Object.entries(WORKFLOW_COMMANDS)) {
+          draft.update(name, (current) => {
+            current.name = current.name ?? name
+            current.description = current.description ?? cmd.description
+            current.template = current.template ?? cmd.template
+          })
+        }
+      })
+    }
+
+    if (opts.subagents !== false && v2Context.agent?.transform) {
+      await v2Context.agent.transform(async (draft) => {
+        for (const [id, ag] of Object.entries(WORKFLOW_AGENTS)) {
+          draft.update(id, (current) => {
+            current.mode = current.mode ?? ag.mode
+            current.description = current.description ?? ag.description
+            current.system = current.system ?? ag.prompt
+            if (ag.permission?.edit === "deny") {
+              const perms = (current.permissions as any[]) ?? []
+              const hasDenyEdit = perms.some((p: any) => p.action === "edit" && p.effect === "deny")
+              if (!hasDenyEdit) {
+                perms.push({
+                  action: "edit",
+                  resource: "*",
+                  effect: "deny",
+                })
+                current.permissions = perms as any
+              }
+            }
+          })
+        }
+      })
+    }
+
+    const skillsPath = getBundledSkillsDir(opts.skillsPath)
+    if (existsSync(skillsPath) && v2Context.skill?.transform) {
+      await v2Context.skill.transform(async (draft) => {
+        const existing = draft.list?.() ?? []
+        const alreadyAdded = existing.some((s: any) => s.type === "directory" && s.path === skillsPath)
+        if (!alreadyAdded) {
+          draft.source({
+            type: "directory",
+            path: skillsPath,
+          } as any)
+        }
+      })
+    }
+  },
+}

package/src/index.ts

@@ -1,85 +1,114 @@
-import type { Hooks, Plugin } from "@opencode-ai/plugin"
+import type { Hooks } from "@opencode-ai/plugin"
 import { features } from "./features/index.ts"
-import { loadConfig } from "./config.ts"
-import { mergeHooks } from "./merge.ts"
+import { mergeHooks } from "./core/lifecycle.ts"
+import { resolveToolPolicy } from "./core/policy.ts"
+import { summarise } from "./core/summary.ts"
+import { createHybridPlugin, type HybridPlugin } from "./core/bridge.ts"
+import type { FeatureModule, OverclockOptions, SharedDeps } from "./core/types.ts"
 import { missingSurfaces } from "./lib/probe.ts"
 import { toast } from "./lib/inject.ts"
 import { firstRun } from "./lib/state.ts"
-import { validateConfig, summarise } from "./validate.ts"
 import { createBusyTracker } from "./lib/busy.ts"
-import { EMPTY_POLICY, resolveToolPolicy, type ToolPolicy } from "./tools.ts"
-import type { FeatureModule, SharedDeps } from "./types.ts"
+import { createV2Host } from "./v2/host.ts"
+
+function featureOptions(
+  options: OverclockOptions,
+  feature: FeatureModule,
+): Record<string, unknown> | null {
+  const setting = options[feature.name] ?? options.features?.[feature.name] ?? feature.defaultEnabled
+  if (setting === false) return null
+  return typeof setting === "object" && setting !== null ? (setting as Record<string, unknown>) : {}
+}
 
 /**
- * Entry. Load config -> probe surfaces -> init enabled modules -> merge hooks.
- * Module crash or missing SDK surface (upstream drift) -> skip module, plugin survive.
+ * Entry. Read options -> probe surfaces -> init enabled modules -> merge hooks.
+ * Employs createHybridPlugin so the plugin is runnable on both V1 and V2 OpenCode harnesses.
  */
-export const Overclock: Plugin = async (ctx) => {
-  const config = await loadConfig(ctx.directory)
+export const Overclock: HybridPlugin<OverclockOptions> = createHybridPlugin<OverclockOptions>({
+  id: "overclock",
+
+  /** V1 lifecycle: tools, execution interception, event bus hooks */
+  server: async (ctx, pluginOptions) => {
+    const options = (pluginOptions ?? {}) as OverclockOptions
+    const { policy, issues } = resolveToolPolicy(options, features)
+
+    const shared: SharedDeps = {
+      busy: createBusyTracker(),
+      toolName: (declared) => policy.rename[declared] ?? declared,
+    }
+    const parts: Partial<Hooks>[] = [{ event: async ({ event }) => shared.busy.onEvent(event) }]
+    const skipped: string[] = []
+    const enabled: FeatureModule[] = []
+
+    for (const feature of features) {
+      const opts = featureOptions(options, feature)
+      if (opts === null) continue
 
-  // Collected now, reported once the tool policy is known so a single pass covers both.
-  const issues = validateConfig(config, features)
+      const missing = missingSurfaces(ctx.client, feature.requires ?? [])
+      if (missing.length) {
+        console.warn(
+          `[overclock] ${feature.name} disabled: client lacks ${missing.join(", ")} (upstream drift?)`,
+        )
+        skipped.push(feature.name)
+        continue
+      }
 
-  // Resolved after the init loop, against the modules that actually loaded -- warning about a
-  // tool belonging to a disabled feature would be noise. Modules only call `toolName` at
-  // runtime (a hook or timer, long after init), so reading it through this binding is safe.
-  let policy: ToolPolicy = EMPTY_POLICY
-  const shared: SharedDeps = {
-    busy: createBusyTracker(),
-    toolName: (declared) => policy.rename[declared] ?? declared,
-  }
-  // First part, so the tracker is current before any module's own event hook reads it.
-  const parts: Partial<Hooks>[] = [{ event: async ({ event }) => shared.busy.onEvent(event) }]
-  const skipped: string[] = []
-  const enabled: FeatureModule[] = []
+      try {
+        parts.push(await feature.init(ctx, opts, shared))
+        enabled.push(feature)
+      } catch (e) {
+        console.warn(`[overclock] feature ${feature.name} failed init: ${e}`)
+      }
+    }
 
-  for (const feature of features) {
-    const setting = config.features?.[feature.name] ?? feature.defaultEnabled
-    if (setting === false) continue
-    const missing = missingSurfaces(ctx.client, feature.requires ?? [])
-    if (missing.length) {
-      console.warn(
-        `[overclock] ${feature.name} disabled: client lacks ${missing.join(", ")} (upstream drift?)`,
+    if (Array.isArray(options.plugins) && options.plugins.length > 0) {
+      const v2Host = createV2Host(ctx, options)
+      const loadedV2 = await v2Host.loadPlugins(options.plugins)
+      if (loadedV2.length > 0) {
+        console.warn(`[overclock] loaded ${loadedV2.length} v2 plugin(s): ${loadedV2.join(", ")}`)
+      }
+      parts.push(v2Host.createHooks())
+    }
+
+    for (const issue of issues) {
+      console.warn(`[overclock] config: ${issue.path ? `${issue.path}: ` : ""}${issue.message}`)
+    }
+    if (issues.length) {
+      void toast(
+        ctx.client,
+        `overclock: ${issues.length} config issue${issues.length > 1 ? "s" : ""} (see logs)`,
+        "warning",
       )
-      skipped.push(feature.name)
-      continue
     }
-    const options = typeof setting === "object" ? setting : {}
-    try {
-      parts.push(await feature.init(ctx, options, shared))
-      enabled.push(feature)
-    } catch (e) {
-      console.warn(`[overclock] feature ${feature.name} failed init: ${e}`)
+
+    const summary = summarise(enabled, skipped, policy)
+    console.warn(`[overclock] ${summary}`)
+    if (await firstRun(ctx.directory)) {
+      void toast(ctx.client, `overclock active: ${summary}`, "info")
     }
-  }
 
-  const resolved = resolveToolPolicy(config, enabled)
-  policy = resolved.policy
-  issues.push(...resolved.issues)
+    if (skipped.length) {
+      void toast(ctx.client, `overclock: ${skipped.join(", ")} disabled (SDK drift)`, "warning")
+    }
+    return mergeHooks(parts, policy)
+  },
 
-  // A mistyped key is otherwise a silent no-op -- the feature runs with defaults and the
-  // user believes their setting took effect. Warn, never throw: bad config degrades to
-  // defaults rather than taking the plugin down.
-  for (const issue of issues) {
-    console.warn(`[overclock] config: ${issue.path ? `${issue.path}: ` : ""}${issue.message}`)
-  }
-  if (issues.length) {
-    void toast(
-      ctx.client,
-      `overclock: ${issues.length} config issue${issues.length > 1 ? "s" : ""} (see logs)`,
-      "warning",
-    )
-  }
+  /** V2 lifecycle: domain transforms (agents, commands, catalog, aisdk) */
+  setup: async (v2Context, pluginOptions) => {
+    const options = (pluginOptions ?? {}) as OverclockOptions
 
-  // Say what was added. This plugin grants the agent background shell execution and
-  // recurring scheduling; that should not be discovered by accident. Log every start
-  // (stderr, invisible unless you look), toast only on a project's first run.
-  console.warn(`[overclock] ${summarise(enabled, skipped, policy)}`)
-  if (await firstRun(ctx.directory)) {
-    void toast(ctx.client, `overclock active: ${summarise(enabled, skipped, policy)}`, "info")
-  }
+    for (const feature of features) {
+      if (!feature.setup) continue
+      const opts = featureOptions(options, feature)
+      if (opts === null) continue
 
-  if (skipped.length)
-    void toast(ctx.client, `overclock: ${skipped.join(", ")} disabled (SDK drift)`, "warning")
-  return mergeHooks(parts, policy)
-}
+      try {
+        await feature.setup(v2Context, opts)
+      } catch (e) {
+        console.warn(`[overclock] feature ${feature.name} failed v2 setup: ${e}`)
+      }
+    }
+  },
+})
+
+export default Overclock

package/src/lib/busy.ts

@@ -1,25 +1 @@
-/**
- * Session busy tracking via `session.status` (doc-preferred; `session.idle` deprecated).
- * Unknown/never-firing statuses degrade gracefully: empty set = nothing reported busy.
- */
-export interface BusyTracker {
-  /** feed bus events */
-  onEvent(event: { type: string; properties?: unknown }): void
-  isBusy(sessionID: string): boolean
-}
-
-export function createBusyTracker(): BusyTracker {
-  const busy = new Set<string>()
-  return {
-    onEvent(event) {
-      const p = (event.properties ?? {}) as { sessionID?: string; status?: { type?: string } }
-      if (!p.sessionID) return
-      if (event.type === "session.status") {
-        p.status?.type === "idle" ? busy.delete(p.sessionID) : busy.add(p.sessionID)
-      } else if (event.type === "session.idle" || event.type === "session.deleted") {
-        busy.delete(p.sessionID)
-      }
-    },
-    isBusy: (id) => busy.has(id),
-  }
-}
+export { createBusyTracker, type BusyTracker } from "../platform/session/busy.ts"

package/src/lib/exec.ts

@@ -0,0 +1,13 @@
+export {
+  execBash,
+  killProcessTree,
+  shellQuote,
+  sanitizeEnv,
+  redactSensitiveOutput,
+  NON_INTERACTIVE_ENV,
+  DEFAULT_PRESERVED_ENV,
+  SENSITIVE_ENV_PATTERN,
+  SENSITIVE_OUTPUT_PATTERNS,
+  type ExecBashOptions,
+  type ExecBashResult,
+} from "../platform/process/exec.ts"

package/src/lib/inject.ts

@@ -1,56 +1,10 @@
-import type { PluginInput } from "@opencode-ai/plugin"
-
-type Client = PluginInput["client"]
-type ModelRef = { providerID: string; modelID: string }
-
-/**
- * Session's active model = model of last assistant message.
- * Without this, promptAsync falls back to config default model -> injected turns
- * run on the wrong model (and pile up QUEUED behind a hung default).
- */
-export async function sessionModel(client: Client, sessionID: string): Promise<ModelRef | undefined> {
-  try {
-    const res = await client.session.messages({ path: { id: sessionID } })
-    const msgs = res.data ?? []
-    for (let i = msgs.length - 1; i >= 0; i--) {
-      const info = msgs[i]?.info
-      if (info?.role === "assistant" && info.modelID) {
-        return { providerID: info.providerID, modelID: info.modelID }
-      }
-    }
-  } catch (e) {
-    console.warn(`[overclock] sessionModel lookup failed (${sessionID}): ${e}`)
-  }
-  return undefined
-}
-
-/**
- * Re-entry: push text into session as user prompt, on the session's own model.
- * promptAsync = fire-and-forget, server queues if busy. Failure -> warn, never throw.
- */
-export async function inject(client: Client, sessionID: string, text: string): Promise<boolean> {
-  try {
-    const model = await sessionModel(client, sessionID)
-    await client.session.promptAsync({
-      path: { id: sessionID },
-      body: { parts: [{ type: "text", text }], ...(model ? { model } : {}) },
-    })
-    return true
-  } catch (e) {
-    console.warn(`[overclock] inject failed (session ${sessionID}): ${e}`)
-    return false
-  }
-}
-
-/** TUI toast, best-effort (headless server -> no TUI, swallow). */
-export async function toast(
-  client: Client,
-  message: string,
-  variant: "info" | "success" | "warning" | "error" = "info",
-): Promise<void> {
-  try {
-    await client.tui.showToast({ body: { message, variant } })
-  } catch {
-    // no TUI attached
-  }
-}
+export {
+  inject,
+  sessionContext,
+  sessionModel,
+  toast,
+  type InjectOptions,
+  type ModelRef,
+  type SessionContext,
+  type ToastVariant,
+} from "../platform/session/inject.ts"

package/src/lib/mirror.ts

@@ -0,0 +1,13 @@
+export {
+  scheduleStore,
+  taskStore,
+  usageStore,
+  type DayBucket,
+  type DayBucketView,
+  type ScheduleEntry,
+  type ScheduleEntryView,
+  type TaskMirrorEntry,
+  type UsageState,
+  type UsageStateView,
+  type UsageTokens,
+} from "../platform/storage/store.ts"

package/src/lib/probe.ts

@@ -1,15 +1 @@
-/**
- * Runtime surface probe (doc: "probe for the surfaces we depend on ... instead of
- * failing silently when upstream moves"). Dot-paths resolved against the SDK client;
- * leaf must be a function.
- */
-export function missingSurfaces(client: unknown, paths: string[]): string[] {
-  return paths.filter((path) => {
-    let node: unknown = client
-    for (const key of path.split(".")) {
-      if (node == null || typeof node !== "object") return true
-      node = (node as Record<string, unknown>)[key]
-    }
-    return typeof node !== "function"
-  })
-}
+export { missingSurfaces } from "../platform/probe.ts"

package/src/lib/state.ts

@@ -1,39 +1,10 @@
-import { mkdir } from "node:fs/promises"
-
-/** State root: <project>/.opencode/overclock/[sub]. Creates if missing. */
-export async function ensureStateDir(directory: string, sub?: string): Promise<string> {
-  const dir = `${directory}/.opencode/overclock${sub ? `/${sub}` : ""}`
-  await mkdir(dir, { recursive: true })
-  return dir
-}
-
-/**
- * True once per project, then never again. Marker lives beside the other state, so
- * deleting .opencode/overclock/ re-arms the first-run notice.
- */
-export async function firstRun(directory: string): Promise<boolean> {
-  const dir = await ensureStateDir(directory)
-  const marker = Bun.file(`${dir}/.installed`)
-  if (await marker.exists()) return false
-  await Bun.write(marker, new Date().toISOString())
-  return true
-}
-
-export async function readJson<T>(path: string, fallback: T): Promise<T> {
-  const file = Bun.file(path)
-  if (!(await file.exists())) return fallback
-  try {
-    return (await file.json()) as T
-  } catch {
-    return fallback
-  }
-}
-
-export async function writeJson(path: string, value: unknown): Promise<void> {
-  await Bun.write(path, JSON.stringify(value, null, 2))
-}
-
-/** POSIX single-quote escape. */
-export function shellQuote(s: string): string {
-  return `'${s.replace(/'/g, `'\\''`)}'`
-}
+export {
+  defineStore,
+  ensureStateDir,
+  firstRun,
+  readJson,
+  shellQuote,
+  stateDir,
+  writeJson,
+  type Store,
+} from "../platform/storage/state.ts"

package/src/lib/tmux.ts

@@ -0,0 +1 @@
+export { isInsideTmux, spawnTaskPane, type TmuxPane } from "../platform/process/tmux.ts"