@bybrawe/opencode-loop 0.5.29 → 0.5.30

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.5.30
+
+- Harden npm publishing so a one-shot release publishes the immutable trigger SHA, verifies that commit belongs to `main`, serializes releases, confirms the package is readable from npm, and tags exactly the published snapshot.
+- Extend the experimental OpenCode 2 command registry with read-only `/loop-export`, `/loop-help`, and `/loop-doctor` diagnostics.
+- Keep OpenCode 2 diagnostics conservative: help advertises only implemented V2 behavior, doctor reports local runtime/state information, and full stable-plugin parity remains explicitly unclaimed.
+- Expand V2 lifecycle, real `@next` command-registry, general CI, and generated-bundle gates around the new diagnostics and release-safety contracts.
+
 ## 0.5.29
 
 - Fix `--no-now` first-run semantics end to end: delayed jobs now wait until `createdAt + interval`, and stable `/loop-status` reports that first due time correctly instead of showing the job as immediately due.

package/README.md

@@ -4,7 +4,7 @@
 
 OpenCode Loop adds `/loop`, scheduled prompt/command/shell jobs, compact scheduling, safe long-running continuation helpers, and the `opencode-loopd` background daemon.
 
-> **Current release: `0.5.29`.** Loop also contains an older experimental `/loop-goal` mode, but for strong persistent Goal contracts and host-verified completion, use the separate **OpenCode Goals** plugin described below.
+> **Current release: `0.5.30`.** Loop also contains an older experimental `/loop-goal` mode, but for strong persistent Goal contracts and host-verified completion, use the separate **OpenCode Goals** plugin described below.
 
 ## Install or update
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bybrawe/opencode-loop",
-  "version": "0.5.29",
+  "version": "0.5.30",
   "description": "Claude Code/Codex style /loop and experimental goal mode for OpenCode: heartbeat scheduler, idle-safe loops, scheduled commands, compact scheduling, verification, checkpoints, and persistent coding goals.",
   "type": "module",
   "main": "src/index.js",
@@ -21,8 +21,8 @@
     "build:plugin": "bun build src/source/v1.js --outfile=src/index.js --target=bun --format=esm --external=@opencode-ai/plugin/tool",
     "build:plugin:npm": "npm run build:plugin",
     "prepack": "node --check src/index.js",
