@nihaopaul/opencode-agent-controlplane 0.0.0-stage → 0.1.7

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# Agent Control Plane OpenCode plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connects a local OpenCode instance to an Agent Control Plane without a second
+tunnel implementation. The plugin invokes the released `node-tunnel` helper in
+`connect` mode. It does **not** restart OpenCode or manage the local OpenCode
+version.
+
+## Install
+
+```sh
+opencode plugin add @nihaopaul/opencode-agent-controlplane@0.1.7
+```
+
+Point it at a short enrol link with either an environment variable:
+
+```sh
+export AGENT_CONTROLPLANE_ENROLL_URL='https://control.example.com/_/enroll/7K3M9Q2B'
+opencode
+```
+
+or an OpenCode plugin entry:
+
+```json
+{
+  "plugin": [
+    [
+      "@nihaopaul/opencode-agent-controlplane@0.1.7",
+      { "enroll_url": "https://control.example.com/_/enroll/7K3M9Q2B" }
+    ]
+  ]
+}
+```
+
+The helper registers, waits for approval in the control plane, stores its secret
+under `$XDG_STATE_HOME/opencode`, enrols a certificate, and runs the tunnel. It
+does not start, stop, upgrade, or restart OpenCode.
+
+Options:
+
+| Option | Environment | Default |
+| --- | --- | --- |
+| `enroll_url` | `AGENT_CONTROLPLANE_ENROLL_URL` | required |
+| `node_tunnel` | `AGENT_CONTROLPLANE_NODE_TUNNEL` | `node-tunnel` on `PATH` |
+| - | `AGENT_CONTROLPLANE_LOG` | `$XDG_STATE_HOME/opencode/agent-controlplane.log` |
+
+Plain HTTP enrol URLs are accepted only for loopback. The helper log is created
+with mode `0600`.
+
+## Requirements
+
+- the released `node-tunnel` binary on `PATH`, or an explicit `node_tunnel`;
+- Node.js 22.14 or newer;
+- outbound access to the control plane, directly or through the standard proxy
+  variables supported by `node-tunnel`.
+
+## Publishing
+
+This package is designed to publish with **npm trusted publishing (OIDC)** and
+no long-lived `NPM_TOKEN`.
+
+On npmjs.com, open the package settings and add a trusted publisher:
+
+- **Organization or user:** `nihaopaul`
+- **Repository:** `agent-controlplane`
+- **Workflow filename:** `publish-plugin.yml`
+- **Allowed actions:** `npm publish`
+- **Environment name:** optional; leave empty unless you add one to the workflow
+
+Then push a `plugin-v*` tag. `.github/workflows/publish-plugin.yml` uses
+`id-token: write` and runs `npm publish --access public` without a token.
+
+The repository is private, so npm cannot generate provenance attestations even
+with trusted publishing. Authentication is still OIDC-bound to this repository
+and workflow. If provenance is required, publish from a public source mirror.
+
+The package name is `@nihaopaul/opencode-agent-controlplane`; change the name in
+`package.json`, the workflow, and the trusted-publisher configuration together.

