@foldspace_npm/harness 0.1.28 → 0.1.30

package/CLAUDE.md

@@ -696,6 +696,8 @@ Each of these cost a real build.
   `AUTH_SOURCE` and `LOAD_MODE`
 - `agent/utils.ts` — configures the harness runtime and re-exports it. **The
   only import surface for actions.**
+- `agent/runtime/` — a code project only: this harness's runtime, which every
+  build keeps current. Never edit it.
 - `agent/views/` — branded cards
 - `docs/app-profile.md` — what is known about this app, and how it was established
 - `foldspace.dev.json` — local harness target configuration
@@ -766,10 +768,17 @@ README's **Adapt it** table lists to what you observed.
 package: Foldspace builds the published bundle with no `node_modules`, so a
 package import passes every gate in this manual and then fails on publish.
 Import the helpers the way the project's own `agent/utils.ts` does - from
-`./runtime` - in a recipe file you copy too. A project with an `agent/utils/`
-folder has its own helpers instead: change the sign-in there, and never add an
-`agent/utils.ts` beside it, which would win the import. Without a code project,
-the package import is right.
+`./runtime` - in a recipe file you copy too. `agent/runtime/` is this harness's
+runtime, copied in for that reason. A build that changes files there names
+them: save exactly those files in a save of their own as soon as the agent is
+on their page. Say you are bringing their project up to date - no need to ask,
+it changes nothing for their users. If their account cannot save, carry on.
+Never edit a file there: the next build puts the harness's copy back. To change
+how a helper behaves, define it in `agent/utils.ts` and export it from there in
+place of the runtime's. A project with an `agent/utils/` folder has its own
+helpers instead: change the sign-in there, and never add an `agent/utils.ts`
+beside it, which would win the import. Without a code project, the package
+import is right.
 
 ## Safety
 

package/README.md

@@ -28,7 +28,7 @@ constraint this package exists to protect.
 - `agent/actions/*` and `agent/api/*` — a handler is `fetch` plus `runTask`,
   nothing more. Actions built in one track run unmodified in the other.
 - `agent/utils.ts` — configures and re-exports `@foldspace_npm/harness/runtime`
-- `foldspace build` — esbuild → `dist/index.js`
+- `foldspace build` — esbuild → `dist/index.js`. In a code project, it first makes `agent/runtime/` match this harness's runtime (never rolling back a copy of a newer runtime; the version is in `src/runtime/VERSION`) and names every file it wrote
 - `foldspace deploy` (Foldspace-internal) - uploads `dist/index.js` to `agent/actions/<env>/<productId>/<agentApiName>`
 - fixtures and tests
 - **the verb interface** below
@@ -225,7 +225,7 @@ v1 flags:
 - **error** `no-static-agent-prompt` - `execute`, a card's `callback` or its `readyState` handing the agent instructions (`directive`, “tell the user”, …)
 - **error** `no-runtask-prompt` — `runTask({ data: { prompt } })` and the same keys; a customer API field named `prompt` is allowed
 - **error** `card-contract` - `awaitUserInput: true` on a view card (its `render` uses no `callback`, `cancel` or `readyState`): the chat panel ignores it, but in headless mode the agent waits for a callback that never comes
-- **error** `no-test-mode-in-bundle` - `armAllInstances(...)`, or `setTestMode(...)` with anything but a literal `false`, anywhere in `agent/`
+- **error** `no-test-mode-in-bundle` - `armAllInstances` used anywhere in `agent/` (called, or handed on to be called later), or `setTestMode(...)` with anything but a literal `false`. A code project's own copy of the runtime in `agent/runtime/` is not refused for the `setTestMode` inside its `armAllInstances`
 - **warning** `card-contract` - any other `awaitUserInput` on a view card, `awaitUserInput` on an input card (not needed), or a `render` that declares `callback`, `cancel` or `readyState` and uses none of them (the SDK treats it as a view card)
 - **warning** `no-emoji` — emoji in handler or `agent/views` string literals
 - **warning** `registry-integrity` — duplicate keys, `{ execute }` not registered, registry value missing `execute`

