@webgrow/skillhub 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# SkillHub MVP
+
+SkillHub is a Convex-first control plane for running Codex-backed loops and
+skills.
+
+The current product direction is:
+
+- `convex/` stores skills, loops, runs, events, host actions, leases, and logs.
+- `dashboard/` is the React/Vite realtime dashboard.
+- `bridge/` is the worker harness that claims Convex actions and runs Codex.
+- `src/cli.mjs` and `src/cloud-catalog.mjs` expose the small user-facing CLI
+  and MCP surface.
+
+The old local JSON database, vanilla dashboard, and local API server prototype
+have been removed. Useful feature ideas from that system are preserved in
+`docs/legacy-system-feature-carryover.md`.
+
+## Quick Start
+
+Connect SkillHub to Codex:
+
+```bash
+npx @webgrow/skillhub connect
+```
+
+After connecting, open Codex and ask:
+
+```txt
+Show my SkillHub options.
+```
+
+Run an option from Codex:
+
+```txt
+Run option 1.
+```
+
+Start Convex:
+
+```bash
+npm run convex:dev
+```
+
+Start the dashboard:
+
+```bash
+npm run dashboard:dev
+```
+
+List runnable options from the CLI:
+
+```bash
+npm run options
+```
+
+Run a loop or skill:
+
+```bash
+node src/cli.mjs run 1
+```
+
+Start the local bridge worker:
+
+```bash
+npm run bridge:start
+```
+
+Check recent run status:
+
+```bash
+npm run status
+```
+
+## Developer Diagnostics
+
+Process one pending action through the internal harness:
+
+```bash
+npm run harness:once
+```
+
+Use the doctor when setting up real Codex CLI execution:
+
+```bash
+npm run harness:doctor -- --mode codex-cli --codex-smoke
+```
+
+## Main Commands
+
+```bash
+npm run connect
+npm run bridge:start
+npm run status
+npm run dashboard:dev
+npm run dashboard:build
+npm run convex:dev
+npm run convex:deploy
+npm run harness
+npm run harness:once
+npm run harness:doctor
+npm run options
+npm run choose
+node src/cli.mjs mcp serve
+```
+
+## Docs
+
+- `docs/codex-user-onboarding-implementation-guide.md`: future user install and
+  Codex onboarding plan.
+- `docs/convex-bridge-plan.md`: Convex bridge architecture and deployment
+  direction.
+- `docs/options-picker.md`: CLI and MCP option picker behavior.
+- `docs/legacy-system-feature-carryover.md`: old prototype features worth
+  rebuilding later if they still matter.

package/bridge/.env.example

@@ -0,0 +1,14 @@
+CONVEX_URL=https://your-deployment.convex.cloud
+SKILLHUB_WORKER_NAME=skillhub-local-worker
+SKILLHUB_HARNESS_MODE=codex-cli
+SKILLHUB_CAPABILITIES=codex.cli,codex.create_goal,codex.create_heartbeat,codex.create_thread,codex.notify_user
+SKILLHUB_POLL_MS=1500
+SKILLHUB_LEASE_MS=60000
+
+CODEX_COMMAND=codex
+CODEX_WORKDIR=C:\Users\you\Documents\code\skillhub-mvp
+CODEX_ARGS_JSON=["--ask-for-approval","never","exec","--sandbox","workspace-write","--json"]
+CODEX_TIMEOUT_MS=600000
+
+# For cloud workers, prefer a worker-scoped secret rather than committing auth.
+# CODEX_API_KEY=

package/bridge/README.md

