unfold-deploy 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.2.0 (2026-11-05)
+
+- `unfold gcloud`: Cloud Run deploys (`gcloud run deploy`) as Prepare → Build → Deploy → Live, with build and revision log links, troubleshooting links, and readable errors from gcloud's HTML error pages.
+- `unfold claude "<task>"` and `unfold codex "<task>"`: run Claude Code or Codex non-interactively and show Start → Explore → Change → Verify → Done, with files changed, checks run, the final answer and cost or tokens. Verify is only confirmed by a passing check.
+- Providers that emit JSON events are shown as readable lines instead of raw JSON; their saved runs replay from recorded events.
+- New demos: `gcloud success`, `gcloud deploy-failure`, `claude success`, `codex checks-failing` (`unfold demo <provider> <name>`).
+- Summary headlines and labels now come from the provider ("Deployed", "Done", …).
+
+## 0.1.0 (2026-11-05)
+
+First release.
+
+- `unfold vercel`: runs `vercel deploy` with your existing login and project link, and shows a live Prepare → Upload → Build → Preview flow pinned to the bottom of the terminal.
+- End-of-run summary with each stage's status and reason, the error, the most likely cause, and URLs.
+- Stages are only confirmed when the output proves it; otherwise they are marked unverified with a reason.
+- `unfold show`: full-screen terminal explorer for a run (stages, evidence, logs, fix prompt).
+- Fix prompts for failed runs, with ready-to-run `claude` and `codex` commands; `--fix claude|codex` starts the agent automatically.
+- Optional browser view with `--web`, served on 127.0.0.1 only.
+- Secret redaction before anything is shown or saved; runs stored in `~/.unfold/runs` (mode 0600, newest 100 kept).
+- Works without node-pty through the system `script` command (macOS and Linux).
+- Demos that run without a Vercel account: `unfold demo success|build-failure|interrupted`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 faizm10
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# Unfold
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Watch what happens after you hit Enter.**
+
+Unfold wraps a CLI command and shows what it's doing as a flow, right in your terminal. The command's own output and prompts work exactly as before, and a small panel pinned to the bottom of the terminal tracks each stage as it happens.
+
+| Command | Wraps | Flow |
+| --- | --- | --- |
+| `unfold vercel` | `vercel deploy` | Prepare → Upload → Build → Preview |
+| `unfold gcloud` | `gcloud run deploy` (Cloud Run) | Prepare → Build → Deploy → Live |
+| `unfold claude "<task>"` | Claude Code, non-interactive | Start → Explore → Change → Verify → Done |
+| `unfold codex "<task>"` | Codex CLI, non-interactive | Start → Explore → Change → Verify → Done |
+
+```
+Vercel CLI 65.2.0
+  Inspect         https://vercel.com/acme/acme-web/6TfY2pQk…
+2026-11-05T18:04:31Z  Running "npm run build"
+…
+── unfold · vercel deploy --logs ─────────────────────── Running 12.4s
+ ✓ Prepare ── ✓ Upload ── ⠹ Build ── ○ Preview
+ Build: Build logs are streaming from Vercel.  ·  Your build command started.
+```
+
+When the command finishes, the panel turns into a summary: every stage's status and reason, the error and most likely cause with line numbers, the URLs, and (on failure) a ready-made fix command for Claude Code or Codex.
+
+Run `unfold show` to explore the run full screen. For each stage it shows two things side by side:
+
+- **Observed in this run**: status, facts and the exact output lines from your deploy, each linking to its place in the logs.
+- **How this stage works**: a general, plain-language explanation. It is clearly labeled as not coming from your run.
+
+Use ←/→ to switch stages, `l` for the logs, `e` to jump to the error, `f` for the fix prompt, `c`/`x` to copy the Claude/Codex command, and `q` to quit.
+
+A stage is only marked **Confirmed** when the output proves it. If the output can't confirm a stage, it stays **Unverified** (`?`) and Unfold says why. One example: Vercel skips uploading files it already has, so a deploy can finish without the output ever showing an upload. When a deploy fails, you see the stage it failed in, the last confirmed stage, the error, the line most likely to be the cause, and a link to that line in the logs.
+
+## Install
+
+Requires Node.js 20 or later, on macOS or Linux. Windows should work but hasn't been tested yet.
+
+```sh
+npm install -g unfold-deploy
+```
+
+The package is `unfold-deploy`; the command is `unfold`. To try it without installing, prefix commands with `npx unfold-deploy` (for example `npx unfold-deploy demo success`).
+
+## Try it without an account
+
+The demos play recorded terminal output through the same pipeline a real run uses:
+
+```sh
+unfold demo success                  # Vercel: a preview deploy that succeeds
+unfold demo build-failure            # Vercel: the build fails on a TypeScript error
+unfold demo interrupted              # Vercel: Ctrl+C while building
+unfold demo gcloud success           # Cloud Run: a source deploy that goes live
+unfold demo gcloud deploy-failure    # Cloud Run: the container never listens on $PORT
+unfold demo claude success           # Claude Code fixes a failing test and confirms it
+unfold demo codex checks-failing     # Codex finishes, but the tests still fail
+unfold show                          # explore the run you just watched
+```
+
+Add `--speed 2` to play faster. Press Ctrl+C during any demo to see the interrupted state.
+
+## Run a real preview deploy
+
+You need the Vercel CLI (`npm i -g vercel`) and `vercel login`. Then, from your app's folder (the one with its `package.json`):
+
+```sh
+cd ~/code/my-app
+unfold vercel                 # runs: vercel deploy --logs
+unfold vercel --yes           # any vercel deploy flags pass straight through
+```
+
+- Unfold runs your installed `vercel` with your existing login and `.vercel/` project link. If the folder isn't linked yet, the Vercel CLI asks its usual questions in your terminal.
+- Unfold adds `--logs` so that the Build stage has real evidence.
+- Unfold creates preview deployments by default. Adding `--prod` makes a production deploy, so don't pass it unless that's what you want.
+- If you belong to several Vercel teams, the CLI asks which one to use. Pass `--scope <team>` to skip the question.
+- Ctrl+C goes to the Vercel CLI as usual. If the deployment had already been created, Vercel may keep building it, and the summary shows its Inspect URL so you can check.
+- Every run is saved. `unfold show` explores the latest one, `unfold show <run-id>` an older one, and `unfold runs` lists them.
+
+Unfold options: `--fix claude|codex` (see below), `--no-panel` (no pinned panel, summary only), `--speed <n>` (demos and replays).
+
+## Deploy to Cloud Run
+
+You need the Google Cloud CLI, logged in (`gcloud auth login`) with a project set. From your service's folder:
+
+```sh
+unfold gcloud --source . --region us-central1      # runs: gcloud run deploy --source . --region us-central1
+unfold gcloud my-api --image us-docker.pkg.dev/…   # prebuilt image: no Build stage
+```
+
+Everything after `unfold gcloud` goes to `gcloud run deploy`, and its questions (service name, region, unauthenticated access) still appear in your terminal. On failure the summary shows the error, the Cloud Build or revision logs link, and the troubleshooting link gcloud printed. HTML error pages gcloud sometimes prints are reduced to their readable sentence.
+
+## Watch a coding agent: Claude Code and Codex
+
+Unfold runs the agent in its non-interactive mode, which reports every step as a structured event, and shows it as a flow: what it read (**Explore**), which files it edited (**Change**), whether checks such as `npm test` or `tsc` passed (**Verify**), and its final answer (**Done**). The summary lists the files changed, the answer, and the cost or token use.
+
+```sh
+unfold claude "fix the failing test" --allowedTools Read Edit "Bash(npm test)"
+unfold claude "add input validation to the signup form" --permission-mode acceptEdits
+unfold codex "fix the failing test" --sandbox workspace-write
+```
+
+- Non-interactive agents can't stop to ask for permission. Give Claude Code the tools it needs with `--allowedTools` or `--permission-mode acceptEdits`; give Codex write access with `--sandbox workspace-write`. Denied tools are listed in the summary.
+- **Verify is only confirmed when a check passes.** If the agent never runs one, or the last one failed, Verify stays `?` with the reason, even when the agent says it's done.
+- Edits go straight to your working tree. Review them with `git diff`.
+
+### Browser view (optional)
+
+Nothing is served unless you ask for it. Add `--web` to also open the flow in a local browser page, for example `unfold vercel --web` or `unfold show --web`. The page is served on `127.0.0.1` only. With `--web` you can also use `--no-open`, `--once` (exit when the run ends) and `--port <n>` (default 4317).
+
+## When a deploy fails: hand it to Claude Code or Codex
+
+Every failed run automatically gets a fix prompt built from that run. It contains:
+
+- the error and the output lines most likely to be the cause, most specific first
+- a redacted log excerpt
+- files mentioned in the errors, such as `./app/checkout/page.tsx:42:21`
+- the framework and build command
+- hints about the stage that failed, for example that Vercel builds use the project's Preview environment variables rather than your local `.env`
+
+The prompt also tells the agent not to deploy and not to change environment variables.
+
+- The prompt is saved to `~/.unfold/runs/<run>.fix-prompt.md` and the summary prints a ready-to-paste command: `claude "$(cat ~/.unfold/runs/<run>.fix-prompt.md)"` or the same with `codex`.
+- In `unfold show`, `f` displays the prompt and `c`/`x` copy the Claude/Codex command. The browser view (`--web`) has the same options.
+- `unfold vercel --fix claude` (or `--fix codex`) goes one step further: if the deploy fails, Unfold starts that agent in your project folder with the prompt. Nothing starts on success, and nothing starts unless you pass the flag.
+
+Try it without an account: `unfold demo build-failure`.
+
+## Privacy
+
+- **Everything stays local.** By default nothing is served at all. With `--web` the page is served on `127.0.0.1` only, and requests for any other host name are rejected. Unfold sends no telemetry.
+- **Secrets are redacted** before any output is shown on the page or saved to disk. This covers tokens, keys, JWTs, `user:password@` in URLs, `KEY=value` pairs with secret-looking names, private key blocks, and `--token` / `--env` flag values. Values of secret-looking environment variables are also matched, in memory only.
+- **The environment is never recorded.** The Vercel CLI inherits it so that your login works, and Unfold doesn't save it.
+- **Saved runs are private to you.** They're written to `~/.unfold/runs/*.jsonl` with mode `0600`, outside your project, so they can't be committed by accident. The newest 100 runs are kept (`UNFOLD_KEEP_RUNS` changes this). Set `UNFOLD_HOME` to store them elsewhere.
+- Your own terminal shows the CLI's unredacted output, the same as it would without Unfold.
+
+## Troubleshooting
+
+- **"Could not find vercel / gcloud / claude / codex on your PATH"**: install that CLI and log in to it first; Unfold prints the install command.
+- **Agent stopped without changing anything**: it probably wasn't allowed to. Check "Permission denied" in the summary and allow the tool (see above).
+- **Stuck at a Vercel question**: Unfold passes your keystrokes straight to the Vercel CLI, so answer it as usual. In scripts, pass `--yes` and `--scope <team>`.
+- **"Unfold didn't recognize any of this output"**: your Vercel CLI may print a format Unfold doesn't know yet. The deploy itself is unaffected. Please open an issue and include your `vercel --version`.
+- **No live panel**: the panel needs a terminal at least 50×12 and the `node-pty` package. On Linux without build tools, node-pty may not install; Unfold then runs the CLI through the system `script` command, prints only the summary, and keeps prompts working. `UNFOLD_TERMINAL=script` or `UNFOLD_TERMINAL=pipe` forces a fallback, and `--no-panel` turns the panel off.
+- **Terminal looks wrong after a crash**: run `reset`. Unfold restores the terminal on normal exits, Ctrl+C and crashes, so please report the crash.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, tests, and how to add a provider such as `gcloud`.
+
+## License
+
+MIT