-    "check": "node --check src/source/v1.js && node --check src/source/core/args.js && node --check src/source/core/state.js && node --check src/source/core/jobs.js && node --check src/source/core/process.js && node --check src/source/opencode/sdk.js && node --check src/source/opencode/session-context.js && node --check src/source/opencode/command-router.js && node --check src/source/opencode/goal-commands.js && node --check src/source/opencode/loop-commands.js && node --check src/source/opencode/loop-registration.js && node --check src/source/runtime/session-activity.js && node --check src/source/runtime/session-status.js && node --check src/source/runtime/compaction.js && node --check src/source/runtime/executor.js && node --check src/source/runtime/scheduler.js && node --check src/source/runtime/goal-runtime.js && node --check src/source/runtime/goal-policy.js && node --check src/source/runtime/goal-steering.js && node --check src/source/runtime/job-workspace.js && node --check src/source/opencode2/prompt-runtime.js && node --check src/source/legacy-v1.js && node --check src/index.js && node --check scripts/install-node.mjs && node --check scripts/loopd.mjs && node --check scripts/install-test.mjs && node --check scripts/loopd-test.mjs && node --check scripts/smoke-test.mjs && node --check scripts/host-adapter-contract-test.mjs && node --check scripts/command-router-test.mjs && node --check scripts/goal-command-handlers-test.mjs && node --check scripts/loop-command-handlers-test.mjs && node --check scripts/loop-registration-test.mjs && node --check scripts/session-activity-test.mjs && node --check scripts/session-status-test.mjs && node --check scripts/compaction-runtime-test.mjs && node --check scripts/executor-runtime-test.mjs && node --check scripts/scheduler-runtime-test.mjs && node --check scripts/goal-runtime-test.mjs && node --check scripts/goal-policy-test.mjs && node --check scripts/goal-steering-test.mjs && node --check scripts/job-workspace-test.mjs && node --check scripts/v2-prompt-runtime-test.mjs && node --check scripts/v2-prompt-interval-test.mjs && node --check scripts/v2-command-runtime-test.mjs && node --check scripts/v2-command-adapter-test.mjs && node --check scripts/comprehensive-watchdog.mjs && node --check scripts/comprehensive-test.mjs && node --check scripts/host-loop-canary.mjs && node --check scripts/host-goal-steering-canary.mjs",
-    "test": "node scripts/command-router-test.mjs && node scripts/goal-command-handlers-test.mjs && node scripts/loop-command-handlers-test.mjs && node scripts/loop-registration-test.mjs && node scripts/session-activity-test.mjs && node scripts/session-status-test.mjs && node scripts/compaction-runtime-test.mjs && node scripts/executor-runtime-test.mjs && node scripts/scheduler-runtime-test.mjs && node scripts/goal-runtime-test.mjs && node scripts/goal-policy-test.mjs && node scripts/goal-steering-test.mjs && node scripts/job-workspace-test.mjs && node scripts/v2-prompt-runtime-test.mjs && node scripts/v2-prompt-interval-test.mjs && node scripts/v2-command-runtime-test.mjs && node scripts/v2-command-adapter-test.mjs && node scripts/install-test.mjs && node scripts/loopd-test.mjs && node scripts/smoke-test.mjs && node scripts/host-adapter-contract-test.mjs && node scripts/comprehensive-watchdog.mjs",
+    "check": "node --check src/source/v1.js && node --check src/source/core/args.js && node --check src/source/core/state.js && node --check src/source/core/jobs.js && node --check src/source/core/process.js && node --check src/source/opencode/sdk.js && node --check src/source/opencode/session-context.js && node --check src/source/opencode/command-router.js && node --check src/source/opencode/goal-commands.js && node --check src/source/opencode/loop-commands.js && node --check src/source/opencode/loop-registration.js && node --check src/source/runtime/session-activity.js && node --check src/source/runtime/session-status.js && node --check src/source/runtime/compaction.js && node --check src/source/runtime/executor.js && node --check src/source/runtime/scheduler.js && node --check src/source/runtime/goal-runtime.js && node --check src/source/runtime/goal-policy.js && node --check src/source/runtime/goal-steering.js && node --check src/source/runtime/job-workspace.js && node --check src/source/opencode2/prompt-runtime.js && node --check src/source/opencode2/diagnostics.js && node --check src/source/legacy-v1.js && node --check src/index.js && node --check scripts/install-node.mjs && node --check scripts/loopd.mjs && node --check scripts/install-test.mjs && node --check scripts/loopd-test.mjs && node --check scripts/smoke-test.mjs && node --check scripts/host-adapter-contract-test.mjs && node --check scripts/command-router-test.mjs && node --check scripts/goal-command-handlers-test.mjs && node --check scripts/loop-command-handlers-test.mjs && node --check scripts/loop-registration-test.mjs && node --check scripts/session-activity-test.mjs && node --check scripts/session-status-test.mjs && node --check scripts/compaction-runtime-test.mjs && node --check scripts/executor-runtime-test.mjs && node --check scripts/scheduler-runtime-test.mjs && node --check scripts/goal-runtime-test.mjs && node --check scripts/goal-policy-test.mjs && node --check scripts/goal-steering-test.mjs && node --check scripts/job-workspace-test.mjs && node --check scripts/v2-prompt-runtime-test.mjs && node --check scripts/v2-prompt-interval-test.mjs && node --check scripts/v2-command-runtime-test.mjs && node --check scripts/v2-command-adapter-test.mjs && node --check scripts/v2-diagnostics-test.mjs && node --check scripts/comprehensive-watchdog.mjs && node --check scripts/comprehensive-test.mjs && node --check scripts/host-loop-canary.mjs && node --check scripts/host-goal-steering-canary.mjs && node --check scripts/publish-workflow-test.mjs",
+    "test": "node scripts/publish-workflow-test.mjs && node scripts/command-router-test.mjs && node scripts/goal-command-handlers-test.mjs && node scripts/loop-command-handlers-test.mjs && node scripts/loop-registration-test.mjs && node scripts/session-activity-test.mjs && node scripts/session-status-test.mjs && node scripts/compaction-runtime-test.mjs && node scripts/executor-runtime-test.mjs && node scripts/scheduler-runtime-test.mjs && node scripts/goal-runtime-test.mjs && node scripts/goal-policy-test.mjs && node scripts/goal-steering-test.mjs && node scripts/job-workspace-test.mjs && node scripts/v2-prompt-runtime-test.mjs && node scripts/v2-prompt-interval-test.mjs && node scripts/v2-command-runtime-test.mjs && node scripts/v2-command-adapter-test.mjs && node scripts/v2-diagnostics-test.mjs && node scripts/install-test.mjs && node scripts/loopd-test.mjs && node scripts/smoke-test.mjs && node scripts/host-adapter-contract-test.mjs && node scripts/comprehensive-watchdog.mjs",
     "canary:host": "node scripts/host-loop-canary.mjs && node scripts/host-goal-steering-canary.mjs",
     "install:global": "node scripts/install-node.mjs",
     "pack:zip": "node scripts/make-zip.mjs"

