@foldspace_npm/harness 0.1.10 → 0.1.12

package/recipes/pick-from-a-list/fixtures/projects.empty-account.json

@@ -0,0 +1,4 @@
+{
+  "items": [],
+  "total": 0
+}

package/recipes/pick-from-a-list/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Pick from a list",
+  "level": "L2",
+  "family": "ask-the-user",
+  "kind": "action",
+  "action": "choose_project",
+  "entry": "agent/actions/choose_project.ts",
+  "outcome": "A clickable list, shown only when the user has to choose",
+  "provenBy": 1
+}

package/recipes/swap-the-login-method/README.md

@@ -0,0 +1,40 @@
+# Swap the login method
+
+The harness's `apiFetch` sends `Authorization: Bearer <token>`. That fits some
+apps. **Three production builds, three different schemes:**
+
+| What the app's own requests carried | Builds | Use |
+|---|---|---|
+| `Authorization: Bearer`, token in a cookie or `localStorage`, plus a fixed API-key header | 1 | the default `apiFetch`, with the extra header passed in `init.headers` |
+| A **custom header** holding a session id read from `localStorage` | 1 | `agent/utils.ts` here |
+| **Cookies** — `credentials: "include"` — and no token at all | 1 | `variants/utils.cookies.ts` |
+
+**Observe which one the app uses before choosing.** Read it off a request the
+page already made. Never guess, and never reach for a public developer API
+because the browser session was missing.
+
+## Adapt it
+
+Copy the variant you need over your project's `agent/utils.ts`. Actions keep
+importing from `../utils`, so nothing else changes — that is what the seam is
+for.
+
+| In the file | Change |
+|---|---|
+| `SESSION_STORAGE_KEY`, `SESSION_HEADER` | The key and header name you **observed** |
+| The cookies variant's extra headers | Only what you observed the app sending. One build needed `x-requested-with`; most do not |
+| `API_BASE` in `constants.ts` | For a same-origin app, the app's own origin. Empty stays a failure on purpose, so a guessed host cannot look like success |
+
+## What those builds learned the hard way
+
+- **Keep the failure reasons.** Replace the transport, not what a 401 or a 404
+  means: `httpFailure` and `networkFailure` are exported for exactly this, so a
+  custom `apiFetch` still returns `signed_out`, `not_found`, `rate_limited`.
+  Hand-rolled versions turned every failure into "unexpected error", or a
+  missing session into an empty list.
+- **Tokens are stored three ways** — raw, JSON-encoded (wrapped in quotes), or
+  inside an object. Strip the quotes; one app switched between the first two.
+- **With cookies there is no token to check first**, so "signed out" is only
+  known from the 401. Let it through as `signed_out` instead of pre-empting it.
+- **Do not `export *`** alongside your own `apiFetch` — name what you re-export,
+  so the default cannot come back by accident.

package/recipes/swap-the-login-method/agent/utils.ts

