@foldspace_npm/harness 0.1.1 → 0.1.3

package/src/init.mjs

@@ -1,14 +1,18 @@
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath } from "node:url";
+import { commandByName } from "./cli-registry.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const defaultTemplateRoot = path.join(packageRoot, "templates", "agent-starter");
 const allowedFlags = new Set(["name", "product-id", "agent-api-name", "domain"]);
 const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
+const defaultDirectory = "my-agent";
 
-export const initUsage =
-  "foldspace init <directory> --product-id <id> --agent-api-name <name> --domain <host> [--name <display-name>]";
+export const initUsage = commandByName("init").usage;
 
 function assertSupportedNode() {
   const major = Number.parseInt(process.versions.node.split(".", 1)[0], 10);
@@ -17,6 +21,13 @@ function assertSupportedNode() {
   }
 }
 
+function isInteractive(options = {}) {
+  if (typeof options.interactive === "boolean") {
+    return options.interactive;
+  }
+  return Boolean(options.stdin?.isTTY ?? input.isTTY);
+}
+
 function readFlag(argv, index) {
   const argument = argv[index];
   const equalsIndex = argument.indexOf("=");
@@ -61,25 +72,28 @@ export function parseInitArgs(argv) {
     index += 1;
   }
 
-  if (positional.length !== 1) {
+  if (positional.length > 1) {
     throw new Error(`Usage: ${initUsage}`);
   }
 
-  for (const required of ["product-id", "agent-api-name", "domain"]) {
-    if (!flags[required]) {
-      throw new Error(`Missing required option: --${required}\nUsage: ${initUsage}`);
-    }
-  }
-
   return {
-    targetDir: path.resolve(positional[0]),
-    displayName: flags.name || path.basename(path.resolve(positional[0])),
-    productId: flags["product-id"],
-    agentApiName: flags["agent-api-name"],
-    domain: flags.domain,
+    directory: positional[0] || null,
+    displayName: flags.name || null,
+    productId: flags["product-id"] || null,
+    agentApiName: flags["agent-api-name"] || null,
+    domain: flags.domain || null,
   };
 }
 
+function missingInitFields(parsed) {
+  const missing = [];
+  if (!parsed.directory) missing.push("directory");
+  if (!parsed.productId) missing.push("product-id");
+  if (!parsed.agentApiName) missing.push("agent-api-name");
+  if (!parsed.domain) missing.push("domain");
+  return missing;
+}
+
 function toPackageName(value) {
   return value
     .trim()
@@ -142,6 +156,111 @@ function normalizeTarget(value) {
   };
 }
 
+async function ask(question, options = {}) {
+  if (typeof options.ask === "function") {
+    return options.ask(question);
+  }
+
+  const rl = readline.createInterface({
+    input: options.stdin || input,
+    output: options.stdout || output,
+  });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+async function askRequired(label, options = {}) {
+  while (true) {
+    const value = await ask(`${label}: `, options);
+    if (value) {
+      return value;
+    }
+    (options.log || console.log)(`${label} is required.`);
+  }
+}
+
+async function askUntilValid(label, validate, options = {}) {
+  while (true) {
+    const value = await askRequired(label, options);
+    try {
+      return validate(value);
+    } catch (error) {
+      (options.log || console.log)(error instanceof Error ? error.message : String(error));
+    }
+  }
+}
+
+async function promptForMissingFields(parsed, options = {}) {
+  const next = { ...parsed };
+  const log = options.log || console.log;
+
+  if (!next.directory) {
+    const value = await ask(`Project directory [${defaultDirectory}]: `, options);
+    next.directory = value || defaultDirectory;
+  }
+
+  if (!next.productId) {
+    next.productId = await askUntilValid("Product ID", validateProductId, options);
+  }
+
+  if (!next.agentApiName) {
+    next.agentApiName = await askUntilValid(
+      "Agent API name",
+      (value) => validateIdentifier(value, "Agent API name"),
+      options,
+    );
+  }
+
+  if (!next.domain) {
+    next.domain = await askUntilValid(
+      "Domain",
+      (value) => {
+        normalizeTarget(value);
+        return value.trim();
+      },
+      options,
+    );
+  }
+
+  if (!next.displayName) {
+    const defaultName = path.basename(path.resolve(next.directory));
+    const value = await ask(`Display name [${defaultName}]: `, options);
+    next.displayName = value || defaultName;
+  }
+
+  log("");
+  return next;
+}
+
+function finalizeInitConfig(parsed) {
+  const directory = parsed.directory;
+  if (!directory) {
+    throw new Error(`Missing required option: directory\nUsage: ${initUsage}`);
+  }
+
+  for (const [key, label] of [
+    ["productId", "product-id"],
+    ["agentApiName", "agent-api-name"],
+    ["domain", "domain"],
+  ]) {
+    if (!parsed[key]) {
+      throw new Error(`Missing required option: --${label}\nUsage: ${initUsage}`);
+    }
+  }
+
+  const targetDir = path.resolve(directory);
+  return {
+    targetDir,
+    displayName: parsed.displayName || path.basename(targetDir),
+    productId: parsed.productId,
+    agentApiName: parsed.agentApiName,
+    domain: parsed.domain,
+  };
+}
+
 function readHarnessVersion(root) {
   const manifestPath = path.join(root, "package.json");
   const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
@@ -281,21 +400,76 @@ export function scaffoldProject(config, options = {}) {
   };
 }
 
-export function runInit(argv, options = {}) {
+function runInstall(targetDir, options = {}) {
+  const install = options.install || ((cwd) => {
+    execFileSync("npm", ["install", "--ignore-scripts"], {
+      cwd,
+      stdio: "inherit",
+      env: process.env,
+    });
+  });
+  install(targetDir);
+}
+
+function isAffirmative(value) {
+  const normalized = value.trim().toLowerCase();
+  return normalized === "" || normalized === "y" || normalized === "yes";
+}
+
+async function maybeInstallDependencies(targetDir, options = {}) {
+  if (!isInteractive(options)) {
+    return false;
+  }
+
+  if (options.autoInstall === true) {
+    runInstall(targetDir, options);
+    return true;
+  }
+
+  if (options.autoInstall === false) {
+    return false;
+  }
+
+  const answer = await ask("Run npm install --ignore-scripts now? [Y/n] ", options);
+  if (!isAffirmative(answer)) {
+    return false;
+  }
+
+  runInstall(targetDir, options);
+  return true;
+}
+
+export async function runInit(argv, options = {}) {
   assertSupportedNode();
-  const config = parseInitArgs(argv);
+  let parsed = parseInitArgs(argv);
+  const missing = missingInitFields(parsed);
+
+  if (missing.length > 0) {
+    if (!isInteractive(options)) {
+      const label = missing[0] === "directory" ? "directory" : `--${missing[0]}`;
+      throw new Error(`Missing required option: ${label}\nUsage: ${initUsage}`);
+    }
+    parsed = await promptForMissingFields(parsed, options);
+  } else if (!parsed.displayName) {
+    parsed.displayName = path.basename(path.resolve(parsed.directory));
+  }
+
+  const config = finalizeInitConfig(parsed);
   const result = scaffoldProject(config, options);
   const log = options.log || console.log;
+  const installed = await maybeInstallDependencies(result.targetDir, options);
 
   log(`Created Foldspace project at ${result.targetDir}`);
   log(`Using @foldspace_npm/harness ${result.harnessVersion}`);
   log("");
   log("Next steps:");
   log(`  cd ${result.targetDir}`);
-  log("  npm install --ignore-scripts");
+  if (!installed) {
+    log("  npm install --ignore-scripts");
+  }
   log("  npm run build");
   log("  npm run inject");
   log("  npm run attach");
 
-  return result;
+  return { ...result, installed };
 }

package/src/project-config.mjs

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function readProjectConfig(projectDir) {
+  const configPath = path.join(projectDir, "foldspace.dev.json");
+  if (!fs.existsSync(configPath)) {
+    throw new Error("foldspace.dev.json not found");
+  }
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `foldspace.dev.json is invalid: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  return config;
+}
+
+export function resolveConfiguredTarget(config, requestedTarget) {
+  const targetName = requestedTarget || config?.defaultTarget;
+  if (typeof targetName !== "string" || !targetName) {
+    throw new Error("foldspace.dev.json must define defaultTarget");
+  }
+  const target = config?.targets?.[targetName];
+  if (!target || typeof target !== "object") {
+    throw new Error(`target "${targetName}" is not defined`);
+  }
+  for (const field of ["productId", "agentApiName"]) {
+    if (typeof target[field] !== "string" || !target[field]) {
+      throw new Error(`target "${targetName}" must define ${field}`);
+    }
+  }
+  return { targetName, target };
+}

package/src/protocol.mjs

@@ -0,0 +1,181 @@
+// Browser-safe request/result contracts shared by local CDP and future
+// extension adapters. This module describes evidence; it does not inspect a
+// page or select a transport.
+export const HARNESS_PROTOCOL_VERSION = 1;
+
+export const CAPABILITIES = Object.freeze({
+  PAGE_EVALUATE: "page.evaluate",
+  PAGE_MUTATE: "page.mutate",
+  ARTIFACT_LOAD: "artifact.load",
+  CDP: "browser.cdp",
+});
+
+export const ERROR_CODES = Object.freeze({
+  INVALID_REQUEST: "INVALID_REQUEST",
+  CAPABILITY_DISABLED: "CAPABILITY_DISABLED",
+  SDK_NOT_FOUND: "SDK_NOT_FOUND",
+  AGENT_NOT_FOUND: "AGENT_NOT_FOUND",
+  REGISTRATION_MISMATCH: "REGISTRATION_MISMATCH",
+  DIAGNOSTIC_FAILED: "DIAGNOSTIC_FAILED",
+  TIMEOUT: "TIMEOUT",
+  EVIDENCE_LIMIT: "EVIDENCE_LIMIT",
+  TRANSPORT_ERROR: "TRANSPORT_ERROR",
+});
+
+export const LIFECYCLE_OPERATIONS = Object.freeze([
+  "prepare_page",
+  "load_artifact",
+  "inspect_registration",
+  "run_diagnostic",
+  "cleanup",
+]);
+
+export const PROTOCOL_LIMITS = Object.freeze({
+  maxRequestBytes: 16 * 1024,
+  maxResultBytes: 64 * 1024,
+  maxIdentifierLength: 128,
+});
+
+const identifierPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function jsonByteLength(value, label) {
+  let json;
+  try {
+    json = JSON.stringify(value);
+  } catch {
+    throw new TypeError(`${label} must be JSON serializable`);
+  }
+  if (json === undefined) {
+    throw new TypeError(`${label} must be JSON serializable`);
+  }
+  return new TextEncoder().encode(json).length;
+}
+
+function assertIdentifier(value, label) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > PROTOCOL_LIMITS.maxIdentifierLength ||
+    !identifierPattern.test(value)
+  ) {
+    throw new TypeError(
+      `${label} must be a non-empty identifier of at most ${PROTOCOL_LIMITS.maxIdentifierLength} characters`,
+    );
+  }
+}
+
+export function createDiagnosticRequest({
+  id,
+  name,
+  args = {},
+  timeoutMs = 10_000,
+}) {
+  assertIdentifier(id, "Diagnostic request id");
+  assertIdentifier(name, "Diagnostic name");
+  if (!isRecord(args)) {
+    throw new TypeError("Diagnostic args must be an object");
+  }
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000) {
+    throw new TypeError("Diagnostic timeoutMs must be an integer between 1 and 60000");
+  }
+
+  const request = {
+    protocolVersion: HARNESS_PROTOCOL_VERSION,
+    id,
+    name,
+    args,
+    timeoutMs,
+  };
+  if (jsonByteLength(request, "Diagnostic request") > PROTOCOL_LIMITS.maxRequestBytes) {
+    throw new RangeError("Diagnostic request exceeds the protocol size limit");
+  }
+  return request;
+}
+
+export function diagnosticSuccess(request, result, metadata = {}) {
+  if (!isRecord(metadata)) {
+    throw new TypeError("Diagnostic metadata must be an object");
+  }
+  const response = {
+    protocolVersion: HARNESS_PROTOCOL_VERSION,
+    id: request.id,
+    name: request.name,
+    ok: true,
+    result,
+    metadata,
+  };
+  if (jsonByteLength(response, "Diagnostic result") > PROTOCOL_LIMITS.maxResultBytes) {
+    return diagnosticFailure(request, {
+      code: ERROR_CODES.EVIDENCE_LIMIT,
+      message: "Diagnostic result exceeded the protocol size limit",
+    });
+  }
+  return response;
+}
+
+export function diagnosticFailure(request, error) {
+  const code = Object.values(ERROR_CODES).includes(error?.code)
+    ? error.code
+    : ERROR_CODES.DIAGNOSTIC_FAILED;
+  const message =
+    typeof error?.message === "string" && error.message.trim()
+      ? error.message.slice(0, 2_000)
+      : "Diagnostic failed";
+
+  return {
+    protocolVersion: HARNESS_PROTOCOL_VERSION,
+    id: request.id,
+    name: request.name,
+    ok: false,
+    error: { code, message },
+  };
+}
+
+export function createLifecycleResult({
+  operation,
+  ok,
+  state,
+  error,
+  details = {},
+}) {
+  if (!LIFECYCLE_OPERATIONS.includes(operation)) {
+    throw new TypeError(`Unknown lifecycle operation: ${operation}`);
+  }
+  if (typeof ok !== "boolean") {
+    throw new TypeError("Lifecycle ok must be a boolean");
+  }
+  assertIdentifier(state, "Lifecycle state");
+  if (!isRecord(details)) {
+    throw new TypeError("Lifecycle details must be an object");
+  }
+
+  const result = {
+    protocolVersion: HARNESS_PROTOCOL_VERSION,
+    operation,
+    ok,
+    state,
+    details,
+    ...(ok
+      ? {}
+      : {
+          error: {
+            code: Object.values(ERROR_CODES).includes(error?.code)
+              ? error.code
+              : ERROR_CODES.TRANSPORT_ERROR,
+            message:
+              typeof error?.message === "string" && error.message.trim()
+                ? error.message.slice(0, 2_000)
+                : "Lifecycle operation failed",
+          },
+        }),
+  };
+
+  if (jsonByteLength(result, "Lifecycle result") > PROTOCOL_LIMITS.maxResultBytes) {
+    throw new RangeError("Lifecycle result exceeds the protocol size limit");
+  }
+  return result;
+}

package/src/session-summary.mjs

@@ -0,0 +1,133 @@
+import { ACTION_LOG_PREFIX } from "./action-observer.mjs";
+
+function normalizeConsoleText(value) {
+  return String(value ?? "")
+    .replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/gi, "<id>")
+    .replace(/\b(?:bearer\s+)?[A-Za-z0-9_-]{40,}\b/gi, "<redacted>")
+    .replace(/([?&](?:token|key|secret|code)=)[^&\s]+/gi, "$1<redacted>")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 1_000);
+}
+
+export function parseActionObservation(text) {
+  const value = String(text ?? "");
+  if (!value.startsWith(`${ACTION_LOG_PREFIX} `)) return null;
+  try {
+    const parsed = JSON.parse(value.slice(ACTION_LOG_PREFIX.length + 1));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function formatActionObservation(event) {
+  const action = event.actionName ? ` ${event.actionName}` : "";
+  const duration = Number.isFinite(event.durationMs)
+    ? ` ${event.durationMs}ms`
+    : "";
+  const keys =
+    Array.isArray(event.parameterKeys) && event.parameterKeys.length
+      ? ` keys=[${event.parameterKeys.join(",")}]`
+      : "";
+  if (event.phase === "registration") {
+    const count = Array.isArray(event.actionNames)
+      ? event.actionNames.length
+      : 0;
+    return `[actions] local artifact ${event.status} (${count} action${count === 1 ? "" : "s"})`;
+  }
+  return `[actions] ${event.source}:${event.phase}${action} ${event.status}${duration}${keys}`;
+}
+
+export function createSessionCollector({
+  maxErrorGroups = 50,
+  maxActionEvents = 200,
+} = {}) {
+  const errorGroups = new Map();
+  const actionEvents = [];
+  let droppedErrorGroups = 0;
+  let droppedActionEvents = 0;
+
+  function recordConsole({ level = "log", text = "" } = {}) {
+    const action = parseActionObservation(text);
+    if (action) {
+      if (actionEvents.length >= maxActionEvents) {
+        actionEvents.shift();
+        droppedActionEvents += 1;
+      }
+      actionEvents.push(action);
+      return action;
+    }
+
+    const normalized = normalizeConsoleText(text);
+    const normalizedLevel = String(level).toLowerCase();
+    const isFailure =
+      normalizedLevel === "error" ||
+      normalizedLevel === "warning" ||
+      normalizedLevel === "warn" ||
+      /\b(?:error|failed|failure|status\s+[45]\d\d)\b/i.test(normalized);
+    if (!normalized || !isFailure) return null;
+
+    const key = `${normalizedLevel}:${normalized}`;
+    const existing = errorGroups.get(key);
+    if (existing) {
+      existing.count += 1;
+    } else if (errorGroups.size < maxErrorGroups) {
+      errorGroups.set(key, {
+        level: normalizedLevel,
+        text: normalized,
+        count: 1,
+      });
+    } else {
+      droppedErrorGroups += 1;
+    }
+    return null;
+  }
+
+  function snapshot() {
+    return {
+      actionEvents: actionEvents.map((event) => ({ ...event })),
+      errorGroups: Array.from(errorGroups.values()).map((group) => ({
+        ...group,
+      })),
+      droppedActionEvents,
+      droppedErrorGroups,
+    };
+  }
+
+  return { recordConsole, snapshot };
+}
+
+export function formatSessionSummary(snapshot) {
+  const lines = [];
+  if (snapshot.actionEvents.length) {
+    lines.push(
+      `Action observations (${snapshot.actionEvents.length}${
+        snapshot.droppedActionEvents
+          ? `, ${snapshot.droppedActionEvents} older dropped`
+          : ""
+      }):`,
+    );
+    for (const event of snapshot.actionEvents.slice(-20)) {
+      lines.push(`  ${formatActionObservation(event)}`);
+    }
+  }
+  if (snapshot.errorGroups.length) {
+    lines.push(
+      `Page failures (${snapshot.errorGroups.length} group${
+        snapshot.errorGroups.length === 1 ? "" : "s"
+      }):`,
+    );
+    for (const group of snapshot.errorGroups) {
+      lines.push(
+        `  [${group.level} x${group.count}] ${group.text}`,
+      );
+    }
+    if (snapshot.droppedErrorGroups) {
+      lines.push(
+        `  ${snapshot.droppedErrorGroups} additional failure group(s) omitted`,
+      );
+    }
+  }
+  return lines.join("\n");
+}

package/templates/agent-starter/CLAUDE.md

@@ -8,10 +8,13 @@ changes there.
 
 ## Before building
 
-1. Connect Product MCP and verify that `list_agents` works.
-2. Inspect the selected agent with `get_agent_settings`, `list_actions`, and
+1. Run `npx foldspace help --json` before an unfamiliar harness operation.
+   Treat its risk, prerequisites, effects, and next-step fields as the current
+   CLI contract.
+2. Connect Product MCP and verify that `list_agents` works.
+3. Inspect the selected agent with `get_agent_settings`, `list_actions`, and
    `list_task_agents`.
-3. Use `discover_actions` to identify candidate experiences, then let the user
+4. Use `discover_actions` to identify candidate experiences, then let the user
    choose what to build.
 
 ## Build workflow
@@ -51,12 +54,18 @@ npm run attach
 ```
 
 `inject` launches an isolated Chrome profile and records its debug port.
-`attach` loads the SDK and the local `dist/index.js` bundle. Use
-`npm run attach -- --bootstrap` when the target page does not already embed the
-Foldspace SDK.
+It does not generate or load an application extension. `attach` prepares the
+page and loads the local `dist/index.js` bundle through CDP.
 
-The attach log must report `actions attached: N` before treating the page as
-running local action code.
+Use the default swap only when the page already has the configured product and
+agent. Use `--bootstrap` only when the page has no Foldspace SDK, and
+`--replace` when it embeds a different product or agent, or when an SDK is
+present without the configured agent.
+
+The attach log must report `inspect_registration:registration_ok` before
+treating the page as registered. Prove the experience through the visible agent
+and require both an SDK action callback and local execute/render evidence; do
+not invoke the handler directly.
 
 ## Verification gates
 
@@ -76,9 +85,23 @@ Do not report success without all six:
 - `agent/constants.ts` — agent, product, and domain identifiers
 - `agent/utils.ts` — Foldspace agent lookup
 - `foldspace.dev.json` — local harness target configuration
+- `docs/` — optional coding-agent learnings; create on demand
 
 Do not introduce another bundler or bundle format.
 
+## Agent learnings
+
+Use `docs/` to record durable, repository-specific lessons so later sessions do
+not repeat the same mistakes.
+
+- Before similar work, read any relevant notes already in `docs/`.
+- After non-obvious discoveries, add a short note covering verified gotchas,
+  failed approaches, design rationale, or useful verification commands.
+- Keep notes concise and evidence-based. Create `docs/` when the first note is
+  useful; do not leave an empty directory.
+- Do not store secrets, cookies, HAR files, browser storage, or other transient
+  session data in `docs/`.
+
 ## Safety
 
 - Do not commit secrets, cookies, HAR files, browser storage, or