@foldspace_npm/harness 0.1.9 → 0.1.11

package/src/cdp-ownership.mjs

@@ -0,0 +1,241 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { createCdpRequestManager } from "./cdp-request-manager.mjs";
+
+export const SENTINEL_FILE = ".foldspace-sentinel";
+
+export function chromeProfileDir(root) {
+  return path.join(root, ".foldspace-dev", "chrome-profile");
+}
+
+export function sentinelPath(profileDir) {
+  return path.join(profileDir, SENTINEL_FILE);
+}
+
+function present(value) {
+  if (value == null) return null;
+  const text = String(value).trim();
+  return text ? text : null;
+}
+
+function resolvedPath(filePath) {
+  try {
+    return fs.realpathSync(filePath);
+  } catch {
+    return path.resolve(filePath);
+  }
+}
+
+export function writeLaunchSentinel(profileDir) {
+  const token = crypto.randomBytes(16).toString("hex");
+  fs.mkdirSync(profileDir, { recursive: true });
+  fs.writeFileSync(sentinelPath(profileDir), `${token}\n`, "utf8");
+  return token;
+}
+
+export function readLaunchSentinel(profileDir) {
+  try {
+    return present(fs.readFileSync(sentinelPath(profileDir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function verifyLaunchSentinel({ profileDir, token } = {}) {
+  const onDisk = readLaunchSentinel(profileDir);
+  const expected = present(token);
+  if (!expected || !onDisk || onDisk !== expected) {
+    return { ok: false, reason: "sentinel_mismatch" };
+  }
+  return { ok: true };
+}
+
+export function parseChromeVersionText(text) {
+  const body = String(text || "");
+  const profilePath = present(body.match(/Profile Path\s+(.+)/i)?.[1]);
+  const commandLine = present(
+    body.match(/Command Line\s+(.+?)(?=\n[A-Z][A-Za-z ]+\s|\n{2}|$)/s)?.[1],
+  );
+  const userDataMatch = commandLine?.match(
+    /--user-data-dir(?:=|\s+)(?:"([^"]+)"|(\S+))/,
+  );
+  return {
+    profilePath,
+    commandLine,
+    userDataDir: present(userDataMatch?.[1] || userDataMatch?.[2]),
+  };
+}
+
+export function reportedProfileMatches(profileDir, reported = {}) {
+  const expected = resolvedPath(profileDir);
+  if (reported.userDataDir) {
+    return resolvedPath(reported.userDataDir) === expected;
+  }
+  if (reported.profilePath) {
+    return resolvedPath(path.dirname(reported.profilePath)) === expected;
+  }
+  return false;
+}
+
+export function verifyCdpOwnership({ profileDir, token, reported } = {}) {
+  const sentinel = verifyLaunchSentinel({ profileDir, token });
+  if (!sentinel.ok) return sentinel;
+  if (!reportedProfileMatches(profileDir, reported)) {
+    return { ok: false, reason: "profile_mismatch" };
+  }
+  return { ok: true };
+}
+
+export function ownershipErrorMessage(
+  reason,
+  { port, profileDir, root } = {},
+) {
+  const profile =
+    root && profileDir
+      ? path.relative(root, profileDir) || profileDir
+      : profileDir || ".foldspace-dev/chrome-profile";
+  const hints = {
+    sentinel_mismatch:
+      "Launch sentinel is missing or does not match. Run foldspace inject again.",
+    profile_mismatch: `The browser on :${port} is using a different user-data-dir than ${profile}.`,
+    cdp_inspect_failed: `Could not read the profile path from Chrome on :${port}.`,
+    cdp_not_ready: `Chrome did not expose CDP on :${port}.`,
+  };
+  return (
+    `Chrome on :${port} is not the Foldspace profile.\n` +
+    `        ${hints[reason] || reason}\n` +
+    `        Close the other debugging Chrome, or pass --port <free-port>.`
+  );
+}
+
+export async function fetchCdpVersion(port) {
+  const response = await fetch(`http://127.0.0.1:${port}/json/version`);
+  if (!response.ok) {
+    throw new Error(`CDP /json/version returned ${response.status}`);
+  }
+  return response.json();
+}
+
+async function openCdpSocket(webSocketDebuggerUrl) {
+  const cdp = createCdpRequestManager({ timeoutMs: 8_000 });
+  const ws = new WebSocket(webSocketDebuggerUrl);
+  await new Promise((resolve, reject) => {
+    ws.addEventListener("open", resolve);
+    ws.addEventListener("error", reject);
+  });
+  ws.addEventListener("message", (event) => {
+    cdp.handleMessage(JSON.parse(event.data));
+  });
+  return {
+    ws,
+    call: (method, params, sessionId) => cdp.call(ws, method, params, sessionId),
+    close() {
+      cdp.failAll();
+      ws.close();
+    },
+  };
+}
+
+export async function inspectCdpUserDataDir(webSocketDebuggerUrl) {
+  const session = await openCdpSocket(webSocketDebuggerUrl);
+  try {
+    const { targetId } = await session.call("Target.createTarget", {
+      url: "chrome://version/",
+    });
+    const attached = await session.call("Target.attachToTarget", {
+      targetId,
+      flatten: true,
+    });
+    const sessionId = attached.sessionId;
+    await session.call("Runtime.enable", {}, sessionId);
+    await session.call("Page.enable", {}, sessionId);
+
+    let text = "";
+    for (let attempt = 0; attempt < 20; attempt++) {
+      const evaluation = await session.call(
+        "Runtime.evaluate",
+        {
+          expression: "document.body ? document.body.innerText : ''",
+          returnByValue: true,
+        },
+        sessionId,
+      );
+      text = evaluation?.result?.value || "";
+      if (/Profile Path|Command Line/i.test(text)) break;
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    }
+
+    try {
+      await session.call("Target.closeTarget", { targetId });
+    } catch {
+      // Best-effort: ownership can still be decided from the text we got.
+    }
+
+    const reported = parseChromeVersionText(text);
+    if (!reported.userDataDir && !reported.profilePath) {
+      throw new Error("chrome://version did not expose a profile path");
+    }
+    return reported;
+  } finally {
+    session.close();
+  }
+}
+
+export async function assertOwnedCdp({
+  profileDir,
+  port,
+  token,
+  fetchVersion = fetchCdpVersion,
+  inspectUserDataDir = inspectCdpUserDataDir,
+} = {}) {
+  const sentinel = verifyLaunchSentinel({ profileDir, token });
+  if (!sentinel.ok) return sentinel;
+
+  let version;
+  try {
+    version = await fetchVersion(port);
+  } catch {
+    return { ok: false, reason: "cdp_not_ready", version: null };
+  }
+
+  let reported;
+  try {
+    reported = await inspectUserDataDir(version.webSocketDebuggerUrl);
+  } catch {
+    return { ok: false, reason: "cdp_inspect_failed", version };
+  }
+
+  const result = verifyCdpOwnership({ profileDir, token, reported });
+  return { ...result, version, reported };
+}
+
+export async function waitForOwnedCdp({
+  profileDir,
+  port,
+  token,
+  timeoutMs = 20_000,
+  fetchVersion = fetchCdpVersion,
+  inspectUserDataDir = inspectCdpUserDataDir,
+  now = Date.now,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
+  const started = now();
+  let last = { ok: false, reason: "cdp_not_ready", version: null };
+  while (now() - started < timeoutMs) {
+    last = await assertOwnedCdp({
+      profileDir,
+      port,
+      token,
+      fetchVersion,
+      inspectUserDataDir,
+    });
+    if (last.ok) return last;
+    if (last.reason !== "cdp_not_ready" && last.reason !== "cdp_inspect_failed") {
+      return last;
+    }
+    await sleep(250);
+  }
+  return last;
+}

package/src/cli-help.mjs

@@ -46,6 +46,7 @@ export function renderGeneralHelp(registry) {
     "  foldspace help --json            Print the machine-readable CLI contract",
     "  foldspace help <command> --json  Print one command contract",
     "  foldspace --version              Show package and protocol versions",
+    "  foldspace upgrade --check        Compare the installed pin to npm latest",
     "",
     "attach loads local actions and observes the normal agent experience.",
     "deploy is a separate remote publication step.",

package/src/cli-registry.mjs

@@ -21,7 +21,7 @@ export const CLI_COMMANDS = Object.freeze([
     group: "start",
     summary: "Create a configured Foldspace actions project",
     usage:
-      "foldspace init [<directory>] [--product-id <id>] [--agent-key <key>] [--domain <host>] [--name <display-name>]",
+      "foldspace init [<directory>] [--product-id <id>] [--agent-key <key>] [--app-domain <host>] [--name <display-name>]",
     risk: "local-write",
     environment: "node",
     environmentVariables: [],
@@ -41,8 +41,9 @@ export const CLI_COMMANDS = Object.freeze([
         required: "non-interactive",
         deprecatedAliases: ["--agent-api-name"],
       }),
-      value("--domain", "host", "Target hostname or HTTP(S) URL", {
+      value("--app-domain", "host", "Live app hostname or HTTP(S) URL", {
         required: "non-interactive",
+        deprecatedAliases: ["--domain"],
       }),
       value("--name", "display-name", "Display name", {
         default: "directory name",
@@ -51,7 +52,7 @@ export const CLI_COMMANDS = Object.freeze([
     prerequisites: [
       "Node 20 or newer",
       "A target directory that does not already exist",
-      "Non-interactive use requires directory, product ID, Agent Key, and domain",
+      "Non-interactive use requires directory, product ID, Agent Key, and app domain",
     ],
     effects: ["Creates a new local project; never initializes Git"],
     next: [
@@ -61,6 +62,48 @@ export const CLI_COMMANDS = Object.freeze([
       "Run foldspace attach",
     ],
   }),
+  Object.freeze({
+    name: "upgrade",
+    entry: null,
+    group: "start",
+    summary: "Check for a newer harness and update the exact pin after asking",
+    usage:
+      "foldspace upgrade [--check | --yes] [--refresh-instructions]",
+    risk: "local-write",
+    environment: "node",
+    environmentVariables: [
+      "FOLDSPACE_PROJECT_DIR",
+      "FOLDSPACE_SKIP_UPDATE_CHECK",
+    ],
+    capabilities: ["project.upgrade"],
+    positionals: [],
+    options: [
+      flag("--check", "Compare versions and print JSON; never install"),
+      flag(
+        "--yes",
+        "Install the latest exact pin after the user has already agreed",
+      ),
+      flag(
+        "--refresh-instructions",
+        "Replace CLAUDE.md with an import of the package instructions",
+      ),
+    ],
+    prerequisites: [
+      "A consumer project with package.json",
+      "An exact @foldspace_npm/harness dependency unless only refreshing instructions",
+    ],
+    effects: [
+      "Without --yes, writes nothing except an optional update cache",
+      "With --yes, rewrites the exact harness pin and runs npm install --ignore-scripts",
+      "Does not rebuild dist/index.js or deploy",
+      "--refresh-instructions copies CLAUDE.md to CLAUDE.md.bak then writes the stub",
+    ],
+    next: [
+      "If outdated, ask the user, then run foldspace upgrade --yes",
+      "Run npm run build after a pin bump",
+      "Deploy only if product users should receive the rebuilt runtime",
+    ],
+  }),
   Object.freeze({
     name: "build",
     entry: "build-cli.mjs",
@@ -194,7 +237,7 @@ export const CLI_COMMANDS = Object.freeze([
       value(
         "--port",
         "number",
-        "CDP port: CLI, CDP_PORT, saved launch state, then 9222",
+        "CDP port: CLI, CDP_PORT, or the port inject recorded",
       ),
       value("--agent", "api-name", "Override the configured agent API name"),
       flag(
@@ -217,6 +260,7 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     effects: [
       "May reload and instrument matching target pages",
+      "Refuses a Chrome that is not the profile inject launched",
       "Test mode is enabled unless --no-test-mode is passed",
       "Never directly invokes an action handler",
       "An empty local action registry is valid; named actions are not required",
@@ -271,6 +315,7 @@ export const CLI_COMMANDS = Object.freeze([
 
 export const CAPABILITY_CATALOGUE = Object.freeze([
   ["project.scaffold", "Create a new configured project on local disk"],
+  ["project.upgrade", "Update the consuming project's exact harness pin"],
   ["artifact.build", "Build the portable dist/index.js action artifact"],
   ["browser.launch", "Launch an isolated local Chrome profile"],
   ["browser.cdp", "Connect to local Chrome through CDP"],
@@ -341,6 +386,7 @@ export function createCliRegistry({ packageName, packageVersion }) {
       "The harness bin alias is equivalent to foldspace.",
       "attach diagnostics are attach-internal; interpret them from the lifecycle log, not as CLI commands.",
       "Coding agents should run attach --daemon; foreground attach is for humans watching the terminal.",
+      "If update.outdated is true, ask the user before foldspace upgrade --yes.",
     ],
   };
 }

package/src/init.mjs

@@ -13,6 +13,7 @@ const allowedFlags = new Set([
   "product-id",
   "agent-key",
   "agent-api-name",
+  "app-domain",
   "domain",
 ]);
 const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
@@ -86,13 +87,18 @@ export function parseInitArgs(argv) {
       "Use --agent-key only; --agent-api-name is its deprecated alias.",
     );
   }
+  if (flags["app-domain"] && flags.domain) {
+    throw new Error(
+      "Use --app-domain only; --domain is its deprecated alias.",
+    );
+  }
 
   return {
     directory: positional[0] || null,
     displayName: flags.name || null,
     productId: flags["product-id"] || null,
     agentApiName: flags["agent-key"] || flags["agent-api-name"] || null,
-    domain: flags.domain || null,
+    domain: flags["app-domain"] || flags.domain || null,
   };
 }
 
@@ -101,7 +107,7 @@ function missingInitFields(parsed) {
   if (!parsed.directory) missing.push("directory");
   if (!parsed.productId) missing.push("product-id");
   if (!parsed.agentApiName) missing.push("agent-key");
-  if (!parsed.domain) missing.push("domain");
+  if (!parsed.domain) missing.push("app-domain");
   return missing;
 }
 
@@ -134,14 +140,14 @@ function validateProductId(value) {
 function normalizeTarget(value) {
   const raw = value.trim();
   if (!raw || raw.includes("*")) {
-    throw new Error("Domain must be a concrete hostname without a wildcard.");
+    throw new Error("App domain must be a concrete hostname without a wildcard.");
   }
 
   let url;
   try {
     url = new URL(raw.includes("://") ? raw : `https://${raw}`);
   } catch {
-    throw new Error(`Invalid domain: ${value}`);
+    throw new Error(`Invalid app domain: ${value}`);
   }
 
   if (
@@ -153,12 +159,12 @@ function normalizeTarget(value) {
     url.search ||
     url.hash
   ) {
-    throw new Error("Domain must contain only an HTTP(S) hostname, without credentials, a port, path, query, or fragment.");
+    throw new Error("App domain must contain only an HTTP(S) hostname, without credentials, a port, path, query, or fragment.");
   }
 
   const domain = url.hostname.toLowerCase().replace(/\.$/, "");
   if (!domain || domain.includes("..")) {
-    throw new Error(`Invalid domain: ${value}`);
+    throw new Error(`Invalid app domain: ${value}`);
   }
 
   return {
@@ -227,7 +233,7 @@ async function promptForMissingFields(parsed, options = {}) {
 
   if (!next.domain) {
     next.domain = await askUntilValid(
-      "Domain",
+      "App domain",
       (value) => {
         normalizeTarget(value);
         return value.trim();
@@ -255,7 +261,7 @@ function finalizeInitConfig(parsed) {
   for (const [key, label] of [
     ["productId", "product-id"],
     ["agentApiName", "agent-key"],
-    ["domain", "domain"],
+    ["domain", "app-domain"],
   ]) {
     if (!parsed[key]) {
       throw new Error(`Missing required option: --${label}\nUsage: ${initUsage}`);
@@ -304,7 +310,9 @@ function createTemplateValues(config, harnessVersion) {
     DISPLAY_NAME: displayName,
     PACKAGE_NAME: packageName,
     PACKAGE_DESCRIPTION_JSON: JSON.stringify(`Foldspace browser actions for ${displayName}.`),
+    PRODUCT_ID: productId,
     PRODUCT_ID_JSON: JSON.stringify(productId),
+    AGENT_API_NAME: agentApiName,
     AGENT_API_NAME_JSON: JSON.stringify(agentApiName),
     APP_DOMAIN: target.domain,
     APP_DOMAIN_JSON: JSON.stringify(target.domain),