@foldspace_npm/harness 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,7 @@
 # @foldspace_npm/harness
 
-Build, inject and verify Foldspace agent experiences against a live app.
+Build the portable `dist/index.js` action artifact and verify it against a live
+app.
 
 **This package is the part that is the same in both architectures.** Everything
 else about how a builder runs differs between them; this does not.
@@ -13,7 +14,7 @@ else about how a builder runs differs between them; this does not.
 |---|---|---|
 | Who runs the agent | Claude Code on the builder's desktop | Claude Agent SDK in GCP |
 | Whose browser | an isolated Chrome the harness launches | the user's **own** Chrome |
-| How code reaches the page | CDP injection | Web Store extension injects a `<script src>` from the CDN |
+| How code reaches the page | harness CDP preparation | builder extension loads the cloud artifact |
 | Prerequisites | Claude Code, a client repo, Node, an isolated Chrome profile | the extension installed |
 | Session and cookies | in a profile the harness creates | the user's own, untouched |
 | Code and history | a git repo on the builder's machine | a workspace in the hosted environment |
@@ -26,8 +27,8 @@ constraint this package exists to protect.
 
 - `agent/actions/*` and `agent/api/*` — a handler is `fetch` plus `runTask`,
   nothing more. The actions built for Figma run unmodified in either track.
-- `foldspace-build` — esbuild → `dist/index.js`
-- `foldspace-deploy` — publish to `agent/actions/<env>/<productId>/<agentApiName>`
+- `foldspace build` — esbuild → `dist/index.js`
+- `foldspace deploy` — publish to `agent/actions/<env>/<productId>/<agentApiName>`
 - fixtures and tests
 - **the verb interface** below
 
@@ -50,20 +51,49 @@ exact failure this package was created to end. And the verb interface only stays
 honest while both implementations sit behind it; separate them and "the same
 action runs in both modes" quietly stops being true.
 
-A hosted container installs this and never calls `inject`. That is kilobytes of
-dead weight, against a contract that cannot drift.
+A hosted environment uses the same action source and build contract, but local
+`inject` and `attach` remain CDP-only commands. The harness does not generate a
+customer application extension.
 
 ---
 
 ## Use
 
+### Discover the CLI
+
+Human-readable help is grouped by workflow:
+
+```bash
+foldspace help
+foldspace help attach
+```
+
+Coding agents can inspect the same versioned command and capability contract:
+
+```bash
+foldspace help --json
+foldspace help attach --json
+```
+
+The installed `harness` binary is an alias for `foldspace`.
+
+The JSON describes current options, prerequisites, side effects, risks,
+capabilities, and next steps. It does not claim that future hosted-environment
+capability enforcement is already implemented.
+
 ### Create a project
 
 Create a configured actions project from the template bundled with the installed
-harness version:
+harness version. Missing values are prompted when stdin is a terminal:
+
+```bash
+npx --yes @foldspace_npm/harness init
+```
+
+Non-interactive / CI form:
 
 ```bash
-npm exec --package=@foldspace_npm/harness -- foldspace init my-agent \
+npx --yes @foldspace_npm/harness init my-agent \
   --product-id FR8JUQZAQRZB \
   --agent-api-name my-agent \
   --domain app.example.com \
@@ -79,24 +109,17 @@ node bin/cli.mjs init ../my-agent \
   --domain app.example.com
 ```
 
-Until `@foldspace_npm/harness` is published, install the local checkout in the
-generated project instead of running the standard install step:
-
-```bash
-cd ../my-agent
-npm install --ignore-scripts --save-dev /absolute/path/to/harness
-```
-
 `--name` is optional and defaults to the target directory name. The product ID
 must be the bare ID, not an `EU-…` SDK key. The domain may be a hostname or an
 HTTP(S) URL without a port or path.
 
 For safety, `init` requires a target path that does not exist. It does not
-install dependencies, initialize Git, or overwrite files. After creation:
+initialize Git or overwrite files. On a TTY it can offer
+`npm install --ignore-scripts` after scaffolding. After creation:
 
 ```bash
 cd my-agent
-npm install --ignore-scripts
+npm install --ignore-scripts   # if you skipped the install prompt
 npm run build
 npm run inject
 npm run attach
@@ -105,6 +128,35 @@ npm run attach
 The generated npm scripts intentionally remain the normal project interface;
 `foldspace init` is the one-time project creation command.
 
+### Choose an attach mode
+
+- **Swap (default):** the page already uses the configured product and agent.
+- **Bootstrap (`--bootstrap`):** the page has no Foldspace SDK.
+- **Replace (`--replace`):** the page embeds a different product or agent, or
+  has an SDK without the configured agent.
+
+Use `foldspace help attach` for mode requirements, effects, and safety options.
+
+### Verify actions through the agent
+
+`foldspace attach` does not invoke action handlers directly. It loads the local
+artifact, verifies that its action names exactly match the configured SDK agent,
+and then observes action callbacks while you exercise the normal agent
+experience.
+
+Action output identifies SDK callbacks and local `execute`/`render` phases:
+
+```text
+[actions] sdk:action show_account_360 executed
+[actions] local-handler:execute show_account_360 succeeded 412ms
+[actions] local-handler:render show_account_360 succeeded 18ms
+```
+
+Only action names, parameter keys, statuses, and durations are recorded; handler
+parameter values, results, and error messages are not. On detach, repeated page
+failures and bounded action observations are summarized. The observer and
+diagnostics are injected by the harness, so `dist/index.js` is not rewritten.
+
 ### Add the harness to an existing project
 
 ```bash
@@ -113,26 +165,22 @@ npm i -D @foldspace_npm/harness
 
 ```json
 { "scripts": {
-    "dev":    "foldspace-build --watch",
-    "build":  "foldspace-build",
-    "inject": "foldspace-inject",
-    "attach": "foldspace-attach",
-    "deploy": "foldspace-deploy"
+    "dev":    "foldspace build --watch",
+    "build":  "foldspace build",
+    "inject": "foldspace inject",
+    "attach": "foldspace attach",
+    "deploy": "foldspace deploy"
 } }
 ```
 
-| Command | A | B |
-|---|:--:|:--:|
-| `foldspace init` | ✅ | ✅ |
-| `foldspace-build` | ✅ | ✅ |
-| `foldspace-deploy` | ✅ | ✅ — it *is* the delivery mechanism |
-| `foldspace-inject` | ✅ | — no browser to launch |
-| `foldspace-attach` | ✅ | replaced by the extension bridge |
-
 Every command resolves the **consuming** repo — `process.cwd()`, or
 `FOLDSPACE_PROJECT_DIR` so a hosted builder can point it at a workspace it
 controls. Config comes from the consumer's `foldspace.dev.json`.
 
+`foldspace deploy` is an explicit remote publication step that reads product
+and agent identity from the selected target in `foldspace.dev.json`. It requires
+local cloud credentials and is separate from local verification.
+
 ---
 
 ## Why this package exists at all