package/bin/build.ts

@@ -2,7 +2,8 @@ import * as esbuild from "esbuild";
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
-import { lintProject, printLint } from "../src/lint/index.mjs";
+import { bundleTurnsOnTestMode, lintProject, printLint } from "../src/lint/index.mjs";
+import { compareVersions } from "../src/upgrade.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const projectDir = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
@@ -11,6 +12,100 @@ const agentActionsEntry = path.join(projectDir, "agent", "actions", "index.ts");
 
 const watchMode = process.argv.includes("--watch");
 
+// A code project carries its own copy of this harness's runtime in
+// agent/runtime/, because Foldspace builds it with no node_modules. Each build
+// keeps that copy the same as the runtime here, so the harness's fixes reach
+// the project, and names what it wrote so the session saves it.
+// src/runtime/VERSION is the runtime's own version - it changes only when the
+// runtime does - and the copy carries it in agent/runtime/VERSION: a copy of a
+// newer runtime is left alone, so an older harness never rolls it back.
+// Other files there, and links, are left alone too.
+let runtimeSaveLine = "";
+
+function plainFile(file: string): "missing" | "file" | "other" {
+  const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+  if (!stat) return "missing";
+  return stat.isFile() ? "file" : "other";
+}
+
+function sameText(left: string, right: string): boolean {
+  return left.replace(/\r\n/g, "\n") === right.replace(/\r\n/g, "\n");
+}
+
+function refreshRuntimeCopy(): void {
+  const copyDir = path.join(projectDir, "agent", "runtime");
+  const copyStat = fs.lstatSync(copyDir, { throwIfNoEntry: false });
+  if (!copyStat) return;
+  if (copyStat.isSymbolicLink()) {
+    console.log("agent/runtime/ is a link, so this build leaves it as is.\n");
+    return;
+  }
+  if (!copyStat.isDirectory()) return;
+
+  const sourceDir = path.join(__dirname, "..", "src", "runtime");
+  const runtimeVersion = fs.readFileSync(path.join(sourceDir, "VERSION"), "utf8").trim();
+  const versionFile = path.join(copyDir, "VERSION");
+  const versionKind = plainFile(versionFile);
+  if (versionKind === "other") {
+    console.log("agent/runtime/VERSION is not a plain file, so this build leaves agent/runtime/ as is.\n");
+    return;
+  }
+  const copyVersion = versionKind === "file" ? fs.readFileSync(versionFile, "utf8").trim() : "";
+  if (copyVersion && compareVersions(copyVersion, runtimeVersion) > 0) {
+    console.log(
+      `agent/runtime/ is runtime ${copyVersion}, newer than this harness's (${runtimeVersion}), so this build uses it as it is. ` +
+        "Unless the human already said no to upgrading this session, ask them, then run npx foldspace upgrade --yes and build again.\n",
+    );
+    return;
+  }
+
+  const toWrite: Array<[string, string]> = [];
+  for (const name of fs.readdirSync(sourceDir).filter((file) => file.endsWith(".ts")).sort()) {
+    const source = fs.readFileSync(path.join(sourceDir, name), "utf8");
+    const target = path.join(copyDir, name);
+    const kind = plainFile(target);
+    if (kind === "other") continue;
+    if (kind === "file" && sameText(fs.readFileSync(target, "utf8"), source)) continue;
+    toWrite.push([name, source]);
+  }
+  const stamp = copyVersion !== runtimeVersion;
+  if (toWrite.length === 0 && !stamp) return;
+
+  const targets = [...toWrite.map(([name]) => path.join(copyDir, name)), ...(stamp ? [versionFile] : [])];
+  const blocked = targets.filter((file) => {
+    try {
+      fs.accessSync(fs.existsSync(file) ? file : copyDir, fs.constants.W_OK);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+  const named = (files: string[]) => files.map((file) => `agent/runtime/${path.basename(file)}`).join(", ");
+  if (blocked.length > 0) {
+    console.error(`Could not update agent/runtime/: ${named(blocked)} cannot be written. Fix that and build again.`);
+    process.exit(1);
+  }
+  try {
+    for (const [name, source] of toWrite) fs.writeFileSync(path.join(copyDir, name), source);
+    if (stamp) fs.writeFileSync(versionFile, `${runtimeVersion}\n`);
+  } catch (error) {
+    console.error(`Could not update agent/runtime/: ${(error as Error).message}. Fix that and build again.`);
+    process.exit(1);
+  }
+
+  // The same runtime version that no longer matches was changed after it was copied.
+  if (!stamp) {
+    console.log(
+      `${named(toWrite.map(([name]) => name))} did not match this harness's copy of the same runtime; this build put the harness's copy back. ` +
+        "Never edit agent/runtime/ - to change how a helper behaves, define it in agent/utils.ts and export it from there in place of the runtime's.",
+    );
+  }
+  runtimeSaveLine =
+    `Updated to this harness's runtime (${runtimeVersion}): ${named(targets)}. ` +
+    "Save exactly these files to the code project in a save of their own, as soon as the agent is on their page - saving changes nothing for their users.";
+  console.log(`${runtimeSaveLine}\n`);
+}
+
 function gateLint(): void {
   const result = lintProject(projectDir);
   printLint(result);
@@ -19,6 +114,21 @@ function gateLint(): void {
   }
 }
 
+const TEST_MODE_IN_BUNDLE =
+  "foldspace build: the bundle can turn test mode on - it uses `setTestMode` with something other than `false`. " +
+  "Any bundle can ship to production, where test mode would stop real users' conversations being tracked. " +
+  "Remove it: test mode is only `npx foldspace attach --test-mode`, which never touches the bundle. dist/index.js was not kept.";
+
+// The net under lint's no-test-mode-in-bundle: read what was actually built.
+function bundleIsSafe(): boolean {
+  const outfile = path.join(distDir, "index.js");
+  if (!fs.existsSync(outfile)) return true;
+  if (!bundleTurnsOnTestMode(fs.readFileSync(outfile, "utf8"))) return true;
+  fs.rmSync(outfile, { force: true });
+  console.error(TEST_MODE_IN_BUNDLE);
+  return false;
+}
+
 function buildOptions(): esbuild.BuildOptions {
   return {
     entryPoints: [agentActionsEntry],
@@ -45,11 +155,8 @@ function rebuildPlugin(): esbuild.Plugin {
       });
       build.onEnd((result) => {
         const time = new Date().toLocaleTimeString();
-        if (result.errors.length === 0) {
-          console.log(`[${time}] Rebuilt: dist/index.js`);
-        } else {
-          console.log(`[${time}] Error: dist/index.js`);
-        }
+        const built = result.errors.length === 0 && bundleIsSafe();
+        console.log(`[${time}] ${built ? "Rebuilt" : "Error"}: dist/index.js`);
       });
     },
   };
@@ -63,6 +170,8 @@ async function build() {
     process.exit(1);
   }
 
+  refreshRuntimeCopy();
+
   if (!watchMode) {
     gateLint();
   }
@@ -90,8 +199,11 @@ async function build() {
       });
     } else {
       await esbuild.build(buildOptions());
+      if (!bundleIsSafe()) process.exit(1);
       console.log("Built: dist/index.js");
       console.log("\nBuild complete!");
+      // Said again at the end, where a session reading only the last lines sees it.
+      if (runtimeSaveLine) console.log(`\n${runtimeSaveLine}`);
     }
   } catch (error) {
     console.error("Build failed:", error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/src/cli-registry.mjs

@@ -129,11 +129,13 @@ export const CLI_COMMANDS = Object.freeze([
     prerequisites: ["agent/actions/index.ts"],
     effects: [
       "Checks the harness version first: behind prints one line, a withdrawn version refuses to run (FOLDSPACE_SKIP_UPDATE_CHECK=1 skips the check)",
+      "In a code project (agent/runtime/ present), first makes each agent/runtime/*.ts match this harness's runtime and records the runtime's version in agent/runtime/VERSION, naming every file it wrote; a copy of a newer runtime, other files there and links are left alone",
       "Runs foldspace lint first; errors skip bundling",
       "Writes dist/index.js when lint has no errors",
     ],
     next: [
       "First build: `npm run inject` (the human signs in in that window), `npx foldspace observe wait-login`, then `npx foldspace attach --daemon`",
+      "If the build names files in agent/runtime/ to save: save exactly those to the code project, in a save of their own, once the agent is on their page",
       "Rebuild while attach runs: `npx foldspace attach --stop`, then `npx foldspace attach --daemon` with the flags it ran with (`--bootstrap`, `--replace`, `--test-mode`) - a running attach keeps the actions it loaded",
     ],
   }),

package/src/lint/index.mjs

@@ -3,6 +3,8 @@ import path from "node:path";
 import { listSourceFiles, parseFile, shouldSkipActionFile } from "./ast.mjs";
 import { lintActionFile, lintViewsFile, ruleNoTestModeInBundle, ruleRegistryIntegrity } from "./rules.mjs";
 
+export { bundleTurnsOnTestMode } from "./rules.mjs";
+
 export const LINT_SCHEMA_VERSION = 1;
 
 export function lintProject(projectDir) {

package/src/lint/rules.mjs

@@ -644,34 +644,173 @@ export function ruleCardContract(sourceFile, relative, findings) {
 
 // Test mode belongs to `attach --test-mode`, which never touches the bundle.
 // A call in agent code that turns it on can ship to production and mark real
-// users' conversations as test traffic. A call to `setTestMode` by name is
-// refused unless its first argument is the literal `false`. A call to
-// `armAllInstances` by name is always refused: even with `false` it sends a
-// partial `setConfiguration` to every instance.
+// users' conversations as test traffic.
+//
+// `setTestMode` is refused unless it is called with the literal `false` - and
+// also when it is reached any other way (handed on, `.call`, `.bind`).
+// `armAllInstances` is refused however it is used, whatever its argument:
+// called (by name, under the name it was imported as, by element access),
+// handed on (a timer, a listener, an object, a default value) or exported
+// under another name. Even with `false` it sends a partial `setConfiguration`
+// to every instance. Importing it, re-exporting it under its own name and
+// types are not uses. Names are matched within the file, not by binding, so
+// the rule errs on the side of refusing.
+//
+// One call is not refused. A code project carries its own copy of the runtime,
+// and that copy's `agent/runtime/agent.ts` defines `function
+// armAllInstances(testMode)`, which calls `setTestMode(testMode)`. That call -
+// with the helper's own first parameter, in that function, in that file - runs
+// only when something uses `armAllInstances`, and every use is refused. The
+// build also checks the bundle itself (`bundleTurnsOnTestMode`), which catches
+// what reading the source cannot.
 export function ruleNoTestModeInBundle(sourceFile, relative, findings) {
-  const walk = (node) => {
-    if (ts.isCallExpression(node)) {
-      const callee = node.expression;
-      const name = ts.isPropertyAccessExpression(callee) ? callee.name.text : ts.isIdentifier(callee) ? callee.text : "";
-      const first = node.arguments[0];
-      const setTestModeOff = name === "setTestMode" && first && first.kind === ts.SyntaxKind.FalseKeyword;
-      if ((name === "setTestMode" || name === "armAllInstances") && !setTestModeOff) {
-        findings.push(
-          finding({
-            rule: "no-test-mode-in-bundle",
-            severity: "error",
-            sourceFile,
-            node,
-            file: relative,
-            message: `\`${name}\` does not belong in agent code: any file in \`agent/\` can ship to production, where test mode would stop real users' conversations being tracked.`,
-            fix: "Remove it. Test mode is only for an agent that already has real users, and only through `npx foldspace attach --test-mode`, which never touches the bundle. For an agent with no real users yet, leave test mode off.",
-          }),
-        );
-      }
+  // path.sep, so a POSIX file whose name holds a backslash is not read as a folder.
+  const inRuntimeHelperFile = relative.split(path.sep).join("/") === "agent/runtime/agent.ts";
+
+  const ARM = "armAllInstances";
+  const armNames = new Set([ARM]);
+  const keyText = (key) => {
+    if (!key) return undefined;
+    if (ts.isIdentifier(key) || ts.isStringLiteralLike(key)) return key.text;
+    if (ts.isComputedPropertyName(key) && ts.isStringLiteralLike(key.expression)) return key.expression.text;
+    return undefined;
+  };
+  const collectImportedNames = (node) => {
+    if (ts.isImportSpecifier(node) && keyText(node.propertyName ?? node.name) === ARM) armNames.add(node.name.text);
+    if (ts.isBindingElement(node) && ts.isIdentifier(node.name) && keyText(node.propertyName ?? node.name) === ARM) {
+      armNames.add(node.name.text);
     }
-    ts.forEachChild(node, walk);
+    ts.forEachChild(node, collectImportedNames);
   };
-  walk(sourceFile);
+  collectImportedNames(sourceFile);
+
+  const memberName = (node) => {
+    if (ts.isPropertyAccessExpression(node)) return node.name.text;
+    if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) {
+      return node.argumentExpression.text;
+    }
+    return "";
+  };
+  const unwrap = (node) => {
+    while (
+      node &&
+      (ts.isParenthesizedExpression(node) ||
+        ts.isNonNullExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isSatisfiesExpression(node) ||
+        ts.isTypeAssertionExpression(node))
+    ) {
+      node = node.expression;
+    }
+    return node;
+  };
+  const isArm = (node) => (ts.isIdentifier(node) && armNames.has(node.text)) || memberName(node) === ARM;
+  const isSetTestMode = (node) =>
+    (ts.isIdentifier(node) && node.text === "setTestMode") || memberName(node) === "setTestMode";
+  const isCallee = (node) => {
+    let parent = node.parent;
+    while (parent && (ts.isParenthesizedExpression(parent) || ts.isNonNullExpression(parent) || ts.isAsExpression(parent))) {
+      parent = parent.parent;
+    }
+    return parent !== undefined && ts.isCallExpression(parent) && unwrap(parent.expression) === node;
+  };
+
+  const inImportEquals = (node) => {
+    let n = node;
+    while (n.parent && ts.isQualifiedName(n.parent)) n = n.parent;
+    return n.parent !== undefined && ts.isImportEqualsDeclaration(n.parent);
+  };
+  // Positions where the name is declared, imported, a key or a type - not a
+  // value that can be called later.
+  const isNamedNotUsed = (node) => {
+    const parent = node.parent;
+    if (!parent) return true;
+    if (ts.isPropertyAccessExpression(parent) && parent.name === node) return true;
+    if (ts.isQualifiedName(parent)) return !inImportEquals(node);
+    if (ts.isExportSpecifier(parent)) return true; // the export itself is judged below, once
+    if (ts.isBindingElement(parent)) return parent.name === node || parent.propertyName === node;
+    if (
+      ts.isImportSpecifier(parent) ||
+      ts.isImportClause(parent) ||
+      ts.isNamespaceImport(parent) ||
+      ts.isTypeQueryNode(parent) ||
+      ts.isImportTypeNode(parent)
+    ) {
+      return true;
+    }
+    if (ts.isFunctionDeclaration(parent) && parent.name === node) {
+      return !parent.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+    }
+    return (
+      (ts.isFunctionExpression(parent) ||
+        ts.isVariableDeclaration(parent) ||
+        ts.isParameter(parent) ||
+        ts.isPropertyAssignment(parent) ||
+        ts.isMethodDeclaration(parent) ||
+        ts.isMethodSignature(parent) ||
+        ts.isGetAccessorDeclaration(parent) ||
+        ts.isSetAccessorDeclaration(parent) ||
+        ts.isPropertyDeclaration(parent) ||
+        ts.isPropertySignature(parent) ||
+        ts.isEnumMember(parent)) &&
+      parent.name === node
+    );
+  };
+
+  // The helper's first parameter, when node is the runtime copy's own
+  // `function armAllInstances(testMode)` in agent/runtime/agent.ts.
+  const helperParam = (node) => {
+    if (!inRuntimeHelperFile || !ts.isFunctionDeclaration(node) || node.name?.text !== ARM) return undefined;
+    if (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)) return undefined;
+    const first = node.parameters[0];
+    return first && ts.isIdentifier(first.name) ? first.name.text : undefined;
+  };
+
+  const refuse = (node, name) => {
+    findings.push(
+      finding({
+        rule: "no-test-mode-in-bundle",
+        severity: "error",
+        sourceFile,
+        node,
+        file: relative,
+        message: `\`${name}\` does not belong in agent code: any file in \`agent/\` can ship to production, where test mode would stop real users' conversations being tracked.`,
+        fix: "Remove it. Test mode is only for an agent that already has real users, and only through `npx foldspace attach --test-mode`, which never touches the bundle. For an agent with no real users yet, leave test mode off.",
+      }),
+    );
+  };
+
+  const walk = (node, exemptParam) => {
+    if (ts.isCallExpression(node) && isSetTestMode(unwrap(node.expression))) {
+      const [first] = node.arguments;
+      const off = first !== undefined && first.kind === ts.SyntaxKind.FalseKeyword;
+      const helperOwnCall =
+        exemptParam !== undefined && node.arguments.length === 1 && ts.isIdentifier(first) && first.text === exemptParam;
+      if (!off && !helperOwnCall) refuse(node, "setTestMode");
+    } else if (isSetTestMode(node) && !isCallee(node) && !(ts.isIdentifier(node) && isNamedNotUsed(node))) {
+      refuse(node, "setTestMode");
+    }
+    if (ts.isCallExpression(node) && isArm(unwrap(node.expression))) {
+      refuse(node, ARM);
+    } else if (isArm(node)) {
+      if (!isCallee(node) && !(ts.isIdentifier(node) && isNamedNotUsed(node))) refuse(node, ARM);
+    } else if (ts.isExportSpecifier(node)) {
+      const local = keyText(node.propertyName ?? node.name);
+      if (local !== undefined && armNames.has(local) && keyText(node.name) !== ARM) refuse(node, ARM);
+    }
+    const param = exemptParam ?? helperParam(node);
+    ts.forEachChild(node, (child) => walk(child, param));
+  };
+  walk(sourceFile, undefined);
+}
+
+// What the build checks in the bundle it wrote: minify keeps property names,
+// so a bundle that can turn test mode on still says `setTestMode`. Calls with
+// `false` (`!1` once minified) are allowed; any other mention is not - the
+// net under the lint rule above, for code it cannot read (a computed name, a
+// file lint does not walk).
+export function bundleTurnsOnTestMode(js) {
+  return /setTestMode/.test(js.replace(/\??\.setTestMode(\?\.)?\(\s*(!1|false)\s*\)/g, ""));
 }
 
 export function lintActionFile(filePath, relative, findings) {

package/src/runtime/VERSION

@@ -0,0 +1 @@
+0.1.30