@webgrow/skillhub 0.1.0

package/bridge/doctor.mjs

@@ -0,0 +1,448 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { access, stat } from "node:fs/promises";
+import process from "node:process";
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import dotenv from "dotenv";
+import { getCodexCliSettings, redactArgs } from "./adapters.mjs";
+import { getRuntimeConfig } from "../src/config.mjs";
+
+dotenv.config({ path: ".env", quiet: true });
+dotenv.config({ path: "bridge/.env.local", quiet: true });
+
+const checks = [];
+const options = parseArgs(process.argv.slice(2));
+const runtimeConfig = getRuntimeConfig();
+const mode = options.mode || runtimeConfig.bridgeMode || process.env.SKILLHUB_HARNESS_MODE || "dry-run";
+const convexUrl = options.convexUrl || runtimeConfig.convexUrl || process.env.CONVEX_URL;
+
+await main().catch((error) => {
+  fail("doctor", error instanceof Error ? error.message : String(error));
+  reportAndExit();
+});
+
+async function main() {
+  pass("mode", mode);
+
+  if (!["dry-run", "codex-cli"].includes(mode)) {
+    fail("SKILLHUB_HARNESS_MODE", `Unsupported mode: ${mode}`);
+  }
+
+  await checkConvex();
+  checkCapabilities();
+
+  if (mode !== "codex-cli") {
+    warn(
+      "codex-cli",
+      "Skipped because the harness mode is dry-run. Use --mode codex-cli to check real Codex execution.",
+    );
+    return reportAndExit();
+  }
+
+  const settings = checkCodexSettings();
+  if (settings) {
+    await checkWorkdir(settings);
+    await checkCodexCommand(settings);
+    await maybeRunCodexSmoke(settings);
+  }
+
+  return reportAndExit();
+}
+
+async function checkConvex() {
+  if (options.skipConvex) {
+    skip("CONVEX_URL", "Convex check skipped by --skip-convex.");
+    return;
+  }
+
+  if (!convexUrl) {
+    fail("CONVEX_URL", "Missing Convex deployment URL.");
+    return;
+  }
+
+  pass("CONVEX_URL", redactUrl(convexUrl));
+
+  try {
+    const client = new ConvexHttpClient(convexUrl);
+    if (process.env.CONVEX_AUTH_TOKEN) {
+      client.setAuth(process.env.CONVEX_AUTH_TOKEN);
+    }
+
+    const listActive = makeFunctionReference("runs:listActive");
+    const runs = await client.query(listActive, { limit: 1 });
+    pass("Convex connectivity", `runs.listActive returned ${runs.length} row(s).`);
+  } catch (error) {
+    fail(
+      "Convex connectivity",
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+}
+
+function checkCapabilities() {
+  const capabilities = parseCapabilities(process.env.SKILLHUB_CAPABILITIES);
+  if (!capabilities.length) {
+    warn(
+      "SKILLHUB_CAPABILITIES",
+      "Not set; harness will use its default capabilities.",
+    );
+    return;
+  }
+
+  pass("SKILLHUB_CAPABILITIES", capabilities.join(", "));
+
+  if (!capabilities.includes("*") && !capabilities.includes("codex.cli")) {
+    warn(
+      "codex.cli capability",
+      "Worker will not claim loop steps unless codex.cli or * is advertised.",
+    );
+  }
+}
+
+function checkCodexSettings() {
+  let settings;
+  try {
+    settings = getCodexCliSettings();
+  } catch (error) {
+    fail("CODEX_ARGS_JSON", error instanceof Error ? error.message : String(error));
+    return null;
+  }
+
+  pass("CODEX_COMMAND", settings.command);
+  pass("CODEX_WORKDIR", settings.cwd);
+
+  if (!Number.isFinite(settings.timeoutMs) || settings.timeoutMs <= 0) {
+    fail("CODEX_TIMEOUT_MS", "Must be a positive number of milliseconds.");
+  } else {
+    pass("CODEX_TIMEOUT_MS", `${settings.timeoutMs} ms`);
+  }
+
+  if (!settings.args.length) {
+    fail(
+      "CODEX_ARGS_JSON",
+      'Missing base args. Recommended: ["--ask-for-approval","never","exec","--sandbox","workspace-write","--json"]',
+    );
+  } else {
+    pass("CODEX_ARGS_JSON", JSON.stringify(redactArgs(settings.args)));
+  }
+
+  if (!settings.args.includes("exec")) {
+    fail("codex exec", "CODEX_ARGS_JSON must include the exec subcommand.");
+  }
+
+  if (!settings.args.includes("--json")) {
+    warn("codex --json", "Recommended so harness logs can parse event streams later.");
+  }
+
+  if (!hasFlagValue(settings.args, "--ask-for-approval", "never")) {
+    warn(
+      "approval policy",
+      "Recommended: --ask-for-approval never for non-interactive workers.",
+    );
+  }
+
+  if (!settings.args.includes("--sandbox")) {
+    warn(
+      "sandbox",
+      "No explicit --sandbox flag. Codex exec defaults may be read-only.",
+    );
+  }
+
+  if (settings.passPromptOnStdin && !settings.args.includes("-")) {
+    warn(
+      "CODEX_STDIN_PROMPT",
+      "When true, CODEX_ARGS_JSON should usually include '-' for codex exec stdin prompts.",
+    );
+  }
+
+  return settings;
+}
+
+async function checkWorkdir(settings) {
+  try {
+    const info = await stat(settings.cwd);
+    if (!info.isDirectory()) {
+      fail("CODEX_WORKDIR", "Path exists but is not a directory.");
+      return;
+    }
+    await access(settings.cwd);
+    pass("CODEX_WORKDIR exists", settings.cwd);
+  } catch (error) {
+    fail("CODEX_WORKDIR exists", error instanceof Error ? error.message : String(error));
+    return;
+  }
+
+  const skipGitCheck = settings.args.includes("--skip-git-repo-check");
+  const git = await spawnCapture({
+    command: "git",
+    args: ["-C", settings.cwd, "rev-parse", "--is-inside-work-tree"],
+    timeoutMs: 10_000,
+  });
+
+  if (git.code === 0 && git.stdout.trim() === "true") {
+    pass("git repository", "Workdir is inside a git repository.");
+    return;
+  }
+
+  if (skipGitCheck) {
+    warn(
+      "git repository",
+      "Workdir did not verify as git, but --skip-git-repo-check is configured.",
+    );
+  } else {
+    fail(
+      "git repository",
+      "Codex exec requires a git repository unless --skip-git-repo-check is set.",
+    );
+  }
+}
+
+async function checkCodexCommand(settings) {
+  const version = await spawnCapture({
+    command: settings.command,
+    args: ["--version"],
+    cwd: settings.cwd,
+    timeoutMs: 20_000,
+  });
+
+  if (version.error) {
+    fail("Codex command", version.error);
+    return;
+  }
+
+  if (version.code === 0) {
+    pass("Codex command", `${settings.command} ${version.stdout.trim()}`.trim());
+    return;
+  }
+
+  fail(
+    "Codex command",
+    formatCommandFailure(version, `${settings.command} --version`),
+  );
+}
+
+async function maybeRunCodexSmoke(settings) {
+  if (!options.codexSmoke) {
+    warn(
+      "Codex smoke",
+      "Skipped. Run npm run harness:doctor -- --mode codex-cli --codex-smoke after the command check passes.",
+    );
+    return;
+  }
+
+  if (hasFailures()) {
+    skip("Codex smoke", "Skipped because earlier checks failed.");
+    return;
+  }
+
+  const prompt =
+    "SkillHub harness doctor smoke test. Reply in one short sentence that Codex exec is reachable. Do not edit files.";
+  const args = settings.passPromptOnStdin ? settings.args : [...settings.args, prompt];
+  const smoke = await spawnCapture({
+    command: settings.command,
+    args,
+    cwd: settings.cwd,
+    input: settings.passPromptOnStdin ? prompt : "",
+    timeoutMs: Math.min(settings.timeoutMs, options.timeoutMs || 120_000),
+  });
+
+  if (smoke.error) {
+    fail("Codex smoke", smoke.error);
+    return;
+  }
+
+  if (smoke.code === 0) {
+    pass("Codex smoke", tail(smoke.stdout || smoke.stderr || "completed"));
+    return;
+  }
+
+  fail("Codex smoke", formatCommandFailure(smoke, "codex exec smoke"));
+}
+
+function parseArgs(args) {
+  const parsed = {
+    codexSmoke: false,
+    convexUrl: "",
+    json: false,
+    mode: "",
+    skipConvex: false,
+    timeoutMs: 0,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--codex-smoke") parsed.codexSmoke = true;
+    else if (arg === "--convex-url") parsed.convexUrl = args[++index] ?? "";
+    else if (arg === "--json") parsed.json = true;
+    else if (arg === "--mode") parsed.mode = args[++index] ?? "";
+    else if (arg === "--skip-convex") parsed.skipConvex = true;
+    else if (arg === "--timeout-ms") parsed.timeoutMs = Number(args[++index] ?? 0);
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return parsed;
+}
+
+function parseCapabilities(value) {
+  if (!value) return [];
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function hasFlagValue(args, flag, value) {
+  const index = args.indexOf(flag);
+  return index >= 0 && args[index + 1] === value;
+}
+
+function pass(name, detail = "") {
+  checks.push({ status: "pass", name, detail });
+}
+
+function warn(name, detail = "") {
+  checks.push({ status: "warn", name, detail });
+}
+
+function fail(name, detail = "") {
+  checks.push({ status: "fail", name, detail });
+}
+
+function skip(name, detail = "") {
+  checks.push({ status: "skip", name, detail });
+}
+
+function hasFailures() {
+  return checks.some((check) => check.status === "fail");
+}
+
+function reportAndExit() {
+  const failures = checks.filter((check) => check.status === "fail").length;
+  const warnings = checks.filter((check) => check.status === "warn").length;
+
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: failures === 0,
+          failures,
+          warnings,
+          mode,
+          checks,
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.log("SkillHub harness doctor");
+    console.log(`Mode: ${mode}`);
+    console.log("");
+    for (const check of checks) {
+      const label = check.status.toUpperCase().padEnd(4, " ");
+      const detail = check.detail ? ` - ${check.detail}` : "";
+      console.log(`${label} ${check.name}${detail}`);
+    }
+    console.log("");
+    console.log(
+      failures === 0
+        ? `Result: ready with ${warnings} warning(s).`
+        : `Result: blocked by ${failures} failure(s), ${warnings} warning(s).`,
+    );
+  }
+
+  process.exitCode = failures === 0 ? 0 : 1;
+}
+
+async function spawnCapture({
+  command,
+  args,
+  cwd = process.cwd(),
+  env = process.env,
+  input = "",
+  timeoutMs = 30_000,
+}) {
+  return await new Promise((resolve) => {
+    let child;
+    let settled = false;
+    const stdout = [];
+    const stderr = [];
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve({
+        stdout: stdout.join(""),
+        stderr: stderr.join(""),
+        ...result,
+      });
+    };
+
+    try {
+      child = spawn(command, args, {
+        cwd,
+        env,
+        shell: false,
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+      });
+    } catch (error) {
+      finish({ code: null, signal: null, error: formatError(error) });
+      return;
+    }
+
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({
+        code: null,
+        signal: "SIGTERM",
+        error: `Timed out after ${timeoutMs} ms.`,
+      });
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => stdout.push(chunk.toString()));
+    child.stderr.on("data", (chunk) => stderr.push(chunk.toString()));
+    child.on("error", (error) => {
+      clearTimeout(timeout);
+      finish({ code: null, signal: null, error: formatError(error) });
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timeout);
+      finish({ code, signal });
+    });
+
+    child.stdin.end(input);
+  });
+}
+
+function formatCommandFailure(result, command) {
+  return [
+    `${command} failed`,
+    result.code !== null && result.code !== undefined ? `exit=${result.code}` : null,
+    result.signal ? `signal=${result.signal}` : null,
+    result.stderr ? `stderr=${tail(result.stderr)}` : null,
+    result.stdout && !result.stderr ? `stdout=${tail(result.stdout)}` : null,
+  ]
+    .filter(Boolean)
+    .join("; ");
+}
+
+function formatError(error) {
+  if (typeof error === "string") return error;
+  if (!error) return "Unknown error";
+  const parts = [error.message ?? String(error)];
+  if (error.code) parts.push(`code=${error.code}`);
+  if (error.path) parts.push(`path=${error.path}`);
+  return parts.join("; ");
+}
+
+function tail(text) {
+  const normalized = text.replace(/\r/g, "").trim();
+  if (normalized.length <= 900) return normalized;
+  return `${normalized.slice(0, 320)}...${normalized.slice(-520)}`;
+}
+
+function redactUrl(value) {
+  return value.replace(/([?&](?:token|key|secret)=)[^&]+/gi, "$1<redacted>");
+}

