@foldspace_npm/harness 0.1.21 → 0.1.22

package/CLAUDE.md

@@ -13,7 +13,11 @@ something they can **see on their own page** — not at "it builds".
    `npx --yes @foldspace_npm/harness@latest upgrade --check`). If
    `update.outdated` is true, say the pinned and latest versions and **ask
    before upgrading**; then `foldspace upgrade --yes` and `npm run build`. Never
-   upgrade as a side effect of build, attach or implementing an action. If the
+   upgrade as a side effect of build, attach or implementing an action.
+   `build` and `attach` check too: behind prints one line and carries on; a
+   version Foldspace **withdrew** refuses to run and says why. Tell the user
+   the reason and ask to upgrade. Only if they decide not to, rerun with
+   `FOLDSPACE_SKIP_UPDATE_CHECK=1` - never set it on your own. If the
    project `CLAUDE.md` does not contain
    `@node_modules/@foldspace_npm/harness/CLAUDE.md`, ask before
    `foldspace upgrade --refresh-instructions`.

package/README.md

@@ -151,6 +151,55 @@ foldspace upgrade --yes   # only after the user agrees
 `--yes` rewrites the exact pin and runs `npm install --ignore-scripts`. Rebuild
 afterward; that is still not a deploy.
 
+`foldspace build` and `foldspace attach` run the same check before they start
+(`attach --status` and `--stop` do not). A project that is behind gets one line
+on stderr and carries on. A project on a **withdrawn** version (below) refuses
+to run and prints the reason. To build on it anyway, once the user has declined
+the upgrade:
+
+```bash
+FOLDSPACE_SKIP_UPDATE_CHECK=1 npm run build
+```
+
+That turns the check off entirely; it does not fix the withdrawn version.
+
+### Withdrawing a release (maintainers)
+
+When a published version is broken badly enough that nobody should build on
+it, withdraw it with `npm deprecate`. The registry is the list of withdrawn
+versions, so projects already installed on it see the withdrawal without
+installing anything new. Only owners of `@foldspace_npm/harness` on npm can
+run it.
+
+1. **Publish the fix first.** If the withdrawn version is also `latest`, the
+   message tells users to upgrade to a version that is itself withdrawn.
+2. **Withdraw the broken version**, with a message that says what is wrong and
+   which version to move to. That message is exactly what users, and the coding
+   agent working for them, see when `build` or `attach` refuses to run:
+
+   ```bash
+   npm deprecate @foldspace_npm/harness@0.1.14 "attach loads the wrong bundle; upgrade to 0.1.15"
+   ```
+
+   A range works too: `npm deprecate "@foldspace_npm/harness@<0.1.15" "…"`.
+3. **Check it took:**
+
+   ```bash
+   npm view @foldspace_npm/harness@0.1.14 deprecated
+   ```
+
+To undo a withdrawal, deprecate with an empty message:
+
+```bash
+npm deprecate @foldspace_npm/harness@0.1.14 ""
+```
+
+**It is not instant.** Each project caches the registry's answer for 12 hours
+in `.foldspace-dev/harness-update.json`. A project that checked recently keeps
+its "fine" answer until that expires, so a withdrawal reaches every project
+within 12 hours. It only reaches projects on a harness version that has this
+check.
+
 ### Lint handlers before they ship
 
 `foldspace build` runs `foldspace lint` first. Errors skip bundling; warnings

package/bin/cli.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import { runInit } from "../src/init.mjs";
 import {
   checkForUpdate,
+  gateForCommand,
   nagIfOutdated,
   resolveProjectDir,
   runUpgrade,
@@ -54,6 +55,18 @@ function runScript(scriptName, args) {
   });
 }
 