@@ -0,0 +1,73 @@
+// agent/utils.ts for an app that authenticates with a CUSTOM HEADER holding a
+// session id from localStorage — not `Authorization: Bearer`.
+//
+// Only the transport is replaced. What a 401, a 404 or a 429 means still comes
+// from the harness, so actions and renderFailure behave exactly the same.
+
+import { configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
+import { AGENT_API_NAME, API_BASE } from "./constants";
+
+configure({ agentApiName: AGENT_API_NAME, apiBase: API_BASE });
+
+/** The localStorage key and the header name you OBSERVED on a real request. */
+const SESSION_STORAGE_KEY = "__observe_me_session";
+const SESSION_HEADER = "__observe-me-session";
+
+function readSession(): string | null {
+  const raw = window.localStorage.getItem(SESSION_STORAGE_KEY);
+  // Apps store it raw or JSON-encoded; strip the quotes either way.
+  return raw ? raw.replace(/^"|"$/g, "") || null : null;
+}
+
+export async function apiFetch<T = unknown>(
+  path: string,
+  init: RequestInit = {},
+  timeoutMs = 15_000,
+): Promise<ApiResult<T>> {
+  if (!API_BASE) {
+    return { ok: false, status: 0, reason: "config", error: "API_BASE is not set — capture the app's XHR first." };
+  }
+  const session = readSession();
+  if (!session) return { ok: false, status: 401, reason: "signed_out", error: "Not signed in." };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${API_BASE}${path}`, {
+      ...init,
+      signal: controller.signal,
+      headers: { "Content-Type": "application/json", [SESSION_HEADER]: session, ...(init.headers ?? {}) },
+    });
+    const text = await res.text();
+    let parsed: unknown = text;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      /* non-JSON; keep the raw text */
+    }
+    if (!res.ok) return httpFailure(res, "That request could not be completed.");
+    return { ok: true, status: res.status, data: parsed as T };
+  } catch (error) {
+    return networkFailure(error, "Request timed out.", "Could not reach the server.");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Everything else still comes from the harness. Named, NOT `export *` — that
+// would put the default apiFetch back next to this one.
+export {
+  getAgent,
+  armAllInstances,
+  rankBy,
+  redact,
+  parseJwt,
+  publicFetch,
+  mapWithConcurrency,
+  renderLoading,
+  renderEmpty,
+  renderError,
+  renderFatal,
+  renderFailure,
+} from "@foldspace_npm/harness/runtime";
+export type { ApiResult, ApiFailure, FailureReason, ViewHost } from "@foldspace_npm/harness/runtime";

package/recipes/swap-the-login-method/fixtures/anything.ok.json

@@ -0,0 +1,8 @@
+{
+  "items": [
+    {
+      "id": "1",
+      "name": "Alpha"
+    }
+  ]
+}

package/recipes/swap-the-login-method/recipe.json

@@ -0,0 +1,12 @@
+{
+  "title": "Swap the login method",
+  "level": "any",
+  "family": "auth",
+  "kind": "override",
+  "entry": "agent/utils.ts",
+  "variants": [
+    "variants/utils.cookies.ts"
+  ],
+  "outcome": "apiFetch for an app that does not authenticate with a bearer token",
+  "provenBy": 2
+}

package/recipes/swap-the-login-method/variants/utils.cookies.ts

@@ -0,0 +1,64 @@
+// agent/utils.ts for an app that authenticates with COOKIES — no token to read.
+// Copy this over agent/utils.ts.
+//
+// There is nothing to check before the request, so "signed out" is only known
+// from the 401. It comes back as `signed_out` like any other.
+
+import { configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
+import { AGENT_API_NAME, API_BASE } from "./constants";
+
+configure({ agentApiName: AGENT_API_NAME, apiBase: API_BASE });
+
+export async function apiFetch<T = unknown>(
+  path: string,
+  init: RequestInit = {},
+  timeoutMs = 15_000,
+): Promise<ApiResult<T>> {
+  if (!API_BASE) {
+    return { ok: false, status: 0, reason: "config", error: "API_BASE is not set — capture the app's XHR first." };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${API_BASE}${path}`, {
+      ...init,
+      credentials: "include",
+      signal: controller.signal,
+      // Add only what you OBSERVED the app sending. One build needed
+      // `x-requested-with: XMLHttpRequest`; most do not.
+      headers: { accept: "application/json", "Content-Type": "application/json", ...(init.headers ?? {}) },
+    });
+    const text = await res.text();
+    let parsed: unknown = text;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      /* non-JSON; keep the raw text */
+    }
+    if (!res.ok) return httpFailure(res, "That request could not be completed.");
+    return { ok: true, status: res.status, data: parsed as T };
+  } catch (error) {
+    return networkFailure(error, "Request timed out.", "Could not reach the server.");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Everything else still comes from the harness. Named, NOT `export *` — that
+// would put the default apiFetch back next to this one.
+export {
+  getAgent,
+  armAllInstances,
+  rankBy,
+  redact,
+  parseJwt,
+  publicFetch,
+  mapWithConcurrency,
+  renderLoading,
+  renderEmpty,
+  renderError,
+  renderFatal,
+  renderFailure,
+} from "@foldspace_npm/harness/runtime";
+export type { ApiResult, ApiFailure, FailureReason, ViewHost } from "@foldspace_npm/harness/runtime";

package/recipes/who-is-the-user/README.md

@@ -0,0 +1,56 @@
+# Who is the user — L0
+
+L0 is not "the agent appears". It is the agent appearing **and** Foldspace
+knowing who it is talking to. Without `identify`, every conversation, every
+analytics row and every segment is anonymous.
+
+**Proven by 4 production builds**, which found the identity in three different
+places — so look before you assume:
+
+| Where the signed-in user was found | Builds |
+|---|---|
+| Claims inside the app's own session token (user id, email, organisation id) | 2 |
+| A user object the app keeps in `localStorage` | 1 |
+| A call to the app's own account endpoint, cached for the page | 1 |
+
+## Adapt it
+
+| In `agent/identify.ts` | Change |
+|---|---|
+| `SessionClaims` | The claim names you **observed** in the token. Two builds, two spellings |
+| `/__observe_me/profile` and `Profile` | The endpoint that describes **the signed-in user** — see the trap below |
+| `subscription.id` | Whatever groups colleagues: organisation, account, workspace |
+
+Then call `identifyUser()` from the bundle's entry point:
+
+```ts
+// agent/actions/index.ts — last line
+import { identifyUser } from "../identify";
+identifyUser();
+```
+
+Custom attributes (a plan name, a sign-up date) only land if they were created
+first in **Settings → Attribute Settings**; send them under their API Name.
+
+## What those builds learned the hard way
+
+- **Claim the "already done" flag before the first `await`.** Checking and then
+  awaiting lets every concurrent load past the check — three bundle loads
+  produced three `identify` calls.
+- **Keep the flag on `window`, not in module scope.** A bundle evaluated twice
+  gets two module scopes and identifies twice.
+- **An account endpoint may describe the account, not the person.** One returned
+  the billing contact's name and email for whoever was signed in — which labels
+  every colleague as the same person. Read the person from the session; read
+  only the account id from the account.
+- **No id means stay anonymous.** A wrong id silently merges or splits real
+  people in the analytics. Never invent one.
+- **A failed identify must not break the agent.** Every failure is silent to the
+  user, and releases the flag so a later load can try again.
+- **Hide the agent until identify resolves, with a timeout** — and on a page
+  with no signed-in user (the login page), do not show it at all.
+- **This is unsigned.** Anyone can call `foldspace.identify` from a console.
+  Signing has to come from the customer's backend
+  (<https://docs.foldspace.ai/security/overview/>); until then treat the
+  analytics as indicative. And if the customer's own page ever calls
+  `identify`, delete this file — theirs runs earlier and knows more.

package/recipes/who-is-the-user/agent/identify.ts

@@ -0,0 +1,89 @@
+// Tell Foldspace who the signed-in user is — once, when the SDK is ready.
+// Context shape: https://docs.foldspace.ai/start/user-context/
+//
+// UNSIGNED: anyone can call foldspace.identify from a console. Signing has to
+// come from the customer's backend. See this recipe's README.
+
+import { apiFetch, getAuthToken, parseJwt, redact } from "./utils";
+
+/** Claims you OBSERVED in the app's session token. Replace these names. */
+type SessionClaims = {
+  sub?: string | number;
+  email?: string;
+};
+
+/**
+ * The endpoint that describes THE SIGNED-IN USER. Check it against a second
+ * account member before trusting it: one app's account endpoint returned the
+ * billing contact for everyone.
+ */
+type Profile = {
+  firstName?: string | null;
+  lastName?: string | null;
+  role?: string | null;
+  organizationId?: string | number | null;
+};
+
+// On window, not in module scope: a bundle evaluated twice on one page gets two
+// module scopes, and would identify twice.
+const IDENTIFIED_FLAG = "__foldspace_identified__";
+
+const claimed = (): boolean => (window as any)[IDENTIFIED_FLAG] === true;
+const claim = (): void => void ((window as any)[IDENTIFIED_FLAG] = true);
+const release = (): void => void ((window as any)[IDENTIFIED_FLAG] = false);
+
+function sessionIdentity(): { id: string; email: string | null } | null {
+  const token = getAuthToken();
+  const claims = token ? parseJwt<SessionClaims>(token) : null;
+  const raw = claims?.sub;
+  const id = typeof raw === "number" ? String(raw) : typeof raw === "string" ? raw.trim() : "";
+  if (!id) return null;
+  const email = typeof claims?.email === "string" && claims.email.includes("@") ? claims.email.trim() : null;
+  return { id, email };
+}
+
+/** Every failure is silent to the user: an unidentified session is a degraded record, never a broken agent. */
+export function identifyUser(): void {
+  const foldspace = (window as any).foldspace;
+  if (typeof foldspace !== "function" || typeof foldspace.identify !== "function") return;
+  if (claimed()) return;
+
+  foldspace("when", "ready", async () => {
+    if (claimed()) return;
+    // Claimed BEFORE the first await, or every concurrent load gets past the check.
+    claim();
+
+    try {
+      // No id means anonymous. Never invent one: a wrong id merges or splits
+      // real people in the analytics.
+      const who = sessionIdentity();
+      if (!who) {
+        release();
+        return;
+      }
+
+      const user: Record<string, unknown> = { id: who.id };
+      if (who.email) user.email = who.email;
+      const context: Record<string, unknown> = { user };
+
+      const profile = await apiFetch<Profile>("/__observe_me/profile");
+      if (profile.ok) {
+        const name = [profile.data?.firstName, profile.data?.lastName].filter(Boolean).join(" ");
+        if (name) user.name = name;
+        if (profile.data?.role) user.role = profile.data.role;
+        // One subscription, many users: whatever groups colleagues together.
+        const org = profile.data?.organizationId;
+        if (org !== null && org !== undefined && String(org) !== "") {
+          context.subscription = { id: String(org) };
+        }
+      }
+
+      foldspace.identify(context);
+      // Never log the identity itself — only that it fired.
+      console.debug("[foldspace] identified", redact(who.id), user.name ? "with name" : "id only");
+    } catch (error) {
+      release();
+      console.warn("[foldspace] identify skipped:", error);
+    }
+  });
+}

package/recipes/who-is-the-user/fixtures/profile.ok.json

@@ -0,0 +1,6 @@
+{
+  "firstName": "Dana",
+  "lastName": "Reyes",
+  "role": "admin",
+  "organizationId": 4410
+}

package/recipes/who-is-the-user/recipe.json

@@ -0,0 +1,9 @@
+{
+  "title": "Who is the user",
+  "level": "L0",
+  "family": "user-context",
+  "kind": "startup",
+  "entry": "agent/identify.ts",
+  "outcome": "Foldspace knows who is signed in, once, when the SDK is ready",
+  "provenBy": 4
+}

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",
@@ -272,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"],
@@ -342,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),

package/src/runtime/config.ts

@@ -26,7 +26,7 @@ export interface AuthSource {
  * wrong place.
  */
 export interface RuntimeConfig {
-  /** Foldspace agent apiName, e.g. `joist-agent`. */
+  /** Foldspace agent apiName, e.g. `acme-agent`. */
   agentApiName: string;
   /**
    * Prefix for `apiFetch` / `apiFetchBinary`. Include an explicit port if the