package/bin/unfold.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { main } from '../dist/cli.js';
+import { restoreTerminal } from '../dist/tui/restore.js';
+
+function crash(err) {
+  restoreTerminal();
+  process.stderr.write(`\n[unfold] Unexpected error: ${err?.stack ?? err}\n`);
+  process.stderr.write('[unfold] Please report it at https://github.com/faizm10/unfold/issues\n');
+  process.exit(1);
+}
+process.on('uncaughtException', crash);
+process.on('unhandledRejection', crash);
+
+main(process.argv.slice(2)).then((code) => process.exit(code), crash);

package/demos/claude-success.json

@@ -0,0 +1,72 @@
+{
+ "provider": "claude",
+ "description": "Claude Code fixes a failing test and confirms it with npm test.",
+ "command": [
+  "claude",
+  "-p",
+  "Fix the failing test",
+  "--permission-mode",
+  "acceptEdits",
+  "--output-format",
+  "stream-json",
+  "--verbose"
+ ],
+ "cwd": "/home/dev/tiny-app",
+ "exitCode": 0,
+ "signal": null,
+ "interrupted": false,
+ "chunks": [
+  {
+   "t": 300,
+   "d": "{\"type\":\"system\",\"subtype\":\"init\",\"cwd\":\"/home/dev/tiny-app\",\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\",\"model\":\"claude-opus-5-5\",\"permissionMode\":\"acceptEdits\",\"claude_code_version\":\"2.1.292\",\"tools\":[\"Read\",\"Edit\",\"Bash\"]}\r\n"
+  },
+  {
+   "t": 1800,
+   "d": "{\"type\":\"assistant\",\"message\":{\"content\":[{\"type\":\"text\",\"text\":\"I'll look at the code and run the tests first.\"}]},\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  },
+  {
+   "t": 2700,
+   "d": "{\"type\":\"assistant\",\"message\":{\"content\":[{\"type\":\"tool_use\",\"id\":\"t1\",\"name\":\"Read\",\"input\":{\"file_path\":\"/home/dev/tiny-app/sum.js\"}}]},\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  },
+  {
+   "t": 3000,
+   "d": "{\"type\":\"user\",\"message\":{\"content\":[{\"type\":\"tool_result\",\"tool_use_id\":\"t1\",\"content\":\"1\\texport function sum(a, b) {\\n2\\t  return a - b;\\n3\\t}\\n\",\"is_error\":false}]},\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  },
+  {
+   "t": 4200,
+   "d": "{\"type\":\"assistant\",\"message\":{\"content\":[{\"type\":\"tool_use\",\"id\":\"t2\",\"name\":\"Bash\",\"input\":{\"command\":\"npm test\",\"description\":\"Run the tests\"}}]},\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  },
+  {
+   "t": 6000,
+   "d": "{\"type\":\"user\",\"message\":{\"content\":[{\"type\":\"tool_result\",\"tool_use_id\":\"t2\",\"content\":\"Exit code 1\\nAssertionError [ERR_ASSERTION]: Expected values to be strictly equal:\\n\\n-1 !== 5\\n\",\"is_error\":true}]},\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  },
+  {
+   "t": 7400,
+   "d": "{\"type\":\"assistant\",\"message\":{\"content\":[{\"type\":\"text\",\"text\":\"`sum` subtracts instead of adding. Fixing it.\"}]},\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  },
+  {
+   "t": 8500,
+   "d": "{\"type\":\"assistant\",\"message\":{\"content\":[{\"type\":\"tool_use\",\"id\":\"t3\",\"name\":\"Edit\",\"input\":{\"file_path\":\"/home/dev/tiny-app/sum.js\",\"old_string\":\"return a - b;\",\"new_string\":\"return a + b;\"}}]},\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  },
+  {
+   "t": 8800,
+   "d": "{\"type\":\"user\",\"message\":{\"content\":[{\"type\":\"tool_result\",\"tool_use_id\":\"t3\",\"content\":\"The file /home/dev/tiny-app/sum.js has been updated.\",\"is_error\":false}]},\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  },
+  {
+   "t": 9700,
+   "d": "{\"type\":\"assistant\",\"message\":{\"content\":[{\"type\":\"tool_use\",\"id\":\"t4\",\"name\":\"Bash\",\"input\":{\"command\":\"npm test\",\"description\":\"Run the tests again\"}}]},\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  },
+  {
+   "t": 11400,
+   "d": "{\"type\":\"user\",\"message\":{\"content\":[{\"type\":\"tool_result\",\"tool_use_id\":\"t4\",\"content\":\"> tiny-app@1.0.0 test\\n> node test.js\\n\\nok\\n\",\"is_error\":false}]},\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  },
+  {
+   "t": 12600,
+   "d": "{\"type\":\"assistant\",\"message\":{\"content\":[{\"type\":\"text\",\"text\":\"Fixed `sum` in sum.js: it returned `a - b` instead of `a + b`. `npm test` now passes.\"}]},\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  },
+  {
+   "t": 12800,
+   "d": "{\"type\":\"result\",\"subtype\":\"success\",\"is_error\":false,\"duration_ms\":13800,\"num_turns\":6,\"result\":\"Fixed `sum` in sum.js: it returned `a - b` instead of `a + b`. `npm test` now passes.\",\"total_cost_usd\":0.1876,\"permission_denials\":[],\"session_id\":\"7b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d\"}\r\n"
+  }
+ ]
+}

package/demos/codex-checks-failing.json

@@ -0,0 +1,62 @@
+{
+ "provider": "codex",
+ "description": "Codex edits a date helper, but the tests still fail when it stops.",
+ "command": [
+  "codex",
+  "exec",
+  "--json",
+  "Fix the time zone bug in startOfDay",
+  "--sandbox",
+  "workspace-write"
+ ],
+ "cwd": "/home/dev/tiny-app",
+ "exitCode": 0,
+ "signal": null,
+ "interrupted": false,
+ "chunks": [
+  {
+   "t": 300,
+   "d": "{\"type\":\"thread.started\",\"thread_id\":\"01a1ae40-5b6c-7d8e-9f01-23456789abcd\"}\r\n"
+  },
+  {
+   "t": 400,
+   "d": "{\"type\":\"turn.started\"}\r\n"
+  },
+  {
+   "t": 2600,
+   "d": "{\"type\":\"item.completed\",\"item\":{\"id\":\"item_0\",\"type\":\"agent_message\",\"text\":\"I'll read the date helper and its tests, then fix the time zone bug.\"}}\r\n"
+  },
+  {
+   "t": 3500,
+   "d": "{\"type\":\"item.started\",\"item\":{\"id\":\"item_1\",\"type\":\"command_execution\",\"command\":\"/bin/zsh -lc \\\"cat src/dates.js test/dates.test.js\\\"\",\"aggregated_output\":\"\",\"exit_code\":null,\"status\":\"in_progress\"}}\r\n"
+  },
+  {
+   "t": 3800,
+   "d": "{\"type\":\"item.completed\",\"item\":{\"id\":\"item_1\",\"type\":\"command_execution\",\"command\":\"/bin/zsh -lc \\\"cat src/dates.js test/dates.test.js\\\"\",\"aggregated_output\":\"export function startOfDay(d) { … }\\n\",\"exit_code\":0,\"status\":\"completed\"}}\r\n"
+  },
+  {
+   "t": 6400,
+   "d": "{\"type\":\"item.started\",\"item\":{\"id\":\"item_2\",\"type\":\"file_change\",\"changes\":[{\"path\":\"/home/dev/tiny-app/src/dates.js\",\"kind\":\"update\"}],\"status\":\"in_progress\"}}\r\n"
+  },
+  {
+   "t": 6600,
+   "d": "{\"type\":\"item.completed\",\"item\":{\"id\":\"item_2\",\"type\":\"file_change\",\"changes\":[{\"path\":\"/home/dev/tiny-app/src/dates.js\",\"kind\":\"update\"}],\"status\":\"completed\"}}\r\n"
+  },
+  {
+   "t": 7400,
+   "d": "{\"type\":\"item.started\",\"item\":{\"id\":\"item_3\",\"type\":\"command_execution\",\"command\":\"/bin/zsh -lc \\\"npm test\\\"\",\"aggregated_output\":\"\",\"exit_code\":null,\"status\":\"in_progress\"}}\r\n"
+  },
+  {
+   "t": 9800,
+   "d": "{\"type\":\"item.completed\",\"item\":{\"id\":\"item_3\",\"type\":\"command_execution\",\"command\":\"/bin/zsh -lc \\\"npm test\\\"\",\"aggregated_output\":\"> tiny-app@1.0.0 test\\n> node --test\\n\\n✖ startOfDay keeps the local date (2.1ms)\\n  AssertionError: Expected \\\"2026-11-05\\\" but got \\\"2026-11-04\\\"\\n\\nℹ tests 6  pass 5  fail 1\\n\",\"exit_code\":1,\"status\":\"failed\"}}\r\n"
+  },
+  {
+   "t": 12400,
+   "d": "{\"type\":\"item.completed\",\"item\":{\"id\":\"item_4\",\"type\":\"agent_message\",\"text\":\"I changed startOfDay to use local time, but one test still fails: it expects 2026-11-05 and gets 2026-11-04, so the test itself may assume UTC. Can you confirm which time zone the dates should use?\"}}\r\n"
+  },
+  {
+   "t": 12600,
+   "d": "{\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":64210,\"cached_input_tokens\":51200,\"output_tokens\":812}}\r\n"
+  }
+ ]
+}