@@ -0,0 +1,74 @@
+# Bridge Harness
+
+The harness is the external worker that connects SkillHub runs to Codex. It should not live inside the dashboard process.
+
+## Runtime Loop
+
+1. Start with `CONVEX_URL` and a worker identity.
+2. Call `bridge.registerSession` once and keep the returned session id.
+3. Expire stale leases so abandoned work can return to the queue.
+4. Generate a fresh `claimId`.
+5. Call `bridge.claimNextAction` with capabilities such as `["codex.cli"]` or `["*"]`.
+6. If no action is returned, sleep briefly and poll again.
+7. For claimed work, send status through `bridge.emitLog` and extend the lease with `bridge.heartbeatLease`.
+8. Execute Codex through the selected adapter.
+9. Finish with `bridge.completeAction`, `bridge.failAction`, or `bridge.releaseAction`.
+
+## Required Environment
+
+- `CONVEX_URL`: Convex deployment URL.
+- `SKILLHUB_WORKER_NAME`: stable worker label for logs and leases.
+- `SKILLHUB_HARNESS_MODE`: `dry-run` or `codex-cli`.
+- `CODEX_HOME`: Codex configuration directory, when running the CLI with saved auth.
+- `CODEX_API_KEY`: optional worker secret for `codex exec` automation.
+- `CODEX_COMMAND`: Codex executable path or command name. Defaults to `codex`.
+- `CODEX_WORKDIR`: git repository where Codex should run. Defaults to this process cwd.
+- `CODEX_ARGS_JSON`: JSON array of base Codex CLI args.
+
+## Adapters
+
+The first adapter defaults to `dry-run`, which proves Convex claiming, heartbeats, logs, and completion without starting an external process.
+
+Use `codex-cli` mode when the worker environment has Codex installed:
+
+```bash
+npm run harness -- --mode codex-cli
+```
+
+Set `CODEX_ARGS_JSON` to the base Codex CLI arguments. The harness appends the SkillHub action prompt unless `CODEX_STDIN_PROMPT=true`.
+
+Recommended local starting point:
+
+```bash
+CODEX_ARGS_JSON='["--ask-for-approval","never","exec","--sandbox","workspace-write","--json"]'
+```
+
+Use `codex login` once for local saved auth, or provide `CODEX_API_KEY` as a worker-only secret in a hosted worker. Do not commit either credential.
+
+## Doctor
+
+Run the doctor before switching the worker to real Codex execution:
+
+```bash
+npm run harness:doctor -- --mode codex-cli
+```
+
+The doctor checks Convex connectivity, worker capabilities, `CODEX_ARGS_JSON`, `CODEX_WORKDIR`, git repo status, and whether the Codex command is runnable. After those checks pass, run the optional real Codex smoke test:
+
+```bash
+npm run harness:doctor -- --mode codex-cli --codex-smoke
+```
+
+The smoke test starts a tiny `codex exec` run, so use it only in an environment where Codex auth and billing are intentionally configured.
+
+Keep adapters small. The durable state belongs in Convex, and the harness should be replaceable.
+
+## Local Commands
+
+```bash
+npm run harness:doctor
+npm run harness:once
+npm run harness -- --dry-run
+```
+
+The same command can run as a Railway worker start command after environment variables are configured.

package/bridge/adapters.mjs