+// build and attach are where a stale or withdrawn harness does its damage, so
+// they check before running. Returns false when the command must not run.
+function passesVersionGate() {
+  const gate = gateForCommand(checkForUpdate(resolveProjectDir())) || {};
+  if (gate.message) console.error(`foldspace: ${gate.message}`);
+  if (gate.block) {
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
 function printHelp(topic, json) {
   const document = helpDocument(registry, topic);
   if (!document) {
@@ -184,8 +197,14 @@ if (!command || command === "--help" || command === "-h") {
     try {
       const definition = commandByName(command);
       const normalized = normalizeCommandArgs(definition, args);
-      if (command === "attach") {
-        const control = classifyAttachControl(normalized);
+      const control =
+        command === "attach" ? classifyAttachControl(normalized) : null;
+      const gated =
+        command === "build" ||
+        (command === "attach" && (!control || control === "daemon"));
+      if (gated && !passesVersionGate()) {
+        // gate already reported why
+      } else if (command === "attach") {
         if (control) {
           Promise.resolve()
             .then(() =>

package/package.json

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

package/src/cli-registry.mjs

@@ -112,12 +112,13 @@ export const CLI_COMMANDS = Object.freeze([
     usage: "foldspace build [--watch]",
     risk: "local-write",
     environment: "node",
-    environmentVariables: ["FOLDSPACE_PROJECT_DIR"],
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "FOLDSPACE_SKIP_UPDATE_CHECK"],
     capabilities: ["artifact.build"],
     positionals: [],
     options: [flag("--watch", "Rebuild when action source changes")],
     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)",
       "Runs foldspace lint first; errors skip bundling",
       "Writes dist/index.js when lint has no errors",
     ],
@@ -201,6 +202,7 @@ export const CLI_COMMANDS = Object.freeze([
       "FOLDSPACE_PROJECT_DIR",
       "CDP_PORT",
       "AGENT_API_NAME",
+      "FOLDSPACE_SKIP_UPDATE_CHECK",
     ],
     capabilities: [
       "browser.cdp",
@@ -260,6 +262,7 @@ export const CLI_COMMANDS = Object.freeze([
       "sdkUrl in foldspace.dev.json when using --bootstrap",
     ],
     effects: [
+      "Checks the harness version first, except --status and --stop: behind prints one line, a withdrawn version refuses to run (FOLDSPACE_SKIP_UPDATE_CHECK=1 skips the check)",
       "May reload and instrument matching target pages",
       "Refuses a Chrome that is not the profile inject launched",
       "Test mode is off unless --test-mode is passed: conversations appear in the dashboard",
@@ -464,6 +467,7 @@ export function createCliRegistry({ packageName, packageVersion, env = process.e
       "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.",
+      "If update.broken is true, this version was withdrawn and build and attach refuse to run. Ask the user to upgrade; set FOLDSPACE_SKIP_UPDATE_CHECK=1 only if they decline.",
       "observe, ask and run are read-only second clients on the test window and work while attach runs.",
       "There is no customer-run publication step: putting actions in front of end users is done with Foldspace's team.",
     ],

package/src/upgrade.mjs

@@ -227,10 +227,10 @@ function readCache(projectDir, now) {
   }
 }
 
-function writeCache(projectDir, latest, now) {
+function writeCache(projectDir, entry, now) {
   const dir = path.dirname(cachePath(projectDir));
   fs.mkdirSync(dir, { recursive: true });
-  writeJson(cachePath(projectDir), { checkedAt: now, latest });
+  writeJson(cachePath(projectDir), { checkedAt: now, ...entry });
 }
 
 export function fetchLatestFromNpm(options = {}) {
@@ -244,7 +244,27 @@ export function fetchLatestFromNpm(options = {}) {
   return normalizeVersion(result.stdout);
 }
 
+/**
+ * A version we have withdrawn is marked with `npm deprecate`, so the registry
+ * is the list of known-broken versions and an old install can still read it.
+ * Returns the deprecation message, "" when the version is not deprecated, or
+ * null when the registry could not be asked.
+ */
+export function fetchDeprecationFromNpm(version, options = {}) {
+  const spawn = options.spawnSyncFn || spawnSync;
+  const result = spawn("npm", ["view", `${HARNESS_PACKAGE}@${version}`, "deprecated"], {
+    encoding: "utf8",
+    timeout: options.timeoutMs ?? NPM_VIEW_TIMEOUT_MS,
+    env: options.env || process.env,
+  });
+  if (result.error || result.status !== 0) return null;
+  return String(result.stdout || "").trim();
+}
+
 function nextAction(report) {
+  if (report.broken) {
+    return `This harness version was withdrawn: ${report.deprecated}. ${UPGRADE_NEXT}`;
+  }
   if (report.status === "outdated") {
     return report.instructionsImport === false
       ? `${UPGRADE_NEXT}. If CLAUDE.md is still a snapshot, also pass --refresh-instructions`
@@ -275,7 +295,11 @@ export function checkForUpdate(projectDir, options = {}) {
     (options.skipCheck !== false && env.FOLDSPACE_SKIP_UPDATE_CHECK === "1");
   const consumer = !harnessSource && Boolean(pinned || installed);
 
+  // The version that actually runs is the installed one; the pin is a fallback
+  // for a project that has not been installed yet.
+  const running = installed || pinned;
   let latest = null;
+  let deprecated = null;
   let status = "current";
 
   if (!consumer) {
@@ -284,16 +308,30 @@ export function checkForUpdate(projectDir, options = {}) {
     status = "check_skipped";
   } else {
     const cached = options.cache === false ? null : readCache(projectDir, now);
-    if (cached?.latest) {
+    const cachedDeprecation =
+      cached?.deprecation?.version === running ? cached.deprecation : null;
+    if (cached?.latest && cachedDeprecation) {
       latest = cached.latest;
+      deprecated = cachedDeprecation.message || null;
     } else {
       const fetched =
         typeof options.fetchLatest === "function"
           ? options.fetchLatest()
           : fetchLatestFromNpm(options);
       latest = normalizeVersion(fetched);
+      const message =
+        typeof options.fetchDeprecation === "function"
+          ? options.fetchDeprecation(running)
+          : fetchDeprecationFromNpm(running, options);
+      deprecated = message || null;
       if (latest && options.cache !== false) {
-        writeCache(projectDir, latest, now);
+        const entry = { latest };
+        // Only cache an answer the registry actually gave, so an offline
+        // run is asked again next time instead of remembered as "fine".
+        if (typeof message === "string") {
+          entry.deprecation = { version: running, message };
+        }
+        writeCache(projectDir, entry, now);
       }
     }
     if (!latest) {
@@ -311,6 +349,8 @@ export function checkForUpdate(projectDir, options = {}) {
     installed,
     latest,
     outdated: status === "outdated",
+    deprecated,
+    broken: Boolean(deprecated),
     status,
     instructionsImport,
     next: null,
@@ -319,6 +359,33 @@ export function checkForUpdate(projectDir, options = {}) {
   return report;
 }
 
+/**
+ * What `build` and `attach` do with an update report before they run:
+ * `block: true` stops the command, `message` (if any) is printed to stderr.
+ * Never upgrades - that stays the user's decision (CLAUDE.md, step 1).
+ * The escape hatch is FOLDSPACE_SKIP_UPDATE_CHECK=1: the report comes back
+ * check_skipped, so nothing here blocks.
+ */
+export function gateForCommand(report) {
+  // A check that could not run never stops a build.
+  if (!report) return { block: false, message: null };
+  if (report.broken) {
+    return {
+      block: true,
+      message:
+        `${HARNESS_PACKAGE} ${report.installed || report.pinned} was withdrawn: ${report.deprecated}. ` +
+        `${UPGRADE_NEXT}. If the user declines, rerun with FOLDSPACE_SKIP_UPDATE_CHECK=1 to build on this version anyway.`,
+    };
+  }
+  if (report.outdated) {
+    return {
+      block: false,
+      message: `${HARNESS_PACKAGE} ${report.installed || report.pinned} is behind ${report.latest}. ${UPGRADE_NEXT}.`,
+    };
+  }
+  return { block: false, message: null };
+}
+
 export function writeExactPin(projectDir, version) {
   const manifestPath = path.join(projectDir, "package.json");
   const manifest = readPackageManifest(projectDir);

package/templates/agent-starter/docs/app-profile.md

@@ -14,8 +14,10 @@ How to re-run any probe below:
 
 ```bash
 npm run inject
-# Sign in. Capture from chrome-devtools MCP, or a page-context fetch,
-# before foldspace attach owns the debug port.
+# Sign in, then read the running app with foldspace observe. It reads the
+# window you signed in to, and works while foldspace attach runs.
+npx foldspace observe screen --click "<a label from observe menu>" --match "<words for the data>"
+npx foldspace observe read "<the GET path screen returned>"
 ```
 
 Start URL: `{{START_URL}}`