package/bridge/harness.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+import { ConvexHttpClient } from "convex/browser";
+import dotenv from "dotenv";
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import process from "node:process";
+import { executeAction, defaultCapabilities } from "./adapters.mjs";
+import { bridgeFunctions } from "./convex-functions.mjs";
+import { getRuntimeConfig } from "../src/config.mjs";
+
+dotenv.config({ path: ".env", quiet: true });
+dotenv.config({ path: "bridge/.env.local", quiet: true });
+
+const options = parseArgs(process.argv.slice(2));
+const runtimeConfig = getRuntimeConfig();
+const convexUrl = options.convexUrl || runtimeConfig.convexUrl || process.env.CONVEX_URL;
+const mode = options.dryRun
+  ? "dry-run"
+  : options.mode || runtimeConfig.bridgeMode || process.env.SKILLHUB_HARNESS_MODE || "dry-run";
+const workerName =
+  options.name ||
+  process.env.SKILLHUB_WORKER_NAME ||
+  `${os.hostname()}-${process.pid}`;
+const pollMs = Number(options.pollMs || process.env.SKILLHUB_POLL_MS || 1500);
+const leaseMs = Number(options.leaseMs || process.env.SKILLHUB_LEASE_MS || 60_000);
+const capabilities = options.capabilities.length
+  ? options.capabilities
+  : parseCapabilities(process.env.SKILLHUB_CAPABILITIES) ?? defaultCapabilities;
+
+if (!convexUrl) {
+  console.error("Run skillhub connect before starting the SkillHub bridge.");
+  process.exit(1);
+}
+
+const client = new ConvexHttpClient(convexUrl);
+if (process.env.CONVEX_AUTH_TOKEN) {
+  client.setAuth(process.env.CONVEX_AUTH_TOKEN);
+}
+
+let stopping = false;
+let activeAbort = null;
+
+process.on("SIGINT", stop);
+process.on("SIGTERM", stop);
+
+await main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});
+
+async function main() {
+  console.log(`SkillHub bridge starting as ${workerName}`);
+  console.log(`Mode: ${mode}`);
+  console.log(`Capabilities: ${capabilities.join(", ")}`);
+
+  const sessionId = await client.mutation(bridgeFunctions.registerSession, {
+    name: workerName,
+    kind: process.env.RAILWAY_SERVICE_NAME ? "railway-worker" : "local-worker",
+    capabilities,
+  });
+
+  while (!stopping) {
+    await expireStaleLeases();
+
+    const claimId = randomUUID();
+    const claimed = await client.mutation(bridgeFunctions.claimNextAction, {
+      claimId,
+      claimedBy: workerName,
+      sessionId,
+      capabilities,
+      leaseMs,
+    });
+
+    if (!claimed) {
+      if (options.once) {
+        console.log("No pending host action matched this worker.");
+        return;
+      }
+      await sleep(pollMs);
+      continue;
+    }
+
+    await handleClaim({ claimId, action: claimed.action });
+
+    if (options.once) {
+      return;
+    }
+  }
+}
+
+async function handleClaim({ claimId, action }) {
+  console.log(`Claimed ${action._id}: ${action.title}`);
+
+  const abortController = new AbortController();
+  activeAbort = abortController;
+
+  const heartbeatEveryMs = Math.max(1000, Math.floor(leaseMs / 3));
+  const heartbeat = setInterval(() => {
+    client
+      .mutation(bridgeFunctions.heartbeatLease, {
+        claimId,
+        extendMs: leaseMs,
+      })
+      .catch((error) => {
+        console.error(`Heartbeat failed for ${claimId}: ${error.message}`);
+      });
+  }, heartbeatEveryMs);
+
+  const emitLog = async (level, message, data = undefined) => {
+    await client.mutation(bridgeFunctions.emitLog, {
+      claimId,
+      level,
+      source: workerName,
+      message,
+      data,
+    });
+  };
+
+  try {
+    await emitLog("info", "SkillHub bridge claimed host action.", {
+      actionId: action._id,
+      actionType: action.actionType,
+      mode,
+    });
+
+    await client.mutation(bridgeFunctions.markApplying, {
+      claimId,
+      note: `SkillHub bridge ${workerName} started ${mode}.`,
+    });
+
+    const result = await executeAction(action, {
+      mode,
+      emitLog,
+      signal: abortController.signal,
+    });
+
+    await client.mutation(bridgeFunctions.completeAction, {
+      claimId,
+      result,
+      note: `SkillHub bridge ${workerName} completed ${action.title}.`,
+    });
+
+    console.log(`Completed ${action._id}`);
+  } catch (error) {
+    const result = error?.result ?? {
+      source: "skillhub-bridge",
+      mode,
+      message: error instanceof Error ? error.message : String(error),
+    };
+
+    await client.mutation(bridgeFunctions.failAction, {
+      claimId,
+      error: error instanceof Error ? error.message : String(error),
+      data: result,
+    });
+
+    console.error(`Failed ${action._id}: ${error.message}`);
+  } finally {
+    clearInterval(heartbeat);
+    activeAbort = null;
+  }
+}
+
+async function expireStaleLeases() {
+  const result = await client.mutation(bridgeFunctions.expireStaleLeases, {
+    limit: 25,
+  });
+  if (result.expired > 0) {
+    console.log(`Expired ${result.expired} stale bridge lease(s).`);
+  }
+}
+
+function stop() {
+  stopping = true;
+  activeAbort?.abort();
+}
+
+function parseArgs(args) {
+  const parsed = {
+    capabilities: [],
+    convexUrl: "",
+    dryRun: false,
+    leaseMs: "",
+    mode: "",
+    name: "",
+    once: false,
+    pollMs: "",
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--once") parsed.once = true;
+    else if (arg === "--dry-run") parsed.dryRun = true;
+    else if (arg === "--convex-url") parsed.convexUrl = args[++index] ?? "";
+    else if (arg === "--mode") parsed.mode = args[++index] ?? "";
+    else if (arg === "--name") parsed.name = args[++index] ?? "";
+    else if (arg === "--poll-ms") parsed.pollMs = args[++index] ?? "";
+    else if (arg === "--lease-ms") parsed.leaseMs = args[++index] ?? "";
+    else if (arg === "--capability") parsed.capabilities.push(args[++index] ?? "");
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  parsed.capabilities = parsed.capabilities.filter(Boolean);
+  return parsed;
+}
+
+function parseCapabilities(value) {
+  if (!value) return null;
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/convex/_generated/ai/ai-files.state.json

@@ -0,0 +1,6 @@
+{
+  "guidelinesHash": "31cdf5763fda9ffee83f538073d80fd995883c95a2bfaf4f6441010f3c391819",
+  "agentsMdSectionHash": "5934f676ea9a332e7cd4a4f64aa23b59d926e9faca026c758d4b1f87d2101cc3",
+  "claudeMdHash": "5934f676ea9a332e7cd4a4f64aa23b59d926e9faca026c758d4b1f87d2101cc3",
+  "agentSkillsSha": "ec1e6baae7d86c7843c22938c75979c016f5c6e9"
+}