package/index.js

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+import { chmodSync, closeSync, mkdirSync, openSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const DEFAULT_BINARY = "node-tunnel";
+const ENV_URL = "AGENT_CONTROLPLANE_ENROLL_URL";
+const ENV_BINARY = "AGENT_CONTROLPLANE_NODE_TUNNEL";
+const ENV_LOG = "AGENT_CONTROLPLANE_LOG";
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+const ENROLL_PATH = /^\/_\/(?:enroll\/[A-Za-z0-9-]{1,64}|connect)$/;
+
+/**
+ * Validate a short enrol link (or the legacy connect link) before it is passed
+ * to the helper. Plain HTTP is only accepted for loopback development.
+ */
+export function validateEnrollUrl(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("enrol URL is required");
+  }
+  let url;
+  try {
+    url = new URL(value.trim());
+  } catch {
+    throw new Error("enrol URL is not a valid URL");
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error("enrol URL must use https://");
+  }
+  if (url.protocol !== "https:" && !LOOPBACK.has(url.hostname)) {
+    throw new Error("plain HTTP enrol URLs are only allowed for loopback");
+  }
+  if (url.username || url.password) {
+    throw new Error("enrol URL must not contain credentials");
+  }
+  if (!ENROLL_PATH.test(url.pathname)) {
+    throw new Error("enrol URL must be /_/enroll/<code> or /_/connect");
+  }
+  return url.toString();
+}
+
+export function enrollUrlFrom(options = {}, env = process.env) {
+  const value = options?.enroll_url ?? options?.enrollUrl ?? env[ENV_URL];
+  return value ? validateEnrollUrl(value) : null;
+}
+
+export function logPath(env = process.env) {
+  if (env[ENV_LOG]) return env[ENV_LOG];
+  const stateHome = env.XDG_STATE_HOME || join(env.HOME || homedir(), ".local", "state");
+  return join(stateHome, "opencode", "agent-controlplane.log");
+}
+
+function binaryFrom(options = {}, env = process.env) {
+  const configured = options?.node_tunnel ?? options?.binary ?? env[ENV_BINARY];
+  return typeof configured === "string" && configured.trim() ? configured.trim() : DEFAULT_BINARY;
+}
+
+/**
+ * Start `node-tunnel connect <url>` in the background. The helper owns
+ * registration, approval, secret storage, enrolment, and the tunnel. The plugin
+ * never restarts OpenCode and never manages the local OpenCode version.
+ */
+export function startHelper({
+  url,
+  binary = DEFAULT_BINARY,
+  logFile = logPath(),
+  env = process.env,
+  spawnImpl = spawn,
+} = {}) {
+  mkdirSync(dirname(logFile), { recursive: true, mode: 0o700 });
+  const fd = openSync(logFile, "a", 0o600);
+  let child;
+  try {
+    try {
+      chmodSync(logFile, 0o600);
+    } catch {
+      // The file may be on a filesystem without POSIX modes.
+    }
+    child = spawnImpl(binary, ["connect", url], {
+      detached: false,
+      stdio: ["ignore", fd, fd],
+      env: { ...env, RUST_LOG: env.RUST_LOG || "info" },
+      windowsHide: true,
+    });
+  } finally {
+    closeSync(fd);
+  }
+  child.on?.("error", (error) => {
+    console.error(`[agent-controlplane] failed to start ${binary}: ${error.message}`);
+  });
+  return child;
+}
+
+export function stopHelper(child) {
+  if (!child || child.killed) return;
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    // The process may already be gone.
+  }
+}
+
+let activeChild = null;
+
+export const AgentControlPlane = async (_input, options = {}) => {
+  try {
+    const url = enrollUrlFrom(options);
+    if (!url) return {};
+    if (activeChild && !activeChild.killed) {
+      console.error("[agent-controlplane] helper already running; leaving it in place");
+      return {};
+    }
+    const child = startHelper({ url, binary: binaryFrom(options) });
+    activeChild = child;
+    return {
+      dispose: async () => {
+        if (activeChild === child) activeChild = null;
+        stopHelper(child);
+      },
+    };
+  } catch (error) {
+    console.error(`[agent-controlplane] ${error instanceof Error ? error.message : String(error)}`);
+    return {};
+  }
+};
+
+export default AgentControlPlane;

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@nihaopaul/opencode-agent-controlplane",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.7",
+  "description": "Connect a local OpenCode instance to an Agent Control Plane by invoking the released node-tunnel helper.",
+  "type": "module",
+  "main": "./index.js",
+  "exports": "./index.js",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nihaopaul/agent-controlplane.git",
+    "directory": "plugin"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.14"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "pack:check": "npm pack --dry-run"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}