package/scripts/publish-workflow-test.mjs

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const workflowPath = path.join(repoRoot, ".github", "workflows", "publish-npm.yml")
+const workflow = await readFile(workflowPath, "utf8")
+
+assert.match(workflow, /ref:\s*\$\{\{ github\.sha \}\}/, "publish workflow must checkout the release trigger SHA")
+assert.doesNotMatch(workflow, /ref:\s*main\b/, "publish workflow must not checkout a moving main branch")
+assert.match(workflow, /git merge-base --is-ancestor "\$GITHUB_SHA" origin\/main/, "release source must be verified against main history")
+assert.match(workflow, /COMMIT_SHA="\$GITHUB_SHA"/, "release tag must target the immutable trigger SHA")
+assert.match(workflow, /group:\s*npm-release/, "npm publication must be serialized")
+assert.match(workflow, /cancel-in-progress:\s*false/, "a newer release must not cancel an in-flight publication")
+
+const publishIndex = workflow.indexOf("npm publish --access public")
+const verifyIndex = workflow.indexOf("Verify published version is readable from npm")
+const tagIndex = workflow.indexOf("Create tag and GitHub release")
+const cleanupIndex = workflow.indexOf("Remove one-shot release branch")
+assert.ok(publishIndex >= 0 && verifyIndex > publishIndex, "npm publication must be verified after publish")
+assert.ok(tagIndex > verifyIndex, "tag/release creation must happen only after npm verification")
+assert.ok(cleanupIndex > tagIndex, "release branch cleanup must be the final release step")
+
+console.log("publish workflow tests passed")

package/scripts/v2-diagnostics-test.mjs

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict"
+import { createOpenCode2DiagnosticsRuntime, OPENCODE_LOOP_V2_HELP_TEXT } from "../src/source/opencode2/diagnostics.js"
+
+const prompts = []
+const reads = []
+const state = {
+  version: 1,
+  jobs: [{ id: "job_export", name: "exported", runCount: 2, paused: false }],
+}
+const runtime = createOpenCode2DiagnosticsRuntime({
+  prompt: async (request) => { prompts.push(request) },
+  readState: async (directory, sessionID) => {
+    reads.push([directory, sessionID])
+    return structuredClone(state)
+  },
+  runtimeVersion: "v-test",
+  runtimePlatform: "test-platform",
+})
+
+const unrelated = await runtime.onEvent({ kind: "command", action: "executed", name: "loop-status", sessionID: "ses", directory: "/work" })
+assert.equal(unrelated.handled, false)
+assert.equal(prompts.length, 0)
+
+const missing = await runtime.onEvent({ kind: "command", action: "executed", name: "loop-export", sessionID: "ses" })
+assert.equal(missing.handled, false)
+assert.equal(missing.reason, "missing-scope")
+assert.equal(prompts.length, 0)
+
+const exported = await runtime.onEvent({ kind: "command", action: "executed", name: "loop-export", sessionID: "ses", directory: "/work" })
+assert.equal(exported.handled, true)
+assert.equal(exported.accepted, true)
+assert.deepEqual(reads, [["/work", "ses"]])
+assert.equal(prompts.length, 1)
+assert.equal(prompts[0].sessionID, "ses")
+assert.equal(prompts[0].noReply, true)
+assert.match(prompts[0].text, /^OpenCode loop state export:\n```json\n/)
+assert.match(prompts[0].text, /"name": "exported"/)
+assert.match(prompts[0].text, /"runCount": 2/)
+assert.match(prompts[0].text, /\n```$/)
+
+const help = await runtime.onEvent({ kind: "command", action: "executed", name: "loop-help", sessionID: "ses", directory: "/work" })
+assert.equal(help.handled, true)
+assert.equal(help.accepted, true)
+assert.equal(reads.length, 1, "loop-help must not read or mutate Loop state")
+assert.equal(prompts.length, 2)
+assert.equal(prompts[1].noReply, true)
+assert.equal(prompts[1].text, OPENCODE_LOOP_V2_HELP_TEXT)
+assert.match(prompts[1].text, /^OpenCode Loop V2 experimental help:/)
+assert.match(prompts[1].text, /\/loop-status/)
+assert.match(prompts[1].text, /\/loop-export/)
+assert.match(prompts[1].text, /\/loop-doctor/)
+assert.match(prompts[1].text, /does not yet claim full stable-plugin parity/)
+assert.doesNotMatch(prompts[1].text, /\/loop-goal/)
+assert.doesNotMatch(prompts[1].text, /--verify/)
+
+const doctor = await runtime.onEvent({ kind: "command", action: "executed", name: "loop-doctor", sessionID: "ses", directory: "/work" })
+assert.equal(doctor.handled, true)
+assert.equal(doctor.accepted, true)
+assert.equal(reads.length, 2, "loop-doctor may read state but must not mutate it")
+assert.equal(prompts.length, 3)
+assert.equal(prompts[2].noReply, true)
+assert.match(prompts[2].text, /^OpenCode Loop V2 doctor:/)
+assert.match(prompts[2].text, /- plugin: bybrawe\.opencode-loop\.v2\.experimental/)
+assert.match(prompts[2].text, /- project directory: \/work/)
+assert.match(prompts[2].text, /- state directory:/)
+assert.match(prompts[2].text, /- active jobs: 1/)
+assert.match(prompts[2].text, /- node: v-test/)
+assert.match(prompts[2].text, /- platform: test-platform/)
+assert.match(prompts[2].text, /- full stable parity: not claimed/)
+assert.match(prompts[2].text, /- smoke test: \/loop 0s --max-runs 1/)
+
+assert.throws(() => createOpenCode2DiagnosticsRuntime({}), /requires prompt\(\)/)
+
+console.log("OpenCode 2 diagnostics contract passed")