@@ -0,0 +1,209 @@
+import { spawn } from "node:child_process";
+import process from "node:process";
+import { defaultCodexArgs, getRuntimeConfig } from "../src/config.mjs";
+
+export const defaultCapabilities = [
+  "codex.cli",
+  "codex.create_goal",
+  "codex.create_heartbeat",
+  "codex.create_thread",
+  "codex.notify_user",
+];
+
+export async function executeAction(action, options) {
+  const mode = options.mode ?? "dry-run";
+
+  if (mode === "dry-run") {
+    return await runDryAdapter(action, options);
+  }
+
+  if (mode === "codex-cli") {
+    return await runCodexCliAdapter(action, options);
+  }
+
+  throw new Error(`Unknown harness adapter mode: ${mode}`);
+}
+
+async function runDryAdapter(action, { emitLog }) {
+  await emitLog("info", "Dry-run adapter accepted host action.", {
+    actionId: action._id,
+    actionType: action.actionType,
+  });
+
+  return {
+    source: "skillhub-bridge",
+    mode: "dry-run",
+    actionId: action._id,
+    actionType: action.actionType,
+    title: action.title,
+    summary: "No external Codex process was started.",
+  };
+}
+
+async function runCodexCliAdapter(action, { emitLog, signal }) {
+  const { args, command, cwd, passPromptOnStdin, timeoutMs } = getCodexCliSettings();
+  const prompt = buildCodexPrompt(action);
+  const finalArgs = passPromptOnStdin ? args : [...args, prompt];
+
+  if (!args.length) {
+    throw new Error(
+      "CODEX_ARGS_JSON must be a JSON array when SKILLHUB_HARNESS_MODE=codex-cli.",
+    );
+  }
+
+  await emitLog("info", "Starting Codex CLI adapter.", {
+    command,
+    args: redactArgs(finalArgs),
+    cwd,
+  });
+
+  return await spawnWithLogs({
+    command,
+    args: finalArgs,
+    cwd,
+    prompt: passPromptOnStdin ? prompt : "",
+    timeoutMs,
+    emitLog,
+    signal,
+  });
+}
+
+export function getCodexCliSettings(env = process.env) {
+  const config = getRuntimeConfig(env);
+  return {
+    command: env.CODEX_COMMAND || config.codexCommand || "codex",
+    args: parseJsonArrayEnv("CODEX_ARGS_JSON", env) || config.codexArgs || defaultCodexArgs,
+    cwd: env.CODEX_WORKDIR || config.codexWorkdir || process.cwd(),
+    timeoutMs: Number(env.CODEX_TIMEOUT_MS || 10 * 60 * 1000),
+    passPromptOnStdin: env.CODEX_STDIN_PROMPT === "true",
+  };
+}
+
+function buildCodexPrompt(action) {
+  return [
+    `SkillHub host action: ${action._id}`,
+    `Title: ${action.title}`,
+    `Type: ${action.actionType}`,
+    `Run: ${action.runId}`,
+    action.nodeId ? `Node: ${action.nodeId}` : null,
+    "",
+    "Payload:",
+    JSON.stringify(action.payload ?? {}, null, 2),
+    "",
+    "Codex tool hint:",
+    JSON.stringify(action.codexTool ?? {}, null, 2),
+    "",
+    "Return a concise structured result. Do not mark the action complete yourself; the SkillHub bridge will write completion to Convex.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function parseJsonArrayEnv(name, env = process.env) {
+  const raw = env[name];
+  if (!raw) return null;
+  const parsed = JSON.parse(raw);
+  if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string")) {
+    throw new Error(`${name} must be a JSON array of strings.`);
+  }
+  return parsed;
+}
+
+async function spawnWithLogs({
+  command,
+  args,
+  cwd,
+  prompt,
+  timeoutMs,
+  emitLog,
+  signal,
+}) {
+  const startedAt = Date.now();
+  const stdout = [];
+  const stderr = [];
+  const pendingLogs = [];
+
+  const child = spawn(command, args, {
+    cwd,
+    env: process.env,
+    shell: false,
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+  });
+
+  const timeout = setTimeout(() => {
+    child.kill("SIGTERM");
+  }, timeoutMs);
+
+  const abort = () => child.kill("SIGTERM");
+  signal?.addEventListener("abort", abort, { once: true });
+
+  child.stdout.on("data", (chunk) => {
+    const text = chunk.toString();
+    stdout.push(text);
+    pendingLogs.push(emitLog("info", trimChunk(text), { stream: "stdout" }));
+  });
+
+  child.stderr.on("data", (chunk) => {
+    const text = chunk.toString();
+    stderr.push(text);
+    pendingLogs.push(emitLog("warn", trimChunk(text), { stream: "stderr" }));
+  });
+
+  if (prompt) {
+    child.stdin.end(prompt);
+  } else {
+    child.stdin.end();
+  }
+
+  const exit = await new Promise((resolve, reject) => {
+    child.on("error", reject);
+    child.on("close", (code, closeSignal) => resolve({ code, signal: closeSignal }));
+  });
+
+  clearTimeout(timeout);
+  signal?.removeEventListener("abort", abort);
+  await Promise.allSettled(pendingLogs);
+
+  const result = {
+    source: "skillhub-bridge",
+    mode: "codex-cli",
+    command,
+    args: redactArgs(args),
+    exitCode: exit.code,
+    signal: exit.signal,
+    durationMs: Date.now() - startedAt,
+    stdoutTail: tail(stdout.join("")),
+    stderrTail: tail(stderr.join("")),
+  };
+
+  if (exit.code !== 0) {
+    const reason = exit.signal
+      ? `Codex CLI stopped by signal ${exit.signal}`
+      : `Codex CLI exited with code ${exit.code}`;
+    const error = new Error(reason);
+    error.result = result;
+    throw error;
+  }
+
+  return result;
+}
+
+function trimChunk(text) {
+  const normalized = text.replace(/\r/g, "").trim();
+  if (normalized.length <= 1800) return normalized;
+  return `${normalized.slice(0, 1800)}...`;
+}
+
+function tail(text) {
+  const normalized = text.replace(/\r/g, "").trim();
+  if (normalized.length <= 4000) return normalized;
+  return normalized.slice(-4000);
+}
+
+export function redactArgs(args) {
+  return args.map((arg) => {
+    if (/key|token|secret|password/i.test(arg)) return "<redacted>";
+    return arg.length > 180 ? `${arg.slice(0, 180)}...` : arg;
+  });
+}

package/bridge/convex-functions.mjs

@@ -0,0 +1,13 @@
+import { makeFunctionReference } from "convex/server";
+
+export const bridgeFunctions = {
+  claimNextAction: makeFunctionReference("bridge:claimNextAction"),
+  completeAction: makeFunctionReference("bridge:completeAction"),
+  emitLog: makeFunctionReference("bridge:emitLog"),
+  expireStaleLeases: makeFunctionReference("bridge:expireStaleLeases"),
+  failAction: makeFunctionReference("bridge:failAction"),
+  heartbeatLease: makeFunctionReference("bridge:heartbeatLease"),
+  markApplying: makeFunctionReference("bridge:markApplying"),
+  registerSession: makeFunctionReference("bridge:registerSession"),
+  releaseAction: makeFunctionReference("bridge:releaseAction"),
+};