chainlesschain 0.162.158 → 0.162.159

package/src/lib/chrome-connector.js

@@ -73,6 +73,7 @@ const _deps = {
   homedir: () => os.homedir(),
   platform: () => process.platform,
   env: () => process.env,
+  tmpdir: () => os.tmpdir(),
   httpGet,
   importPlaywright: () => import("playwright"),
 };
@@ -346,4 +347,389 @@ export async function captureState({
   }
 }
 
+// ─── Browser Action mode (gap-analysis #6) ────────────────────────────────
+//
+// captureState/browser_state stay the read-only DEFAULT. performActions is
+// the explicit, approval-gated capability that DRIVES the connected browser:
+// click / type / press / navigate / waitForSelector / screenshot /
+// assertText. Every executed step is appended to an audit JSONL under
+// ~/.chainlesschain/browser-actions/<date>.jsonl (CC_BROWSER_ACTIONS_DIR
+// overrides the dir for tests). Screenshot paths are ALWAYS generated
+// internally — a caller-supplied path is refused (same invariant as
+// browser_state: an action tool must not double as an arbitrary-file writer).
+
+export const SUPPORTED_BROWSER_ACTIONS = Object.freeze([
+  "click",
+  "type",
+  "press",
+  "navigate",
+  "waitForSelector",
+  "screenshot",
+  "assertText",
+]);
+export const MAX_BROWSER_ACTIONS = 30;
+export const DEFAULT_ACTION_TIMEOUT_MS = 10000;
+export const MAX_ACTION_TIMEOUT_MS = 30000;
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
+
+/** Audit log directory (CC_BROWSER_ACTIONS_DIR override for tests). */
+export function browserActionsDir({ deps = _deps } = {}) {
+  const env = deps.env();
+  if (env.CC_BROWSER_ACTIONS_DIR) return env.CC_BROWSER_ACTIONS_DIR;
+  return path.join(deps.homedir(), ".chainlesschain", "browser-actions");
+}
+
+/**
+ * Resolve an optional caller CDP endpoint to a PORT, enforcing the connector's
+ * loopback-only contract: only http:// against 127.0.0.1 / localhost / [::1]
+ * is accepted. performActions then connects to `http://127.0.0.1:<port>` —
+ * the caller string is never used as the connection target verbatim, so a
+ * crafted endpoint cannot widen the trust boundary the prior security fix
+ * established.
+ */
+export function resolveLoopbackCdpPort(
+  cdpUrl,
+  fallbackPort = DEFAULT_CDP_PORT,
+) {
+  if (cdpUrl == null || cdpUrl === "") return normalizeCdpPort(fallbackPort);
+  let parsed;
+  try {
+    parsed = new URL(String(cdpUrl));
+  } catch {
+    throw new Error(`Invalid CDP endpoint: ${cdpUrl}`);
+  }
+  if (parsed.protocol !== "http:") {
+    throw new Error(
+      `CDP endpoint must be http:// on loopback (got ${parsed.protocol})`,
+    );
+  }
+  if (!LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase())) {
+    throw new Error(
+      `CDP endpoint must be loopback-only (127.0.0.1 / localhost) — refusing host "${parsed.hostname}"`,
+    );
+  }
+  return normalizeCdpPort(parsed.port || DEFAULT_CDP_PORT);
+}
+
+function truncateForAudit(value, cap = 200) {
+  const s = String(value);
+  return s.length > cap ? `${s.slice(0, cap)}…` : s;
+}
+
+/**
+ * Validate + normalize the caller's action list BEFORE anything connects.
+ * Throws on the first invalid action — performActions turns that into
+ * {ok:false, error} without touching the browser. Screenshot paths are
+ * generated here (deps.tmpdir), and any caller-supplied path key is refused.
+ */
+export function normalizeBrowserActions(actions, { deps = _deps } = {}) {
+  if (!Array.isArray(actions) || actions.length === 0) {
+    throw new Error("actions must be a non-empty array of action objects");
+  }
+  if (actions.length > MAX_BROWSER_ACTIONS) {
+    throw new Error(
+      `too many actions (${actions.length}) — max ${MAX_BROWSER_ACTIONS} per call`,
+    );
+  }
+  const requireSelector = (raw, type) => {
+    const sel = raw.selector;
+    if (typeof sel !== "string" || sel.trim() === "" || sel.length > 1000) {
+      throw new Error(`${type} requires a non-empty "selector" string`);
+    }
+    return sel;
+  };
+  return actions.map((raw, i) => {
+    if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new Error(`action[${i}] must be an object with a "type"`);
+    }
+    const type = String(raw.type || "");
+    if (!SUPPORTED_BROWSER_ACTIONS.includes(type)) {
+      throw new Error(
+        `action[${i}] has unsupported type "${type}". Supported: ${SUPPORTED_BROWSER_ACTIONS.join(", ")}`,
+      );
+    }
+    switch (type) {
+      case "click":
+        return { type, selector: requireSelector(raw, "click") };
+      case "type": {
+        if (typeof raw.text !== "string") {
+          throw new Error(`type requires a "text" string`);
+        }
+        return { type, selector: requireSelector(raw, "type"), text: raw.text };
+      }
+      case "press": {
+        if (
+          typeof raw.key !== "string" ||
+          raw.key.trim() === "" ||
+          raw.key.length > 50
+        ) {
+          throw new Error(`press requires a non-empty "key" string`);
+        }
+        return { type, key: raw.key };
+      }
+      case "navigate": {
+        let parsed;
+        try {
+          parsed = new URL(String(raw.url || ""));
+        } catch {
+          throw new Error(`navigate has an invalid "url": ${raw.url}`);
+        }
+        if (!["http:", "https:"].includes(parsed.protocol)) {
+          throw new Error(
+            `navigate url must be http(s):// (got ${parsed.protocol})`,
+          );
+        }
+        return { type, url: String(raw.url) };
+      }
+      case "waitForSelector": {
+        const t = Number(raw.timeoutMs ?? raw.timeout_ms ?? 5000);
+        const timeoutMs = Math.min(
+          Math.max(Number.isFinite(t) ? t : 5000, 1),
+          MAX_ACTION_TIMEOUT_MS,
+        );
+        return {
+          type,
+          selector: requireSelector(raw, "waitForSelector"),
+          timeoutMs,
+        };
+      }
+      case "screenshot": {
+        // The path is GENERATED — never caller-supplied. Refuse loudly so a
+        // model (or user) learns the invariant instead of being silently
+        // second-guessed.
+        for (const k of ["path", "file", "output", "screenshotPath"]) {
+          if (raw[k] != null) {
+            throw new Error(
+              `screenshot path is generated internally — remove "${k}"`,
+            );
+          }
+        }
+        return {
+          type,
+          screenshotPath: path.join(
+            deps.tmpdir(),
+            `cc-browser-act-${Date.now()}-${i}.png`,
+          ),
+        };
+      }
+      case "assertText": {
+        if (typeof raw.expected !== "string" || raw.expected === "") {
+          throw new Error(`assertText requires a non-empty "expected" string`);
+        }
+        return {
+          type,
+          selector: requireSelector(raw, "assertText"),
+          expected: raw.expected,
+        };
+      }
+      /* c8 ignore next 2 -- unreachable: type already validated above */
+      default:
+        throw new Error(`unsupported action type "${type}"`);
+    }
+  });
+}
+
+/** One JSONL row per EXECUTED step (explicit utf-8, best-effort). */
+function appendActionAudit(entry, deps) {
+  const dir = browserActionsDir({ deps });
+  deps.fs.mkdirSync(dir, { recursive: true });
+  const date = entry.ts.slice(0, 10);
+  deps.fs.appendFileSync(
+    path.join(dir, `${date}.jsonl`),
+    JSON.stringify(entry) + "\n",
+    "utf-8",
+  );
+}
+
+/**
+ * Does the dedicated connector profile own the CDP port we are attaching to?
+ * Chrome writes DevToolsActivePort (first line = port) into the user-data-dir
+ * it was launched with; if the file under ~/.chainlesschain/chrome-profile is
+ * missing or names a different port, we are driving some OTHER profile —
+ * possibly the user's real logged-in browser — and the result carries a
+ * profileWarning.
+ */
+function connectorProfileOwnsPort(port, deps) {
+  try {
+    const marker = path.join(
+      connectorProfileDir({ deps }),
+      "DevToolsActivePort",
+    );
+    if (!deps.fs.existsSync(marker)) return false;
+    const firstLine = String(deps.fs.readFileSync(marker, "utf-8"))
+      .split(/\r?\n/)[0]
+      .trim();
+    return Number(firstLine) === Number(port);
+  } catch {
+    return false;
+  }
+}
+
+async function runOneAction(page, act, timeoutMs) {
+  switch (act.type) {
+    case "click":
+      await page.click(act.selector, { timeout: timeoutMs });
+      return `clicked ${act.selector}`;
+    case "type":
+      await page.fill(act.selector, act.text, { timeout: timeoutMs });
+      return `typed ${act.text.length} chars into ${act.selector}`;
+    case "press":
+      await page.keyboard.press(act.key);
+      return `pressed ${act.key}`;
+    case "navigate":
+      await page.goto(act.url, {
+        waitUntil: "domcontentloaded",
+        timeout: timeoutMs,
+      });
+      return `navigated to ${act.url}`;
+    case "waitForSelector":
+      await page.waitForSelector(act.selector, { timeout: act.timeoutMs });
+      return `selector appeared: ${act.selector}`;
+    case "screenshot":
+      await page.screenshot({ path: act.screenshotPath });
+      return `screenshot saved: ${act.screenshotPath}`;
+    case "assertText": {
+      const text = await page.textContent(act.selector, {
+        timeout: timeoutMs,
+      });
+      if (text == null) {
+        throw new Error(`assertText: no element matches ${act.selector}`);
+      }
+      if (!text.includes(act.expected)) {
+        throw new Error(
+          `assertText FAILED: "${truncateForAudit(act.expected, 80)}" not found in ${act.selector} (got: ${truncateForAudit(text.trim(), 120)})`,
+        );
+      }
+      return `assertText passed: ${act.selector} contains "${truncateForAudit(act.expected, 80)}"`;
+    }
+    /* c8 ignore next 2 -- unreachable: normalizeBrowserActions validated type */
+    default:
+      throw new Error(`unsupported action type "${act.type}"`);
+  }
+}
+
+/**
+ * Execute an ordered list of explicit browser actions against the connected
+ * Chrome. Fail-fast on the first failed step unless `continueOnError`. Each
+ * step result is {ok, action, detail, durationMs}; the overall result adds
+ * final page url/title, `executed` count, optional `profileWarning` (attached
+ * browser is NOT the dedicated connector profile) and `auditError` (audit
+ * write failed — actions themselves are never aborted for audit IO).
+ */
+export async function performActions(
+  actions,
+  {
+    port = DEFAULT_CDP_PORT,
+    cdpUrl = null,
+    tab = 0,
+    continueOnError = false,
+    sessionId = null,
+    actionTimeoutMs = DEFAULT_ACTION_TIMEOUT_MS,
+    deps = _deps,
+  } = {},
+) {
+  let normalized;
+  let resolvedPort;
+  try {
+    resolvedPort = resolveLoopbackCdpPort(cdpUrl, port);
+    normalized = normalizeBrowserActions(actions, { deps });
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+  const stepTimeout = Math.min(
+    Math.max(Number(actionTimeoutMs) || DEFAULT_ACTION_TIMEOUT_MS, 1),
+    MAX_ACTION_TIMEOUT_MS,
+  );
+
+  let playwright;
+  try {
+    playwright = await deps.importPlaywright();
+  } catch {
+    return {
+      ok: false,
+      error: "playwright is not installed — npm install playwright",
+    };
+  }
+  let browser;
+  try {
+    browser = await playwright.chromium.connectOverCDP(
+      `http://127.0.0.1:${resolvedPort}`,
+    );
+  } catch (err) {
+    return {
+      ok: false,
+      error:
+        `cannot attach to CDP on port ${resolvedPort} (${err.message.split("\n")[0]}) — ` +
+        "launch a debuggable Chrome first (cc browse chrome launch)",
+    };
+  }
+  try {
+    // Same post-connect target-attach race as captureState: poll briefly.
+    let pages = [];
+    for (let i = 0; i < 20; i++) {
+      pages = browser.contexts().flatMap((c) => c.pages());
+      if (pages.length > 0) break;
+      await new Promise((r) => setTimeout(r, 150));
+    }
+    if (pages.length === 0) {
+      return { ok: false, error: "the connected Chrome has no open tabs" };
+    }
+    const index = Math.min(Math.max(0, Number(tab) || 0), pages.length - 1);
+    const page = pages[index];
+
+    const result = { ok: false, port: resolvedPort, tab: index, steps: [] };
+    if (!connectorProfileOwnsPort(resolvedPort, deps)) {
+      result.profileWarning =
+        "the attached Chrome does not appear to be running the dedicated connector profile " +
+        "(~/.chainlesschain/chrome-profile) — actions run in that browser's REAL session";
+    }
+
+    let auditError = null;
+    for (const act of normalized) {
+      const started = Date.now();
+      const step = { ok: false, action: act.type, detail: "", durationMs: 0 };
+      try {
+        step.detail = await runOneAction(page, act, stepTimeout);
+        step.ok = true;
+        if (act.screenshotPath) step.screenshotPath = act.screenshotPath;
+      } catch (err) {
+        step.detail = String(err && err.message ? err.message : err).split(
+          "\n",
+        )[0];
+      }
+      step.durationMs = Date.now() - started;
+      result.steps.push(step);
+      try {
+        const entry = {
+          ts: new Date(started).toISOString(),
+          action: act.type,
+          ok: step.ok,
+          durationMs: step.durationMs,
+        };
+        if (sessionId) entry.sessionId = String(sessionId);
+        if (act.selector) entry.selector = truncateForAudit(act.selector);
+        if (act.url) entry.url = truncateForAudit(act.url);
+        if (act.key) entry.key = truncateForAudit(act.key, 50);
+        appendActionAudit(entry, deps);
+      } catch (err) {
+        auditError = err.message;
+      }
+      if (!step.ok && !continueOnError) break;
+    }
+
+    result.executed = result.steps.length;
+    result.ok =
+      result.steps.length === normalized.length &&
+      result.steps.every((s) => s.ok);
+    if (auditError) result.auditError = auditError;
+    result.url = page.url();
+    result.title = await page.title().catch(() => "");
+    return result;
+  } finally {
+    // connectOverCDP close() disconnects the client; the browser lives on.
+    await browser.close().catch(() => {});
+  }
+}
+
 export { _deps };

package/src/lib/cloud/bundle.js

@@ -0,0 +1,110 @@
+/**
+ * Git branch bundling + result reflow for cloud handoff. A `git bundle` of the
+ * current branch (base64) is the portable snapshot the private runner clones;
+ * the runner returns a patch/plan/pr/artifacts which we apply/persist locally.
+ *
+ * All git calls go through the injectable `run` so the flow is testable without
+ * a repo.
+ */
+
+import { execFileSync } from "node:child_process";
+import { writeFileSync, mkdtempSync } from "node:fs";
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+export const _deps = { execFileSync };
+
+function git(args, cwd, deps = _deps) {
+  return deps
+    .execFileSync("git", args, {
+      cwd,
+      encoding: "utf-8",
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+    .toString();
+}
+
+/**
+ * Bundle the current branch into a base64 git bundle.
+ * @returns {{ bundle:string, branch:string, baseSha:string, bytes:number }}
+ */
+export function bundleBranch(cwd = process.cwd(), deps = _deps) {
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], cwd, deps).trim();
+  const baseSha = git(["rev-parse", "HEAD"], cwd, deps).trim();
+  const tmp = mkdtempSync(join(tmpdir(), "cc-cloud-bundle-"));
+  const bundleFile = join(tmp, "branch.bundle");
+  try {
+    // Bundle the full branch history so the runner can clone a working repo.
+    git(["bundle", "create", bundleFile, "HEAD", branch], cwd, deps);
+    const buf = readFileSync(bundleFile);
+    return {
+      bundle: buf.toString("base64"),
+      branch,
+      baseSha,
+      bytes: buf.length,
+    };
+  } finally {
+    try {
+      rmSync(tmp, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+/**
+ * Apply a unified-diff patch the runner produced onto the local worktree.
+ * Uses `git apply --3way` so it merges cleanly on top of local edits when
+ * possible; returns { applied, reason }.
+ */
+export function applyResultPatch(patch, cwd = process.cwd(), deps = _deps) {
+  if (!patch || !String(patch).trim()) {
+    return { applied: false, reason: "no patch in result" };
+  }
+  const tmp = mkdtempSync(join(tmpdir(), "cc-cloud-patch-"));
+  const patchFile = join(tmp, "result.patch");
+  try {
+    writeFileSync(patchFile, patch, "utf-8");
+    git(["apply", "--3way", "--whitespace=nowarn", patchFile], cwd, deps);
+    return { applied: true, reason: "patch applied (3way)" };
+  } catch (err) {
+    return {
+      applied: false,
+      reason: `patch did not apply cleanly: ${err.message.split("\n")[0]}`,
+    };
+  } finally {
+    try {
+      rmSync(tmp, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+/**
+ * Persist non-patch result artifacts (plan text, artifact blobs) under the
+ * job's local dir and return where they landed. `writeFile` injected.
+ */
+export function persistResultArtifacts(result, destDir, deps = {}) {
+  const writeFile = deps.writeFileSync || writeFileSync;
+  const written = [];
+  if (result?.plan) {
+    const p = join(destDir, "plan.md");
+    writeFile(p, String(result.plan), "utf-8");
+    written.push(p);
+  }
+  for (const art of Array.isArray(result?.artifacts) ? result.artifacts : []) {
+    if (!art?.name || art.content == null) continue;
+    const safe = String(art.name).replace(/[^\w.-]/g, "_");
+    const p = join(destDir, safe);
+    const content =
+      art.encoding === "base64"
+        ? Buffer.from(String(art.content), "base64")
+        : String(art.content);
+    writeFile(p, content);
+    written.push(p);
+  }
+  return written;
+}

package/src/lib/cloud/cloud-client.js

@@ -0,0 +1,152 @@
+/**
+ * Self-hosted cloud handoff (gap-2026-07-11 P1#7) — the private-runner version
+ * of Claude Code's --cloud/--teleport. `cc cloud run "<task>"` bundles the
+ * current git branch, POSTs it to a configured private runner, and records the
+ * job locally; `cc cloud status/attach` poll and reflow the runner's result
+ * (plan / patch / PR / artifacts) back into the local workspace.
+ *
+ * No Anthropic cloud dependency: the runner is any HTTP endpoint speaking the
+ * small protocol below (a reference runner can be a box running `cc agent`).
+ *
+ *   POST   {base}/v1/jobs           {task, bundle(base64), branch, baseSha}     → {jobId}
+ *   GET    {base}/v1/jobs/{id}       → {status: queued|running|done|failed, summary?}
+ *   GET    {base}/v1/jobs/{id}/result → {patch?, plan?, pr?, artifacts?, log?}
+ *
+ * Auth: Bearer token (config cloud.token / CC_CLOUD_TOKEN). Transport (fetch)
+ * and the bundle builder are injected so this is unit-testable offline.
+ *
+ * Local job ledger: ~/.chainlesschain/cloud-jobs/<jobId>.json
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { getHomeDir } from "../paths.js";
+
+export const _deps = { fetch: (...a) => globalThis.fetch(...a) };
+
+export function cloudJobsDir() {
+  const dir = join(getHomeDir(), "cloud-jobs");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function jobPath(jobId) {
+  if (!/^[\w.-]+$/.test(String(jobId || ""))) {
+    throw new Error(`invalid job id: ${jobId}`);
+  }
+  return join(cloudJobsDir(), `${jobId}.json`);
+}
+
+export function saveJob(job) {
+  writeFileSync(jobPath(job.jobId), JSON.stringify(job, null, 2), "utf-8");
+  return job;
+}
+
+export function readJob(jobId) {
+  try {
+    return JSON.parse(readFileSync(jobPath(jobId), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function listJobs() {
+  const dir = cloudJobsDir();
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => {
+      try {
+        return JSON.parse(readFileSync(join(dir, f), "utf-8"));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => (b.submittedAt || 0) - (a.submittedAt || 0));
+}
+
+export class CloudClient {
+  /**
+   * @param {object} opts { baseUrl, token, deps? }
+   */
+  constructor(opts = {}) {
+    this.baseUrl = String(opts.baseUrl || "").replace(/\/+$/, "");
+    if (!this.baseUrl) {
+      throw new Error(
+        "no cloud runner configured — set cloud.baseUrl / CC_CLOUD_URL",
+      );
+    }
+    this.token = opts.token || null;
+    this.deps = { ..._deps, ...(opts.deps || {}) };
+  }
+
+  _headers(extra = {}) {
+    return {
+      "Content-Type": "application/json",
+      ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}),
+      ...extra,
+    };
+  }
+
+  async _json(method, path, body) {
+    const res = await this.deps.fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: this._headers(),
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    if (!res.ok) {
+      throw new Error(`cloud runner ${method} ${path} → HTTP ${res.status}`);
+    }
+    return res.json();
+  }
+
+  /** Submit a job. `bundle` is a base64 git bundle of the branch. */
+  async submit({ task, bundle, branch, baseSha }) {
+    const data = await this._json("POST", "/v1/jobs", {
+      task,
+      bundle,
+      branch,
+      baseSha,
+    });
+    if (!data?.jobId) throw new Error("runner did not return a jobId");
+    return data;
+  }
+
+  async status(jobId) {
+    return this._json("GET", `/v1/jobs/${encodeURIComponent(jobId)}`);
+  }
+
+  async result(jobId) {
+    return this._json("GET", `/v1/jobs/${encodeURIComponent(jobId)}/result`);
+  }
+}
+
+export const TERMINAL_CLOUD_STATUS = new Set(["done", "failed"]);
+
+/**
+ * Poll a job until terminal or the deadline. `onTick(status)` reports progress.
+ * `sleep`/`now` injected for tests.
+ */
+export async function pollUntilDone(client, jobId, opts = {}) {
+  const intervalMs = opts.intervalMs ?? 3000;
+  const timeoutMs = opts.timeoutMs ?? 30 * 60_000;
+  const sleep = opts.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = opts.now || (() => Date.now());
+  const deadline = now() + timeoutMs;
+  for (;;) {
+    const status = await client.status(jobId);
+    opts.onTick?.(status);
+    if (TERMINAL_CLOUD_STATUS.has(status.status)) return status;
+    if (now() >= deadline) {
+      return { status: "timeout", summary: "poll deadline reached" };
+    }
+    await sleep(intervalMs);
+  }
+}