package/scripts/v2-plugin-sentinel-test.mjs

@@ -30,6 +30,9 @@ assert.deepEqual(Object.keys(OPENCODE_LOOP_V2_COMMANDS), [
   "loop-clear",
   "loop-status",
   "loop-now",
+  "loop-export",
+  "loop-help",
+  "loop-doctor",
 ])
 assert.deepEqual(
   parseOpenCode2LoopCommandText(`${OPENCODE_LOOP_V2_COMMANDS["loop-now"].template}\n\nsecond`),

package/src/source/opencode2/commands.js

@@ -31,6 +31,18 @@ export const OPENCODE_LOOP_V2_COMMANDS = Object.freeze({
     description: "Run matching OpenCode Loop jobs on the next idle boundary.",
     template: "OpenCode Loop run-now command handled locally. Reply exactly: OK.",
   }),
+  "loop-export": Object.freeze({
+    description: "Export OpenCode Loop state for the current session.",
+    template: "OpenCode Loop export command handled locally. Reply exactly: OK.",
+  }),
+  "loop-help": Object.freeze({
+    description: "Show the experimental OpenCode 2 Loop command help.",
+    template: "OpenCode Loop help command handled locally. Reply exactly: OK.",
+  }),
+  "loop-doctor": Object.freeze({
+    description: "Show experimental OpenCode 2 Loop diagnostics.",
+    template: "OpenCode Loop doctor command handled locally. Reply exactly: OK.",
+  }),
 })
 
 export function registerOpenCode2LoopCommands(draft) {

package/src/source/opencode2/diagnostics.js

@@ -0,0 +1,80 @@
+import { readState as defaultReadState, stateDir } from "../core/state.js"
+
+export const OPENCODE_LOOP_V2_HELP_TEXT = [
+  "OpenCode Loop V2 experimental help:",
+  "/loop 0s --max-runs 2 <prompt>                  autonomous prompt loop",
+  "/loop 5m --no-now --name later --multi <prompt> delayed named prompt loop",
+  "/loop 0s --command /review                       slash-command loop when the host exposes session.command",
+  "/loop-status                                      show current Loop jobs",
+  "/loop-now [target]                                run matching jobs on the next idle boundary",
+  "/loop-pause [target] | /loop-resume [target]      pause or resume jobs",
+  "/loop-stop [target] | /loop-remove [target]       remove matching jobs",
+  "/loop-clear                                       clear all jobs",
+  "/loop-export                                      export current session Loop state as JSON",
+  "/loop-help                                        show this experimental V2 help",
+  "/loop-doctor                                      show local V2 diagnostics",
+  "Experimental V2 does not yet claim full stable-plugin parity; unsupported options fail closed.",
+].join("\n")
+
+function scopeFrom(event) {
+  const directory = typeof event?.directory === "string" ? event.directory.trim() : ""
+  const sessionID = String(event?.sessionID || "").trim()
+  if (!directory || !sessionID) return undefined
+  return { directory, sessionID }
+}
+
+export function createOpenCode2DiagnosticsRuntime(options = {}) {
+  if (typeof options.prompt !== "function") throw new TypeError("V2 diagnostics runtime requires prompt()")
+  const readState = typeof options.readState === "function" ? options.readState : defaultReadState
+  const runtimeVersion = options.runtimeVersion || process.version
+  const runtimePlatform = options.runtimePlatform || process.platform
+
+  async function exportState(event) {
+    const scope = scopeFrom(event)
+    if (!scope) return { handled: false, reason: "missing-scope" }
+    const state = await readState(scope.directory, scope.sessionID)
+    const text = `OpenCode loop state export:\n\`\`\`json\n${JSON.stringify(state, null, 2)}\n\`\`\``
+    const request = { sessionID: scope.sessionID, text, noReply: true }
+    await options.prompt(request)
+    return { handled: true, accepted: true, state, request }
+  }
+
+  async function help(event) {
+    const scope = scopeFrom(event)
+    if (!scope) return { handled: false, reason: "missing-scope" }
+    const request = { sessionID: scope.sessionID, text: OPENCODE_LOOP_V2_HELP_TEXT, noReply: true }
+    await options.prompt(request)
+    return { handled: true, accepted: true, request }
+  }
+
+  async function doctor(event) {
+    const scope = scopeFrom(event)
+    if (!scope) return { handled: false, reason: "missing-scope" }
+    const state = await readState(scope.directory, scope.sessionID)
+    const text = [
+      "OpenCode Loop V2 doctor:",
+      "- plugin: bybrawe.opencode-loop.v2.experimental",
+      `- project directory: ${scope.directory}`,
+      `- state directory: ${stateDir(scope.directory)}`,
+      `- active jobs: ${(state.jobs || []).length}`,
+      `- node: ${runtimeVersion}`,
+      `- platform: ${runtimePlatform}`,
+      "- full stable parity: not claimed",
+      "- smoke test: /loop 0s --max-runs 1 continue the current task",
+    ].join("\n")
+    const request = { sessionID: scope.sessionID, text, noReply: true }
+    await options.prompt(request)
+    return { handled: true, accepted: true, state, request }
+  }
+
+  async function onEvent(event) {
+    if (event?.kind === "command" && event?.action === "executed") {
+      if (event?.name === "loop-export") return await exportState(event)
+      if (event?.name === "loop-help") return await help(event)
+      if (event?.name === "loop-doctor") return await doctor(event)
+    }
+    return { handled: false }
+  }
+
+  return Object.freeze({ onEvent, exportState, help, doctor })
+}

package/src/source/opencode2/experimental.js

@@ -1,5 +1,6 @@
 import { inspectOpenCode2Context } from "./capabilities.js"
 import { OPENCODE_LOOP_V2_COMMANDS, registerOpenCode2LoopCommands } from "./commands.js"
+import { createOpenCode2DiagnosticsRuntime } from "./diagnostics.js"
 import { createOpenCode2PromptRuntime } from "./prompt-runtime.js"
 import { createOpenCode2RuntimeAdapter } from "./runtime-adapter.js"
 
@@ -21,12 +22,20 @@ export const OpenCodeLoopV2ExperimentalPlugin = {
     }
 
     let promptRuntime
-    const onRuntimeEvent = async (event) => promptRuntime?.onEvent(event)
+    let diagnosticsRuntime
+    const onRuntimeEvent = async (event) => {
+      const promptResult = await promptRuntime?.onEvent(event)
+      if (promptResult?.handled) return promptResult
+      return await diagnosticsRuntime?.onEvent(event) ?? promptResult
+    }
     const runtime = createOpenCode2RuntimeAdapter(ctx, { onEvent: onRuntimeEvent })
     promptRuntime = createOpenCode2PromptRuntime({
       prompt: (request) => runtime.prompt(request),
       command: capabilities.sessionCommand ? (request) => runtime.command(request) : undefined,
     })
+    diagnosticsRuntime = createOpenCode2DiagnosticsRuntime({
+      prompt: (request) => runtime.prompt(request),
+    })
 
     try {
       await runtime.start()