The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: Plan Canvas, a browser review canvas for plans (#2467)
haelyraa51139561364
diff --git a/.agents/skills/plan-canvas/SKILL.md b/.agents/skills/plan-canvas/SKILL.mdnew file mode 100644index 000000000..72ea5aef6--- /dev/null+++ b/.agents/skills/plan-canvas/SKILL.md@@ -0,0 +1,152 @@+---+name: plan-canvas+description: Open plans and HTML artifacts in a local browser canvas where the human annotates elements, chats, and approves or requests changes without leaving the page. Use when presenting a plan for review, or when feedback like "move this, change that" is easier pointed at than typed.+metadata:+ origin: ECC+---++# Plan Canvas++Review loop for plans and visual artifacts: you write the artifact, the human+reviews it in the browser — annotating the exact element they mean, chatting,+and delivering an **Approve plan / Request changes** verdict — while you block+on a single CLI call that returns their feedback as JSON.++Inspired by [lavish-axi](https://github.com/kunchenguid/lavish-axi); rebuilt+ECC-native around the `/plan` confirmation gate, with zero dependencies.++## When to Use++- You just wrote a plan artifact (`.claude/plans/*.plan.md` from `/plan`) and+ need the CONFIRM/approve decision — the canvas verdict replaces a typed+ "yes/proceed".+- The user should *point at* what to change: reviewing designs, comparisons,+ reports, or any local `.md` / `.html` artifact.+- The user asks for `/plan-canvas`, a visual review, or "open it in the browser".++Do NOT use for: code review of diffs (`/code-review`), running web apps, or+remote URLs. The canvas serves local artifact files only.++## How It Works++Invoke the CLI as `ecc-plan-canvas` — the bin shipped by the `ecc-universal`+package (on PATH after a global/plugin install; `node "$CLAUDE_PLUGIN_ROOT/scripts/plan-canvas.js"`+also works for plugin installs). Run it from the project you are reviewing in;+it works from any working directory. It manages a detached loopback server+(`127.0.0.1:4517`) shared by all sessions, keyed by artifact path — no session+ids to track.++The workflow is a plain CLI-plus-JSON loop, so it is model- and harness-agnostic:+any agent that can run a shell command and read stdout drives it the same way+(Claude Code, Codex, Cursor, Gemini, OpenCode, Copilot). Trigger it however your+harness surfaces skills — e.g. `/plan-canvas` in Claude Code, `$plan-canvas` in+Codex — or just run the `ecc-plan-canvas` commands directly.++```bash+# 1. Open the artifact in the user's browser (returns immediately)+ecc-plan-canvas open .claude/plans/feature.plan.md++# 2. Block until the human responds. Leave running; re-run if interrupted —+# queued feedback is never lost. Run in the background if your harness+# time-limits foreground commands.+ecc-plan-canvas await .claude/plans/feature.plan.md+```++`await` prints JSON when the human acts:++```json+{+ "status": "feedback",+ "items": [+ { "kind": "annotation", "text": "Split this into two phases",+ "anchor": { "selector": "h2:nth-of-type(3)", "tag": "h2", "snippet": "Phase 2: Migration" } },+ { "kind": "verdict", "verdict": "request-changes" }+ ]+}+```++- `kind: "chat"` — freeform message; answer in the canvas, not the terminal.+- `kind: "annotation"` — feedback anchored to an element (`anchor.selector`,+ `anchor.snippet` show what they pointed at; `anchor.textRange.text` when+ they highlighted a passage).+- `kind: "verdict"` — `approve` means the plan is CONFIRMED: stop polling,+ end the session, and start implementing. `request-changes` means revise the+ artifact (the canvas live-reloads it) and keep the loop going.++**3. Respond in the canvas**, then keep listening — one command does both:++```bash+ecc-plan-canvas await <file> --reply "Split Phase 2 as requested — take a look."+```++**4. End** when review concludes: `ecc-plan-canvas end <file>`.++## Diagrams (Mermaid)++When part of the plan is a flow, architecture, sequence, state machine, ER+model, or dependency graph, author it as a fenced ` ```mermaid ` block instead+of ASCII art or a wall of prose — the canvas renders it as a themed diagram the+human can point at. Reach for it when a picture reads faster than a paragraph;+skip it for simple lists or tables.++````markdown+```mermaid+flowchart LR+ A[Market resolves] --> B{Watchers?}+ B -->|yes| C[Enqueue jobs] --> D[Fan-out worker]+```+````++Diagrams render in the ECC dark theme with the accent palette. Mermaid loads in+the browser from a pinned CDN; if that is unavailable (offline), the block+degrades to showing its source, so the review is never blocked. Point a local+mirror at `ECC_PLAN_CANVAS_MERMAID_URL` for air-gapped use.++## Rules++- Markdown artifacts render in ECC's plan template (including Mermaid blocks);+ `.html` artifacts render as-is with the annotation layer injected. For HTML+ authoring guidance use the `frontend-design-direction` and `artifact-design`+ skills.+- Edit the artifact file to revise — the canvas live-reloads on save. Never+ re-run `open` to refresh.+- `{"status": "ended", "endedBy": "user"}` (or `sessionEnded: true` on a+ feedback batch) means the user closed the review: stop polling, deliver+ remaining updates in chat, and do not reopen. A plain `open` on that+ session is refused; pass `--reopen` only when the user asks to resume.+- Sibling assets (images, CSS) must sit next to the artifact and be+ referenced by relative path.+- The server is loopback-only and exits after 30 idle minutes+ (`ECC_PLAN_CANVAS_IDLE_MS`); `stop` shuts it down explicitly. State lives+ in `~/.claude/plan-canvas/` (`ECC_PLAN_CANVAS_STATE_DIR`).++## Examples++**Plan approval flow** — `/plan` writes+`.claude/plans/notifications.plan.md` and must WAIT for confirmation:++```bash+ecc-plan-canvas open .claude/plans/notifications.plan.md+ecc-plan-canvas await .claude/plans/notifications.plan.md+# → {"status":"feedback","items":[{"kind":"verdict","verdict":"approve"}]}+ecc-plan-canvas end .claude/plans/notifications.plan.md+# plan is confirmed — begin implementation+```++**Revision loop** — feedback arrives, you edit the file, reply, keep listening:++```bash+# await returned annotations → edit the .plan.md (canvas live-reloads)+ecc-plan-canvas await <file> --reply "Reworked the risk table."+# → blocks again until the next response+```++## Anti-Patterns++- Polling with `--timeout-ms` in a loop — it exists for tests. Leave the+ plain `await` running instead.+- Reopening after a user-initiated end "just to show" something.+- Pasting the whole plan into chat *and* opening a canvas — pick the canvas+ and keep the terminal summary to one line.+- Parsing the canvas chat from state files — everything you need arrives via+ `await`.diff --git a/.agents/skills/plan-canvas/agents/openai.yaml b/.agents/skills/plan-canvas/agents/openai.yamlnew file mode 100644index 000000000..8318d3b53--- /dev/null+++ b/.agents/skills/plan-canvas/agents/openai.yaml@@ -0,0 +1,7 @@+interface:+ display_name: "Plan Canvas"+ short_description: "Browser annotate-and-approve review for plan artifacts"+ brand_color: "#6885E8"+ default_prompt: "Use $plan-canvas to open a plan in the browser for annotate-and-approve review."+policy:+ allow_implicit_invocation: truediff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 829d903e2..82392836b 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -11,7 +11,7 @@{"name": "ecc","source": "./",- "description": "Harness-native ECC operator layer - 67 agents, 277 skills, 93 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses",+ "description": "Harness-native ECC operator layer - 67 agents, 278 skills, 94 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses","version": "2.0.0","author": {"name": "Affaan Mustafa",diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 504ecbff4..16e54ca53 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ecc","version": "2.0.0",- "description": "Harness-native ECC plugin for engineering teams - 67 agents, 277 skills, 93 legacy command shims, reusable hooks, rules, MCP conventions, and operator workflows for Claude Code plus adjacent agent harnesses",+ "description": "Harness-native ECC plugin for engineering teams - 67 agents, 278 skills, 94 legacy command shims, reusable hooks, rules, MCP conventions, and operator workflows for Claude Code plus adjacent agent harnesses","author": {"name": "Affaan Mustafa","url": "https://x.com/affaanmustafa"diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdindex fdade2cda..0501050cb 100644--- a/.github/PULL_REQUEST_TEMPLATE.md+++ b/.github/PULL_REQUEST_TEMPLATE.md@@ -27,6 +27,17 @@- [ ] No sensitive data exposed in logs or output- [ ] Follows conventional commits format+## If you changed dependencies or `package.json` (`bin` / `files` / deps)+- [ ] Ran `yarn install --mode=update-lockfile` and committed the `yarn.lock` change. CI runs Yarn in hardened mode on public PRs and fails if the lockfile would be modified, so an out of date `yarn.lock` breaks the build even when nothing else is wrong.++## If you added a skill, command, agent, hook, or CLI tool+- [ ] Registered in `package.json` (`bin` and `files`), `manifests/install-components.json`, `manifests/install-modules.json`, and `agent.yaml`+- [ ] Regenerated the catalog (`npm run catalog:sync`) and command registry (`npm run command-registry:write`)+- [ ] Updated the docs tables it belongs in (`README.md`, `COMMANDS-QUICK-REF.md`, `docs/COMMAND-AGENT-MAP.md`)+- [ ] If it ships a new script path, added it to the publish surface allowlist (`tests/scripts/npm-publish-surface.test.js`)+- [ ] Cross-harness surfaces updated if applicable (for Codex, `.agents/skills/<name>/` plus `agents/openai.yaml`; the Codex frontmatter validator allows only `name`, `description`, `metadata`, `license`, `allowed-tools`, so drop keys like `version` from that copy)+- [ ] Full gauntlet passes locally (`npm test`)+## Documentation- [ ] Updated relevant documentation- [ ] Added comments for complex logicdiff --git a/AGENTS.md b/AGENTS.mdindex 2ffe06a0b..40c355be2 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -1,6 +1,6 @@# Everything Claude Code (ECC) — Agent Instructions-This is a **production-ready AI coding plugin** providing 67 specialized agents, 277 skills, 93 commands, and automated hook workflows for software development.+This is a **production-ready AI coding plugin** providing 67 specialized agents, 278 skills, 94 commands, and automated hook workflows for software development.**Version:** 2.0.0@@ -152,8 +152,8 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat```agents/ — 67 specialized subagents-skills/ — 277 workflow skills and domain knowledge-commands/ — 93 slash commands+skills/ — 278 workflow skills and domain knowledge+commands/ — 94 slash commandshooks/ — Trigger-based automationsrules/ — Always-follow guidelines (common + per-language)scripts/ — Cross-platform Node.js utilitiesdiff --git a/COMMANDS-QUICK-REF.md b/COMMANDS-QUICK-REF.mdindex b1bcab691..fff319049 100644--- a/COMMANDS-QUICK-REF.md+++ b/COMMANDS-QUICK-REF.md@@ -9,6 +9,7 @@| Command | What it does ||---------|-------------|| `/plan` | Restate requirements, assess risks, write step-by-step implementation plan — **waits for your confirm before touching code** |+| `/plan-canvas` | Open a plan or HTML artifact in the browser Plan Canvas — annotate elements, chat with the agent, approve or request changes in place || `/tdd` | Enforce test-driven development: scaffold interface → write failing test → implement → verify 80%+ coverage || `/code-review` | Full code quality, security, and maintainability review of changed files || `/build-fix` | Detect and fix build errors — delegates to the right build-resolver agent automatically |diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex ec983b4e6..8157a38c8 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -464,7 +464,19 @@ How you tested this.- [ ] Clear descriptions```-### 3. Review Process+### 3. Before You Push (avoid red CI)++Run `npm test` locally. It is the same gauntlet CI runs, and it catches almost everything below.++- **Changed `package.json`?** If you touched `bin`, `files`, or dependencies, run `yarn install --mode=update-lockfile` and commit the `yarn.lock` change. CI runs Yarn in hardened mode on public PRs and fails if the lockfile would be modified, so a stale `yarn.lock` breaks the build on its own.+- **Added a skill, command, agent, hook, or CLI tool?** Wire up every surface it belongs to:+ - `package.json` (`bin` and `files`), `manifests/install-components.json`, `manifests/install-modules.json`, and `agent.yaml`+ - Regenerate the catalog (`npm run catalog:sync`) and command registry (`npm run command-registry:write`)+ - Update the docs tables (`README.md`, `COMMANDS-QUICK-REF.md`, `docs/COMMAND-AGENT-MAP.md`)+ - New script path? Add it to the publish surface allowlist (`tests/scripts/npm-publish-surface.test.js`)+ - Cross-harness: for Codex, add `.agents/skills/<name>/` plus `agents/openai.yaml`. The Codex frontmatter validator only allows `name`, `description`, `metadata`, `license`, and `allowed-tools`, so drop keys like `version` from that copy.++### 4. Review Process1. Maintainers review within 48 hours2. Address feedback if requesteddiff --git a/README.md b/README.mdindex bdc9298bf..125692102 100644--- a/README.md+++ b/README.md@@ -439,7 +439,7 @@ If you stacked methods, clean up in this order:/plugin list ecc@ecc```-**That's it!** You now have access to 67 agents, 277 skills, and 93 legacy command shims.+**That's it!** You now have access to 67 agents, 278 skills, and 94 legacy command shims.### Dashboard GUI@@ -1533,8 +1533,8 @@ The configuration is automatically detected from `.opencode/opencode.json`.| Feature | Claude Code | OpenCode | Status ||---------|---------------------|----------|--------|| Agents | PASS: 67 agents | PASS: 12 agents | **Claude Code leads** |-| Commands | PASS: 93 commands | PASS: 35 commands | **Claude Code leads** |-| Skills | PASS: 277 skills | PASS: 37 skills | **Claude Code leads** |+| Commands | PASS: 94 commands | PASS: 35 commands | **Claude Code leads** |+| Skills | PASS: 278 skills | PASS: 37 skills | **Claude Code leads** || Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** || Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** || MCP Servers | PASS: 14 servers | PASS: Full | **Full parity** |@@ -1694,8 +1694,8 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e| Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode | GitHub Copilot ||---------|-----------------------|------------|-----------|----------|----------------|| **Agents** | 67 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 | N/A |-| **Commands** | 93 | Shared | Instruction-based | 35 | 5 prompts |-| **Skills** | 277 | Shared | 10 (native format) | 37 | Via instructions |+| **Commands** | 94 | Shared | Instruction-based | 35 | 5 prompts |+| **Skills** | 278 | Shared | 10 (native format) | 37 | Via instructions || **Hook Events** | 8 types | 15 types | None yet | 11 types | None || **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks | N/A || **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions | 1 always-on file |diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 9298011e2..1f0a94c22 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -164,7 +164,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"/plugin list ecc@ecc```-**完成!** 你现在可以使用 67 个代理、277 个技能和 93 个命令。+**完成!** 你现在可以使用 67 个代理、278 个技能和 94 个命令。### multi-* 命令需要额外配置diff --git a/agent.yaml b/agent.yamlindex a3c437884..6275ce2ee 100644--- a/agent.yaml+++ b/agent.yaml@@ -108,6 +108,7 @@ skills:- perl-security- perl-testing- plankton-code-quality+ - plan-canvas- plan-orchestrate- postgres-patterns- product-lens@@ -215,6 +216,7 @@ commands:- orch-refine-code- orch-review- plan+ - plan-canvas- plan-prd- pm2- projectsdiff --git a/commands/plan-canvas.md b/commands/plan-canvas.mdnew file mode 100644index 000000000..8fd4c63c0--- /dev/null+++ b/commands/plan-canvas.md@@ -0,0 +1,45 @@+---+description: Open a plan or HTML artifact in the browser Plan Canvas for annotate-and-approve review+argument-hint: "[path/to/artifact.plan.md | path/to/artifact.html]"+---++# Plan Canvas Command++Opens a local artifact in the Plan Canvas — ECC's browser review surface —+where the user annotates elements, chats with you, and approves the plan or+requests changes without leaving the page.++This command is a thin entry point over the `plan-canvas` skill. Follow that+skill for the full workflow and rules.++## What This Command Does++1. Resolve the artifact: the given path, else the most recently modified+ `.claude/plans/*.plan.md`, else ask what to review.+2. `ecc-plan-canvas open <artifact>` — opens the user's browser.+3. `ecc-plan-canvas await <artifact>` — block until feedback,+ verdict, or session end; leave it running.+4. Apply feedback to the artifact file (the canvas live-reloads), answer with+ `await <artifact> --reply "..."`, and repeat until the user approves or+ ends the session.++An `approve` verdict counts as plan confirmation for `/plan`-style gates:+stop polling, `end` the session, and begin implementation.++## Example++```+User: /plan-canvas .claude/plans/notifications.plan.md++Assistant: (runs open + await, browser opens)+...user clicks "Request changes" with two annotations...+Assistant: (edits the plan, replies in-canvas, awaits again)+...user clicks "Approve plan"...+Assistant: Plan approved in the canvas — starting implementation.+```++## Related++- `plan-canvas` skill — full workflow, feedback JSON shapes, rules+- `/plan` — produces the plan artifacts this reviews+- Source: `scripts/plan-canvas.js`, `scripts/lib/plan-canvas/`diff --git a/commands/plan.md b/commands/plan.mdindex aed475034..739752957 100644--- a/commands/plan.md+++ b/commands/plan.md@@ -111,6 +111,11 @@ When called with a `.prd.md` file, write the plan to `.claude/plans/{kebab-case-After writing the artifact, report its path and WAIT for confirmation before writing code.+> **Visual review:** instead of asking for a typed confirmation, you can open the+> artifact in the browser Plan Canvas (`/plan-canvas`, or the `plan-canvas` skill):+> the user annotates the plan in place and clicks **Approve plan** or **Request+> changes**, which arrives as your confirmation signal.+## Example Usage```@@ -181,6 +186,7 @@ If you want changes, respond with:## Integration with Other CommandsAfter planning:+- Use `/plan-canvas` to run the confirmation gate visually in the browser (annotate + approve)- Use the `tdd-workflow` skill to implement with test-driven development- Use `/build-fix` if build errors occur- Use `/code-review` to review completed implementationdiff --git a/docs/COMMAND-AGENT-MAP.md b/docs/COMMAND-AGENT-MAP.mdindex 70bcacfc1..d99ee12cc 100644--- a/docs/COMMAND-AGENT-MAP.md+++ b/docs/COMMAND-AGENT-MAP.md@@ -5,6 +5,7 @@ This document lists each slash command and the primary agent(s) or skills it inv| Command | Primary agent(s) | Notes ||---------|------------------|--------|| `/plan` | planner | Implementation planning before code |+| `/plan-canvas` | — (skill: plan-canvas) | Browser review canvas for plan artifacts: annotate, chat, approve/request changes || `/tdd` | tdd-guide | Test-driven development || `/code-review` | code-reviewer | Quality and security review || `/build-fix` | build-error-resolver | Fix build/type errors |diff --git a/docs/COMMAND-REGISTRY.json b/docs/COMMAND-REGISTRY.jsonindex 0e1444e68..29b1cd647 100644--- a/docs/COMMAND-REGISTRY.json+++ b/docs/COMMAND-REGISTRY.json@@ -1,6 +1,6 @@{"schemaVersion": 1,- "totalCommands": 93,+ "totalCommands": 94,"commands": [{"command": "aside",@@ -626,6 +626,17 @@"skills": [],"path": "commands/orch-review.md"},+ {+ "command": "plan-canvas",+ "description": "Open a plan or HTML artifact in the browser Plan Canvas for annotate-and-approve review",+ "type": "review",+ "primaryAgents": [],+ "allAgents": [],+ "skills": [+ "plan-canvas"+ ],+ "path": "commands/plan-canvas.md"+ },{"command": "plan-prd","description": "Generate a lean, problem-first PRD and hand off to /plan for implementation planning.",@@ -645,7 +656,9 @@"allAgents": ["planner"],- "skills": [],+ "skills": [+ "plan-canvas"+ ],"path": "commands/plan.md"},{@@ -1020,7 +1033,7 @@"orchestration": 11,"planning": 2,"refactoring": 1,- "review": 14,+ "review": 15,"testing": 53},"topAgents": [diff --git a/docs/design/assets/plan-canvas-demo.png b/docs/design/assets/plan-canvas-demo.pngnew file mode 100644index 000000000..39d8fde1fBinary files /dev/null and b/docs/design/assets/plan-canvas-demo.png differdiff --git a/docs/design/plan-canvas.md b/docs/design/plan-canvas.mdnew file mode 100644index 000000000..3de3fc733--- /dev/null+++ b/docs/design/plan-canvas.md@@ -0,0 +1,120 @@+# Plan Canvas — interactive plan review in the browser++Status: implemented (`feat/plan-canvas`)+Inspired by: [lavish-axi](https://github.com/kunchenguid/lavish-axi) by @kunchenguid, the+idea of a local, annotate-and-chat review loop over agent-generated artifacts. Plan Canvas is+an original, ECC-native implementation of that idea, not a port.++++## Problem++`/plan` ends with a hard gate: the agent writes `.claude/plans/{name}.plan.md` and WAITS for+the user to confirm. Today that review happens as a wall of markdown in the terminal, and the+feedback loop is "retype what you want changed in chat." The community has asked for the same+loop lavish-axi popularized: see the plan rendered properly, point at the part you mean, and+talk to the agent from the page.++## What it is++A loopback-only web editor for plan artifacts (and any local HTML artifact):++- The agent runs `node scripts/plan-canvas.js open <artifact>` after writing a plan.+- The artifact opens in the browser inside ECC-styled chrome (same design tokens as+ `scripts/dashboard-web.js`): dark-first, `--accent #6885e8`, accent→pink brand gradient,+ light theme toggle.+- The human reviews visually, clicks elements or selects text to attach numbered annotations,+ and chats with the agent from a side rail.+- Plan-specific verdict actions — **Approve plan** / **Request changes** — map directly onto+ `/plan`'s CONFIRM gate, so approval can happen from the canvas instead of the terminal.+- The agent blocks on `node scripts/plan-canvas.js await <artifact>` (long poll). Feedback+ arrives as JSON on stdout: chat messages, annotations with CSS-selector + text-range+ anchors, verdicts, or session-end.+- The agent replies with `await --reply "..."`, which appears in the canvas chat; edits to the+ artifact file live-reload the page.++## How it fits ECC++| Piece | Location | Follows |+|---|---|---|+| CLI entry | `scripts/plan-canvas.js` (+ npm bin `ecc-plan-canvas`) | `scripts/control-pane.js` |+| Server | `scripts/lib/plan-canvas/server.js` | control-pane loopback server, host-header + Origin allowlist (DNS-rebinding guard) |+| Editor chrome | `scripts/lib/plan-canvas/ui.js` | `scripts/lib/control-pane/ui.js`, tokens from `scripts/dashboard-web.js` |+| Markdown plan renderer | `scripts/lib/plan-canvas/markdown.js` | zero new deps; renders the `commands/plan.md` artifact schema (tables, tasks, code fences, Mermaid blocks) |+| Mermaid diagrams | `scripts/lib/plan-canvas/ui.js` | ` ```mermaid ` blocks render in the browser, themed to ECC; pinned CDN with offline fallback (`ECC_PLAN_CANVAS_MERMAID_URL` for a local mirror) |+| Session state | `scripts/lib/plan-canvas/sessions.js` | file-path-keyed sessions, state under `~/.claude/plan-canvas/` (`ECC_PLAN_CANVAS_STATE_DIR` override) |+| Skill | `skills/plan-canvas/SKILL.md` | skills-first surface; teaches the open → await → reply loop; defers visual guidance to `frontend-design-direction`, `artifact-design`, `dataviz` |+| Command shim | `commands/plan-canvas.md` | legacy parity surface, points at the skill |+| `/plan` pointer | `commands/plan.md` | after writing the artifact, offer canvas review |+| Hook (optional) | `scripts/hooks/plan-canvas-sessions.js`, `SessionStart` | surfaces open canvas sessions so a fresh session can resume a review |+| Tests | `tests/lib/plan-canvas/*`, `tests/integration/plan-canvas-e2e.test.js` | node:test-style plain assert, run by `tests/run-all.js` |++Registration: `package.json` (`bin`, `files[]`), `manifests/install-components.json`+(+ `install-modules.json` workflow-quality paths), `agent.yaml` skills list, catalog ++command-registry regeneration.++## Cross-harness / model compatibility++The feature is model- and harness-agnostic by construction: the CLI emits plain JSON and the+skill teaches a shell-plus-stdout loop, so any capable agent drives it identically — the same+"just a CLI" thesis lavish-axi uses. There is no Claude-only dependency in the core loop; the+`SessionStart` hook is an additive Claude Code convenience (other harnesses see open sessions+from a bare `ecc-plan-canvas` invocation).++Surfaces mirror how peer workflow-quality skills ship across ECC's harnesses:++- `skills/plan-canvas/` — canonical (Claude Code and the installer's per-target adapters).+- `.agents/skills/plan-canvas/` (+ `agents/openai.yaml` interface manifest) — Codex, alongside+ `tdd-workflow`, `e2e-testing`, `verification-loop`.+- `agent.yaml` skills list — the Codex gitagent manifest.+- The CLI resolves from any project via the `ecc-plan-canvas` bin (global/plugin install) or+ `$CLAUDE_PLUGIN_ROOT/scripts/plan-canvas.js`, never a cwd-relative path.++Cursor's checked-in subset is content/marketing skills only, so — matching peers — plan-canvas+is not added there; the installer still places it for Cursor from the canonical `skills/`.++## Protocol++Sessions are keyed by canonical artifact path (`sha256(realpath)[:12]`). The CLI talks to a+detached server (`server.json` in the state dir records pid/port/version; idle self-shutdown+after 30 min, `ECC_PLAN_CANVAS_IDLE_MS`). Feedback is deliver-and-drain: queued items are+handed to exactly one `await` call and persisted to disk until then, so nothing is lost if+the poll is interrupted.++- `GET /health` — `{ok, app: "ecc-plan-canvas", version}` (CLI/server version handshake)+- `GET /` — session list (ECC chrome)+- `POST /api/sessions` `{file, reopen?}` — open/resume; `409 user-ended` unless `reopen`+- `GET /canvas/<key>` — editor chrome; `GET /artifact/<key>/` — rendered artifact+ (markdown → ECC plan template, HTML passthrough) with the annotation SDK injected;+ sibling assets confined to the artifact directory+- `POST /api/session/<key>/feedback` `{items[], endSession?}` — browser queues+ chat / annotation / verdict items+- `GET /api/await?file=<path>[&timeoutMs=n]` — agent long-poll (whitespace heartbeat);+ returns `{status: feedback|ended|waiting|missing, items[], sessionEnded?, endedBy?}`+- `POST /api/session/<key>/reply` `{text}` — agent message → canvas chat+- `POST /api/session/<key>/end` (user) / `POST /api/end` `{file}` (agent) — ender recorded;+ user ends are sticky: plain `open` refuses to reopen without `--reopen`+- `GET /events/<key>` — SSE to the browser: `chat-sync`, `presence`+ (waiting/listening/working), `reload` (artifact file changed), `ended`++## Deliberate differences from lavish-axi++- Plan-first: renders `.plan.md` / `.md` natively (including Mermaid); lavish is HTML-only.+- Verdict actions wired to ECC's plan-confirmation workflow.+- ECC design tokens and chrome; JSON (not TOON) agent output.+- Mermaid renders themed to ECC, but without lavish's pan/zoom or node-id capture —+ whole-element annotation covers pointing at a diagram or node.+- No export/share hosting, no layout-audit gate, no bundled playbooks — ECC's existing+ design skills (`frontend-design-direction`, `artifact-design`, `dataviz`) cover authoring.++## Security posture++Loopback bind only by default; Host and Origin allowlist checks on every request (same+approach as control-pane); artifact served only from registered session paths with+sibling-asset access confined to the artifact directory; state dir is user-local. The server+never executes artifact content — it only serves it to the browser.++The one optional outbound request is the pinned Mermaid library, fetched by the browser only+for artifacts that contain a diagram; it renders with `securityLevel: 'strict'`, degrades to+showing diagram source if unavailable, and can be repointed at a local mirror via+`ECC_PLAN_CANVAS_MERMAID_URL`. The server itself still makes no network calls.diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.mdindex 72586c0e2..6326e8b6f 100644--- a/docs/zh-CN/AGENTS.md+++ b/docs/zh-CN/AGENTS.md@@ -1,6 +1,6 @@# Everything Claude Code (ECC) — 智能体指令-这是一个**生产就绪的 AI 编码插件**,提供 67 个专业代理、277 项技能、93 条命令以及自动化钩子工作流,用于软件开发。+这是一个**生产就绪的 AI 编码插件**,提供 67 个专业代理、278 项技能、94 条命令以及自动化钩子工作流,用于软件开发。**版本:** 2.0.0@@ -147,8 +147,8 @@```agents/ — 67 个专业子代理-skills/ — 277 个工作流技能和领域知识-commands/ — 93 个斜杠命令+skills/ — 278 个工作流技能和领域知识+commands/ — 94 个斜杠命令hooks/ — 基于触发的自动化rules/ — 始终遵循的指导方针(通用 + 每种语言)scripts/ — 跨平台 Node.js 实用工具diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.mdindex f16e8a887..1e6546b72 100644--- a/docs/zh-CN/README.md+++ b/docs/zh-CN/README.md@@ -228,7 +228,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"/plugin list ecc@ecc```-**搞定!** 你现在可以使用 67 个智能体、277 项技能和 93 个命令了。+**搞定!** 你现在可以使用 67 个智能体、278 项技能和 94 个命令了。***@@ -1141,8 +1141,8 @@ opencode| 功能特性 | Claude Code | OpenCode | 状态 ||---------|---------------|----------|--------|| 智能体 | PASS: 67 个 | PASS: 12 个 | **Claude Code 领先** |-| 命令 | PASS: 93 个 | PASS: 35 个 | **Claude Code 领先** |-| 技能 | PASS: 277 项 | PASS: 37 项 | **Claude Code 领先** |+| 命令 | PASS: 94 个 | PASS: 35 个 | **Claude Code 领先** |+| 技能 | PASS: 278 项 | PASS: 37 项 | **Claude Code 领先** || 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多!** || 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** || MCP 服务器 | PASS: 14 个 | PASS: 完整 | **完全对等** |@@ -1249,8 +1249,8 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以| 功能特性 | Claude Code | Cursor IDE | Codex CLI | OpenCode ||---------|-----------------------|------------|-----------|----------|| **智能体** | 67 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |-| **命令** | 93 | 共享 | 基于指令 | 35 |-| **技能** | 277 | 共享 | 10 (原生格式) | 37 |+| **命令** | 94 | 共享 | 基于指令 | 35 |+| **技能** | 278 | 共享 | 10 (原生格式) | 37 || **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 || **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 || **规则** | 34 (通用 + 语言) | 34 (YAML 前页) | 基于指令 | 13 条指令 |diff --git a/hooks/README.md b/hooks/README.mdindex 8df6e4f93..c9a9107fc 100644--- a/hooks/README.md+++ b/hooks/README.md@@ -63,6 +63,7 @@ That installs resolved hooks to `~/.claude/hooks/hooks.json`. On Windows, the Cl| Hook | Event | What It Does ||------|-------|-------------|| **Session start** | `SessionStart` | Loads previous context and detects package manager |+| **Plan Canvas sessions** | `SessionStart` | Surfaces open Plan Canvas browser reviews so a fresh session can resume the loop || **Pre-compact** | `PreCompact` | Saves state before context compaction || **Console.log audit** | `Stop` | Checks all modified files for `console.log` after each response || **Session summary** | `Stop` | Persists session state when transcript path is available |diff --git a/hooks/hooks.json b/hooks/hooks.jsonindex 7bfdefe1f..8367f833f 100644--- a/hooks/hooks.json+++ b/hooks/hooks.json@@ -120,6 +120,17 @@],"description": "Load previous context and detect package manager on new session","id": "session:start"+ },+ {+ "matcher": "*",+ "hooks": [+ {+ "type": "command",+ "command": "node -e \"const p=require('path');const r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();const s=p.join(r,'scripts/hooks/plugin-hook-bootstrap.js');process.env.CLAUDE_PLUGIN_ROOT=r;process.argv.splice(1,0,s);require(s)\" node scripts/hooks/run-with-flags.js session-start:plan-canvas-sessions scripts/hooks/plan-canvas-sessions.js standard,strict"+ }+ ],+ "description": "Surface open Plan Canvas review sessions so a fresh session can resume the loop",+ "id": "session-start:plan-canvas-sessions"}],"PostToolUse": [diff --git a/manifests/install-components.json b/manifests/install-components.jsonindex 9b007b3a2..471028a5a 100644--- a/manifests/install-components.json+++ b/manifests/install-components.json@@ -454,6 +454,14 @@"agents-core"]},+ {+ "id": "skill:plan-canvas",+ "family": "skill",+ "description": "Browser review canvas for plan artifacts: annotate, chat, approve or request changes.",+ "modules": [+ "workflow-quality"+ ]+ },{"id": "skill:tdd-workflow","family": "skill",diff --git a/manifests/install-modules.json b/manifests/install-modules.jsonindex ede68e3dc..de93c523c 100644--- a/manifests/install-modules.json+++ b/manifests/install-modules.json@@ -272,6 +272,7 @@"skills/eval-harness","skills/hookify-rules","skills/iterative-retrieval",+ "skills/plan-canvas","skills/plankton-code-quality","skills/production-audit","skills/skill-scout",diff --git a/package.json b/package.jsonindex 38768ae70..5e0be9b02 100644--- a/package.json+++ b/package.json@@ -107,6 +107,7 @@"scripts/lib/","scripts/list-installed.js","scripts/loop-status.js",+ "scripts/plan-canvas.js","scripts/orchestration-status.js","scripts/orchestrate-codex-worker.sh","scripts/orchestrate-worktrees.js",@@ -249,6 +250,7 @@"skills/perl-patterns/","skills/perl-security/","skills/perl-testing/",+ "skills/plan-canvas/","skills/plankton-code-quality/","skills/parallel-execution-optimizer/","skills/postgres-patterns/",@@ -326,7 +328,8 @@"bin": {"ecc": "scripts/ecc.js","ecc-control-pane": "scripts/control-pane.js",- "ecc-install": "scripts/install-apply.js"+ "ecc-install": "scripts/install-apply.js",+ "ecc-plan-canvas": "scripts/plan-canvas.js"},"scripts": {"postinstall": "echo '\\n ecc-universal installed!\\n Run: npx ecc typescript\\n Compat: npx ecc-install typescript\\n Docs: https://github.com/affaan-m/ECC\\n'",diff --git a/scripts/hooks/plan-canvas-sessions.js b/scripts/hooks/plan-canvas-sessions.jsnew file mode 100644index 000000000..4e0799f87--- /dev/null+++ b/scripts/hooks/plan-canvas-sessions.js@@ -0,0 +1,68 @@+#!/usr/bin/env node+/**+ * Plan Canvas open-session surfacing (SessionStart)+ *+ * Cross-platform (Windows, macOS, Linux)+ *+ * If a Plan Canvas review is still open from a previous agent session,+ * surface it at session start so a fresh session can resume the loop with+ * `plan-canvas await <file>` instead of leaving the human talking to an+ * empty chair in the browser.+ *+ * Never blocks: exits 0 on every error, prints nothing when there is+ * nothing to resume.+ */++'use strict';++const fs = require('fs');+const path = require('path');+const os = require('os');++function stateDir() {+ const override = process.env.ECC_PLAN_CANVAS_STATE_DIR;+ if (override && override.trim()) return path.resolve(override.trim());+ return path.join(os.homedir(), '.claude', 'plan-canvas');+}++function openSessions() {+ try {+ const parsed = JSON.parse(fs.readFileSync(path.join(stateDir(), 'sessions.json'), 'utf8'));+ return Object.values(parsed.sessions || {}).filter(session => session.status !== 'ended');+ } catch {+ return [];+ }+}++function buildContext(sessions) {+ const lines = [+ '[PlanCanvas] Open browser review sessions from a previous run:'+ ];+ for (const session of sessions.slice(0, 5)) {+ const pending = session.pendingFeedback && session.pendingFeedback.length;+ lines.push(` - ${session.file}${pending ? ` (${pending} undelivered feedback item${pending === 1 ? '' : 's'})` : ''}`);+ }+ lines.push(+ 'Resume with `node scripts/plan-canvas.js await <file>` (plan-canvas skill), or `end <file>` if the review is obsolete.'+ );+ return lines.join('\n');+}++function run() {+ const sessions = openSessions();+ if (sessions.length > 0) {+ process.stdout.write(`${buildContext(sessions)}\n`);+ }+ return 0;+}++if (require.main === module) {+ try {+ process.exit(run());+ } catch (error) {+ process.stderr.write(`[PlanCanvas] WARNING: ${error.message}\n`);+ process.exit(0);+ }+}++module.exports = { run, openSessions, buildContext };diff --git a/scripts/lib/control-pane/server.js b/scripts/lib/control-pane/server.jsindex 81f8a99ed..bfe847159 100644--- a/scripts/lib/control-pane/server.js+++ b/scripts/lib/control-pane/server.js@@ -24,42 +24,14 @@ async function withStateStore(stateDbPath, fn) {}}-const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);--// Extract the hostname portion of an HTTP Host header value, stripping any-// port. Returns null when the header is missing or malformed. Used to gate-// requests against a local-only allowlist so DNS-rebinding cannot pivot a-// browser tab into the loopback control-pane API.-function parseHostHeader(value) {- if (!value || typeof value !== 'string') return null;- const trimmed = value.trim();- if (!trimmed) return null;- const match = trimmed.match(/^(\[[^\]]+\]|[^:]+)(?::\d+)?$/);- if (!match) return null;- return match[1].toLowerCase();-}--function buildAllowedHostnames(configuredHost) {- const set = new Set(LOOPBACK_HOSTNAMES);- if (configuredHost) set.add(String(configuredHost).toLowerCase());- return set;-}--function isAllowedHostHeader(hostHeader, allowedHostnames) {- const hostname = parseHostHeader(hostHeader);- if (!hostname) return false;- return allowedHostnames.has(hostname);-}--function isAllowedOrigin(originHeader, allowedHostnames) {- if (!originHeader || typeof originHeader !== 'string') return true;- try {- const url = new URL(originHeader);- return allowedHostnames.has(url.hostname.toLowerCase());- } catch {- return false;- }-}+// Host/Origin gating lives in scripts/lib/loopback-guard.js so every ECC+// loopback server shares one hardened implementation; re-exported below to+// keep this module's public API stable.+const {+ buildAllowedHostnames,+ isAllowedHostHeader,+ isAllowedOrigin+} = require('../loopback-guard');function usage() {return [diff --git a/scripts/lib/loopback-guard.js b/scripts/lib/loopback-guard.jsnew file mode 100644index 000000000..cde3373a9--- /dev/null+++ b/scripts/lib/loopback-guard.js@@ -0,0 +1,53 @@+'use strict';++/**+ * Host/Origin gating for ECC's loopback HTTP servers (control pane, plan+ * canvas). DNS rebinding can point an attacker-controlled hostname at+ * 127.0.0.1, so every request must present a Host header from this+ * allowlist before the server does any work.+ */++const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);++// Extract the hostname portion of an HTTP Host header value, stripping any+// port. Returns null when the header is missing or malformed.+function parseHostHeader(value) {+ if (!value || typeof value !== 'string') return null;+ const trimmed = value.trim();+ if (!trimmed) return null;+ const match = trimmed.match(/^(\[[^\]]+\]|[^:]+)(?::\d+)?$/);+ if (!match) return null;+ return match[1].toLowerCase();+}++function buildAllowedHostnames(configuredHost) {+ const set = new Set(LOOPBACK_HOSTNAMES);+ if (configuredHost) set.add(String(configuredHost).toLowerCase());+ return set;+}++function isAllowedHostHeader(hostHeader, allowedHostnames) {+ const hostname = parseHostHeader(hostHeader);+ if (!hostname) return false;+ return allowedHostnames.has(hostname);+}++// Origin is absent on same-origin navigations and CLI clients; when present+// it must resolve to an allowed hostname.+function isAllowedOrigin(originHeader, allowedHostnames) {+ if (!originHeader || typeof originHeader !== 'string') return true;+ try {+ const url = new URL(originHeader);+ return allowedHostnames.has(url.hostname.toLowerCase());+ } catch {+ return false;+ }+}++module.exports = {+ LOOPBACK_HOSTNAMES,+ buildAllowedHostnames,+ isAllowedHostHeader,+ isAllowedOrigin,+ parseHostHeader+};diff --git a/scripts/lib/plan-canvas/markdown.js b/scripts/lib/plan-canvas/markdown.jsnew file mode 100644index 000000000..84799a3c4--- /dev/null+++ b/scripts/lib/plan-canvas/markdown.js@@ -0,0 +1,277 @@+'use strict';++/**+ * Minimal GitHub-flavored-markdown subset renderer for Plan Canvas.+ * Renders .claude/plans/*.plan.md artifacts to HTML body content.+ *+ * Security model: the entire source line is HTML-escaped before any inline+ * rule runs, so raw HTML in the markdown always displays as text. Link and+ * image URLs are validated against an allowlist of protocols.+ */++// Placeholders live in the Unicode private-use area so escaped output can+// never collide with them. Pre-existing occurrences are stripped from input.+const TOKEN_OPEN = '\uE000';+const TOKEN_CLOSE = '\uE001';+const TOKEN_RE = new RegExp(TOKEN_OPEN + '(\\d+)' + TOKEN_CLOSE, 'g');+const STRIP_RE = new RegExp('[' + TOKEN_OPEN + TOKEN_CLOSE + ']', 'g');++const LIST_ITEM_RE = /^(\s*)([-*]|\d+\.)\s+(.*)$/;+const HR_RE = /^ {0,3}(-{3,}|\*{3,})\s*$/;++function escapeHtml(value) {+ return String(value ?? '')+ .replace(/&/g, '&')+ .replace(/</g, '<')+ .replace(/>/g, '>')+ .replace(/"/g, '"')+ .replace(/'/g, ''');+}++function slugify(text) {+ return String(text ?? '')+ .toLowerCase()+ .replace(/[^a-z0-9\s-]/g, '')+ .trim()+ .replace(/[\s-]+/g, '-')+ .replace(/^-+|-+$/g, '');+}++// Strip whitespace/control characters so "Ja vaScript:" style tricks cannot+// hide a scheme, then classify against the allowlist.+function classifyUrl(rawUrl) {+ const compact = String(rawUrl)+ .split('')+ .filter((ch) => ch.charCodeAt(0) > 32)+ .join('')+ .toLowerCase();+ if (compact.startsWith('#')) return 'anchor';+ if (compact.startsWith('//')) return 'blocked';+ const scheme = compact.match(/^[a-z][a-z0-9+.-]*:/);+ if (!scheme) return 'relative';+ if (scheme[0] === 'http:' || scheme[0] === 'https:') return 'http';+ if (scheme[0] === 'mailto:') return 'mailto';+ return 'blocked';+}++function applyEmphasis(s) {+ return s+ .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')+ .replace(/~~([^~]+)~~/g, '<del>$1</del>')+ .replace(/\*([^*]+)\*/g, '<em>$1</em>')+ .replace(/(^|[^\w])_([^_]+)_(?!\w)/g, '$1<em>$2</em>');+}++function renderInline(rawText) {+ const tokens = [];+ const stash = (html) => {+ tokens.push(html);+ return TOKEN_OPEN + (tokens.length - 1) + TOKEN_CLOSE;+ };++ let s = escapeHtml(rawText);++ // Code spans first: contents stay escaped and opt out of all other rules.+ s = s.replace(/`([^`]+)`/g, (_m, code) => stash('<code>' + code + '</code>'));++ s = s.replace(/!\[([^\]]*)\]\(([^)]*)\)/g, (_m, alt, src) => {+ const kind = classifyUrl(src);+ if (kind !== 'http' && kind !== 'relative') return alt;+ return stash('<img src="' + src.trim() + '" alt="' + alt + '">');+ });++ s = s.replace(/\[([^\]]+)\]\(([^)]*)\)/g, (_m, label, url) => {+ const kind = classifyUrl(url);+ const text = applyEmphasis(label);+ if (kind === 'blocked') return text;+ const extra = kind === 'http' ? ' target="_blank" rel="noopener"' : '';+ return stash('<a href="' + url.trim() + '"' + extra + '>' + text + '</a>');+ });++ s = applyEmphasis(s);++ // Stashed anchors may hold code-span tokens, so resolve until none remain.+ while (s.includes(TOKEN_OPEN)) {+ s = s.replace(TOKEN_RE, (_m, idx) => tokens[Number(idx)]);+ }+ return s;+}++function splitTableRow(line) {+ let s = line.trim();+ if (s.startsWith('|')) s = s.slice(1);+ if (s.endsWith('|') && !s.endsWith('\\|')) s = s.slice(0, -1);+ return s+ .replace(/\\\|/g, TOKEN_OPEN)+ .split('|')+ .map((cell) => cell.split(TOKEN_OPEN).join('|').trim());+}++function isAlignmentRow(line) {+ if (!line || !line.includes('|')) return false;+ const cells = splitTableRow(line);+ return cells.length > 0 && cells.every((cell) => /^:?-+:?$/.test(cell));+}++function cellAlign(spec) {+ const left = spec.startsWith(':');+ const right = spec.endsWith(':');+ if (left && right) return 'center';+ if (right) return 'right';+ if (left) return 'left';+ return '';+}++function renderListItem(text) {+ const task = text.match(/^\[([ xX])\]\s+(.*)$/);+ if (task) {+ const checked = task[1].trim() ? ' checked' : '';+ return '<li class="task"><input type="checkbox" disabled' + checked + '> ' ++ renderInline(task[2]) + '</li>';+ }+ return '<li>' + renderInline(text) + '</li>';+}++function buildList(items, start, indent) {+ const tag = /^\d/.test(items[start].marker) ? 'ol' : 'ul';+ const parts = [];+ let i = start;+ while (i < items.length && items[i].indent >= indent) {+ if (items[i].indent > indent) {+ // Deeper item: nest a sublist inside the previous <li>+ const nested = buildList(items, i, items[i].indent);+ if (parts.length > 0) {+ const last = parts.pop();+ parts.push(last.replace(/<\/li>$/, '\n' + nested.html + '\n</li>'));+ } else {+ parts.push('<li>\n' + nested.html + '\n</li>');+ }+ i = nested.end;+ } else {+ parts.push(renderListItem(items[i].text));+ i += 1;+ }+ }+ return { html: '<' + tag + '>\n' + parts.join('\n') + '\n</' + tag + '>', end: i };+}++function startsBlock(line, nextLine) {+ return /^```/.test(line) ||+ /^#{1,6}\s/.test(line) ||+ HR_RE.test(line) ||+ /^ {0,3}>/.test(line) ||+ LIST_ITEM_RE.test(line) ||+ (line.includes('|') && isAlignmentRow(nextLine || ''));+}++function renderMarkdown(text) {+ if (!text) return '';+ const lines = String(text)+ .replace(STRIP_RE, '')+ .replace(/\r\n?/g, '\n')+ .split('\n');+ const out = [];+ let i = 0;++ while (i < lines.length) {+ const line = lines[i];++ if (!line.trim()) {+ i += 1;+ continue;+ }++ const fence = line.match(/^```(.*)$/);+ if (fence) {+ const lang = fence[1].trim().split(/\s+/)[0].toLowerCase().replace(/[^a-z0-9-]/g, '');+ const body = [];+ i += 1;+ while (i < lines.length && !/^```\s*$/.test(lines[i])) {+ body.push(lines[i]);+ i += 1;+ }+ i += 1; // skip closing fence (or run off EOF)+ if (lang === 'mermaid') {+ // Mermaid reads the element's textContent, and the browser decodes+ // character references there — so escaping keeps `-->`/`<` intact for+ // the renderer while preventing HTML injection or a </pre> breakout.+ out.push('<pre class="mermaid">' + escapeHtml(body.join('\n')) + '</pre>');+ continue;+ }+ const cls = lang ? ' class="language-' + lang + '"' : '';+ out.push('<pre><code' + cls + '>' + escapeHtml(body.join('\n')) + '</code></pre>');+ continue;+ }++ const heading = line.match(/^(#{1,6})\s+(.+?)\s*$/);+ if (heading) {+ const level = heading[1].length;+ out.push('<h' + level + ' id="' + slugify(heading[2]) + '">' ++ renderInline(heading[2]) + '</h' + level + '>');+ i += 1;+ continue;+ }++ // Horizontal rule (alignment rows never reach here: tables consume them)+ if (HR_RE.test(line)) {+ out.push('<hr>');+ i += 1;+ continue;+ }++ // Blockquote: strip one `>` level and recurse, which handles nesting+ if (/^ {0,3}>/.test(line)) {+ const inner = [];+ while (i < lines.length && /^ {0,3}>/.test(lines[i])) {+ inner.push(lines[i].replace(/^ {0,3}> ?/, ''));+ i += 1;+ }+ out.push('<blockquote>\n' + renderMarkdown(inner.join('\n')) + '\n</blockquote>');+ continue;+ }++ // Table: header row followed by an alignment row+ if (line.includes('|') && isAlignmentRow(lines[i + 1] || '')) {+ const aligns = splitTableRow(lines[i + 1]).map(cellAlign);+ const row = (tag, cells) => '<tr>' + cells.map((cell, idx) => {+ const style = aligns[idx] ? ' style="text-align:' + aligns[idx] + '"' : '';+ return '<' + tag + style + '>' + renderInline(cell) + '</' + tag + '>';+ }).join('') + '</tr>';+ const head = row('th', splitTableRow(line));+ const body = [];+ i += 2;+ while (i < lines.length && lines[i].trim() && lines[i].includes('|')) {+ body.push(row('td', splitTableRow(lines[i])));+ i += 1;+ }+ out.push('<table>\n<thead>\n' + head + '\n</thead>\n<tbody>\n' ++ body.join('\n') + '\n</tbody>\n</table>');+ continue;+ }++ if (LIST_ITEM_RE.test(line)) {+ const items = [];+ while (i < lines.length) {+ const m = lines[i].match(LIST_ITEM_RE);+ if (!m) break;+ items.push({ indent: m[1].length, marker: m[2], text: m[3] });+ i += 1;+ }+ out.push(buildList(items, 0, items[0].indent).html);+ continue;+ }++ // Paragraph: run of plain lines up to a blank line or block start+ const para = [line.trim()];+ i += 1;+ while (i < lines.length && lines[i].trim() && !startsBlock(lines[i], lines[i + 1])) {+ para.push(lines[i].trim());+ i += 1;+ }+ out.push('<p>' + renderInline(para.join('\n')) + '</p>');+ }++ return out.join('\n');+}++module.exports = { renderMarkdown, escapeHtml, slugify };diff --git a/scripts/lib/plan-canvas/sdk.js b/scripts/lib/plan-canvas/sdk.jsnew file mode 100644index 000000000..a5110914d--- /dev/null+++ b/scripts/lib/plan-canvas/sdk.js@@ -0,0 +1,237 @@+'use strict';++/**+ * Plan Canvas artifact SDK — the script injected into the reviewed artifact.+ *+ * The artifact runs in a sandboxed iframe without allow-same-origin, so this+ * script can only talk to the chrome via postMessage. It renders all of its+ * own UI inside a shadow root so it never annotates itself and never leaks+ * styles into the artifact.+ */++function artifactSdkJs() {+ return `'use strict';+(() => {+ if (window.parent === window) return; // only meaningful inside the canvas+ if (window.__eccPlanCanvasSdk) return;+ window.__eccPlanCanvasSdk = true;++ let annotate = true;+ let card = null;++ const post = msg => window.parent.postMessage(msg, '*');++ // --- shadow-root UI host --------------------------------------------+ const host = document.createElement('div');+ host.setAttribute('data-ecc-plan-canvas', 'ui');+ host.style.cssText = 'position:absolute;top:0;left:0;width:0;height:0;z-index:2147483647';+ const root = host.attachShadow({ mode: 'open' });+ root.innerHTML = \`+ <style>+ :host{all:initial}+ .hl{position:fixed;pointer-events:none;border:1.5px solid #6885e8;background:rgba(104,133,232,0.12);border-radius:4px;display:none;z-index:2147483646;transition:all .06s ease-out}+ .selhint{position:absolute;display:none;z-index:2147483647;background:#101218;color:#dfe2e9;border:1px solid #272c3e;border-radius:6px;padding:4px 10px;font:600 11.5px -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;cursor:pointer;box-shadow:0 8px 32px rgba(0,0,0,0.6)}+ .selhint:hover{border-color:#6885e8}+ .card{position:absolute;display:none;z-index:2147483647;width:300px;background:#101218;border:1px solid #272c3e;border-radius:8px;box-shadow:0 8px 32px rgba(0,0,0,0.6);font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;color:#dfe2e9}+ .card h4{margin:0;padding:10px 12px 0;font-size:11px;font-weight:600;text-transform:uppercase;letter-spacing:.05em;color:#80859a}+ .card .snippet{padding:4px 12px 0;font:10.5px 'SF Mono','Fira Code',monospace;color:#4acbbe;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}+ .card textarea{display:block;width:calc(100% - 24px);margin:8px 12px;min-height:56px;resize:vertical;background:#13161e;border:1px solid #1d2130;border-radius:6px;color:#dfe2e9;font:12.5px -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;padding:7px 9px;outline:none;box-sizing:border-box}+ .card textarea:focus{border-color:#6885e8}+ .card .row{display:flex;justify-content:flex-end;gap:8px;padding:0 12px 12px}+ .card button{border-radius:6px;font:600 11.5px -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;padding:5px 12px;cursor:pointer}+ .card .cancel{background:none;border:1px solid #1d2130;color:#80859a}+ .card .cancel:hover{color:#dfe2e9;border-color:#272c3e}+ .card .queue{background:#6885e8;border:1px solid #6885e8;color:#fff}+ .card .queue:hover{background:#3d5ab8}+ .card .keys{padding:0 12px 10px;font-size:9.5px;color:#4c5168}+ </style>+ <div class="hl"></div>+ <button class="selhint" type="button">Annotate selection</button>+ <div class="card">+ <h4></h4>+ <div class="snippet"></div>+ <textarea placeholder="What should change here?"></textarea>+ <div class="row">+ <button class="cancel" type="button">Cancel</button>+ <button class="queue" type="button">Queue</button>+ </div>+ <div class="keys">Enter to queue · Cmd/Ctrl+Enter to queue & send</div>+ </div>\`;+ const attach = () => document.body ? document.body.appendChild(host) : null;+ if (document.body) attach();+ else document.addEventListener('DOMContentLoaded', attach);++ const hl = root.querySelector('.hl');+ const selhint = root.querySelector('.selhint');+ const cardEl = root.querySelector('.card');+ const cardTitle = cardEl.querySelector('h4');+ const cardSnippet = cardEl.querySelector('.snippet');+ const cardText = cardEl.querySelector('textarea');++ // --- selectors & context ---------------------------------------------+ const esc = v => (window.CSS && CSS.escape) ? CSS.escape(v) : v.replace(/[^a-zA-Z0-9_-]/g, '\\\\$&');+ function selectorFor(el) {+ const parts = [];+ let node = el;+ for (let depth = 0; node && node.nodeType === 1 && depth < 6; depth++) {+ if (node.id) { parts.unshift('#' + esc(node.id)); return parts.join(' > '); }+ const tag = node.tagName.toLowerCase();+ if (tag === 'body' || tag === 'html') { parts.unshift(tag); break; }+ let nth = 1;+ let sib = node;+ while ((sib = sib.previousElementSibling)) if (sib.tagName === node.tagName) nth++;+ parts.unshift(tag + ':nth-of-type(' + nth + ')');+ node = node.parentElement;+ }+ return parts.join(' > ');+ }+ function snippetFor(el) {+ return (el.innerText || el.textContent || '').replace(/\\s+/g, ' ').trim().slice(0, 200);+ }+ const INTERACTIVE = new Set(['button', 'input', 'select', 'textarea', 'option', 'label', 'summary', 'a']);+ function isInteractive(el) {+ let node = el;+ while (node && node.nodeType === 1) {+ if (INTERACTIVE.has(node.tagName.toLowerCase()) || node.isContentEditable) return true;+ node = node.parentElement;+ }+ return false;+ }+ const isOurs = el => el === host || host.contains(el);++ // --- annotation card ---------------------------------------------------+ function openCard(target) {+ card = target;+ cardTitle.textContent = target.kindLabel;+ cardSnippet.textContent = target.anchor.snippet || target.anchor.selector;+ cardText.value = '';+ cardEl.style.display = 'block';+ const x = Math.min(target.x, window.innerWidth - 320) + window.scrollX;+ const y = target.y + 12 + window.scrollY;+ cardEl.style.left = Math.max(8, x) + 'px';+ cardEl.style.top = y + 'px';+ cardText.focus();+ }+ function closeCard() {+ card = null;+ cardEl.style.display = 'none';+ }+ function queueCard(sendNow) {+ if (!card) return;+ const text = cardText.value.trim();+ if (!text) { cardText.focus(); return; }+ post({+ type: sendNow ? 'pc:queue-and-send' : 'pc:queue',+ item: { kind: 'annotation', text, anchor: card.anchor }+ });+ closeCard();+ }+ cardEl.querySelector('.cancel').addEventListener('click', closeCard);+ cardEl.querySelector('.queue').addEventListener('click', () => queueCard(false));+ cardText.addEventListener('keydown', e => {+ if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) { e.preventDefault(); queueCard(true); }+ else if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); queueCard(false); }+ else if (e.key === 'Escape') closeCard();+ });++ // --- element hover / click ---------------------------------------------+ document.addEventListener('mousemove', e => {+ if (!annotate || card) { hl.style.display = 'none'; return; }+ const el = e.target;+ if (!el || isOurs(el) || el === document.body || el === document.documentElement || isInteractive(el)) {+ hl.style.display = 'none';+ return;+ }+ const rect = el.getBoundingClientRect();+ hl.style.display = 'block';+ hl.style.left = rect.left - 2 + 'px';+ hl.style.top = rect.top - 2 + 'px';+ hl.style.width = rect.width + 'px';+ hl.style.height = rect.height + 'px';+ }, true);++ document.addEventListener('click', e => {+ if (!annotate) return;+ const el = e.target;+ if (isOurs(el)) return;+ if (card) { if (!cardEl.contains(e.composedPath()[0])) closeCard(); return; }+ if (isInteractive(el)) return; // let controls behave natively+ const selection = window.getSelection();+ if (selection && !selection.isCollapsed) return; // handled by selection flow+ if (el === document.body || el === document.documentElement) return;+ e.preventDefault();+ e.stopPropagation();+ hl.style.display = 'none';+ openCard({+ kindLabel: 'Annotate <' + el.tagName.toLowerCase() + '>',+ anchor: { selector: selectorFor(el), tag: el.tagName.toLowerCase(), snippet: snippetFor(el) },+ x: e.clientX,+ y: e.clientY+ });+ }, true);++ // --- text selection -------------------------------------------------------+ document.addEventListener('mouseup', e => {+ if (!annotate || card || isOurs(e.target)) return;+ setTimeout(() => {+ const selection = window.getSelection();+ const text = selection ? String(selection).replace(/\\s+/g, ' ').trim() : '';+ if (!text || !selection.rangeCount) { selhint.style.display = 'none'; return; }+ const rect = selection.getRangeAt(0).getBoundingClientRect();+ selhint.style.display = 'block';+ selhint.style.left = rect.left + window.scrollX + 'px';+ selhint.style.top = rect.bottom + 6 + window.scrollY + 'px';+ selhint.onclick = () => {+ selhint.style.display = 'none';+ const anchorNode = selection.anchorNode;+ const el = anchorNode && anchorNode.nodeType === 1 ? anchorNode : anchorNode && anchorNode.parentElement;+ openCard({+ kindLabel: 'Annotate selection',+ anchor: {+ selector: el ? selectorFor(el) : 'body',+ tag: 'text',+ snippet: text.slice(0, 200),+ textRange: { text: text.slice(0, 1000) }+ },+ x: rect.left,+ y: rect.bottom+ });+ };+ }, 0);+ }, true);+ document.addEventListener('selectionchange', () => {+ const selection = window.getSelection();+ if (!selection || selection.isCollapsed) selhint.style.display = 'none';+ });++ // --- chrome bridge ---------------------------------------------------------+ window.addEventListener('message', e => {+ const msg = e.data || {};+ if (msg.type === 'pc:set-mode') {+ annotate = Boolean(msg.annotate);+ if (!annotate) { hl.style.display = 'none'; selhint.style.display = 'none'; closeCard(); }+ } else if (msg.type === 'pc:restore-scroll') {+ window.scrollTo(msg.x || 0, msg.y || 0);+ }+ });+ document.addEventListener('keydown', e => {+ if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'i') {+ e.preventDefault();+ post({ type: 'pc:toggle-mode' });+ } else if (e.key === 'Escape' && card) closeCard();+ }, true);++ let scrollTimer = null;+ window.addEventListener('scroll', () => {+ if (scrollTimer) return;+ scrollTimer = setTimeout(() => {+ scrollTimer = null;+ post({ type: 'pc:scroll', x: window.scrollX, y: window.scrollY });+ }, 150);+ }, { passive: true });++ post({ type: 'pc:ready' });+})();`;+}++module.exports = { artifactSdkJs };diff --git a/scripts/lib/plan-canvas/server.js b/scripts/lib/plan-canvas/server.jsnew file mode 100644index 000000000..28e7c2b70--- /dev/null+++ b/scripts/lib/plan-canvas/server.js@@ -0,0 +1,532 @@+'use strict';++/**+ * Plan Canvas loopback server.+ *+ * One detached process serves every open review session: the browser chrome,+ * the rendered artifact, an SSE stream for live updates, and the long-poll+ * endpoint agents block on. Sessions are keyed by canonical artifact path+ * (see sessions.js).+ */++const { EventEmitter } = require('events');+const fs = require('fs');+const http = require('http');+const path = require('path');++const { buildAllowedHostnames, isAllowedHostHeader, isAllowedOrigin } = require('../loopback-guard');+const { renderMarkdown } = require('./markdown');+const { artifactSdkJs } = require('./sdk');+const {+ canvasCss,+ canvasClientJs,+ renderCanvasHtml,+ renderMarkdownArtifactHtml,+ renderSessionListHtml+} = require('./ui');++const DEFAULT_PORT = 4517;+const DEFAULT_HOST = '127.0.0.1';+const DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000;+const MAX_BODY_BYTES = 1024 * 1024;++const CONTENT_TYPES = {+ '.css': 'text/css; charset=utf-8',+ '.gif': 'image/gif',+ '.html': 'text/html; charset=utf-8',+ '.ico': 'image/x-icon',+ '.jpeg': 'image/jpeg',+ '.jpg': 'image/jpeg',+ '.js': 'text/javascript; charset=utf-8',+ '.json': 'application/json; charset=utf-8',+ '.md': 'text/plain; charset=utf-8',+ '.mjs': 'text/javascript; charset=utf-8',+ '.png': 'image/png',+ '.svg': 'image/svg+xml',+ '.ttf': 'font/ttf',+ '.txt': 'text/plain; charset=utf-8',+ '.webp': 'image/webp',+ '.woff': 'font/woff',+ '.woff2': 'font/woff2'+};++function resolvePort(env = process.env) {+ const value = Number.parseInt(env.ECC_PLAN_CANVAS_PORT || '', 10);+ return Number.isInteger(value) && value >= 0 && value <= 65535 ? value : DEFAULT_PORT;+}++function resolveIdleTimeoutMs(env = process.env) {+ const raw = String(env.ECC_PLAN_CANVAS_IDLE_MS || '').trim().toLowerCase();+ if (raw === '0' || raw === 'off') return 0;+ const value = Number.parseInt(raw, 10);+ return Number.isInteger(value) && value > 0 ? value : DEFAULT_IDLE_TIMEOUT_MS;+}++function readJsonBody(req) {+ return new Promise((resolve, reject) => {+ let size = 0;+ const chunks = [];+ req.on('data', chunk => {+ size += chunk.length;+ if (size > MAX_BODY_BYTES) {+ reject(new Error('body too large'));+ req.destroy();+ return;+ }+ chunks.push(chunk);+ });+ req.on('end', () => {+ if (chunks.length === 0) return resolve({});+ try {+ resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));+ } catch {+ reject(new Error('invalid JSON body'));+ }+ });+ req.on('error', reject);+ });+}++function sendJson(res, statusCode, payload) {+ const body = JSON.stringify(payload);+ res.writeHead(statusCode, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });+ res.end(body);+}++function sendHtml(res, statusCode, html, { csp = true } = {}) {+ const headers = { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' };+ if (csp) {+ headers['content-security-policy'] =+ "default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-src 'self'";+ }+ res.writeHead(statusCode, headers);+ res.end(html);+}++function createPlanCanvasServer({+ store,+ host = DEFAULT_HOST,+ version = '0.0.0',+ idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,+ heartbeatMs = 15000,+ onIdleShutdown = null,+ log = () => {}+} = {}) {+ if (!store) throw new Error('createPlanCanvasServer requires a session store');++ const allowedHostnames = buildAllowedHostnames(host);+ const wake = new EventEmitter();+ wake.setMaxListeners(0);+ const sseClients = new Map(); // key -> Set<res>+ const awaitCounts = new Map(); // key -> active long-poll count+ const workingKeys = new Set(); // keys whose agent took feedback and is off working+ const watchers = new Map(); // key -> fs.FSWatcher+ let idleTimer = null;+ let closed = false;++ // --- presence + SSE ---------------------------------------------------++ function presenceFor(key) {+ const session = store.get(key);+ if (!session || session.status === 'ended') return 'ended';+ if ((awaitCounts.get(key) || 0) > 0) return 'listening';+ return workingKeys.has(key) ? 'working' : 'waiting';+ }++ function broadcast(key, event, payload) {+ const clients = sseClients.get(key);+ if (!clients) return;+ const frameText = `event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`;+ for (const client of clients) client.write(frameText);+ }++ function broadcastPresence(key) {+ broadcast(key, 'presence', { state: presenceFor(key) });+ }++ function connectionCount() {+ let total = 0;+ for (const clients of sseClients.values()) total += clients.size;+ for (const count of awaitCounts.values()) total += count;+ return total;+ }++ function armIdleTimer() {+ if (!idleTimeoutMs || closed) return;+ if (connectionCount() > 0) return;+ clearTimeout(idleTimer);+ idleTimer = setTimeout(() => {+ if (connectionCount() === 0 && !closed) {+ log('[plan-canvas] idle timeout reached, shutting down');+ if (onIdleShutdown) onIdleShutdown();+ }+ }, idleTimeoutMs);+ if (idleTimer.unref) idleTimer.unref();+ }++ function noteConnectionOpened() {+ clearTimeout(idleTimer);+ }++ function noteConnectionClosed() {+ armIdleTimer();+ }++ // --- artifact watching --------------------------------------------------++ function watchSession(session) {+ if (watchers.has(session.key)) return;+ const dir = path.dirname(session.file);+ const base = path.basename(session.file);+ let debounce = null;+ try {+ const watcher = fs.watch(dir, (eventType, filename) => {+ if (filename && filename !== base) return;+ clearTimeout(debounce);+ debounce = setTimeout(() => broadcast(session.key, 'reload', {}), 150);+ });+ watcher.on('error', () => watchers.delete(session.key));+ watchers.set(session.key, watcher);+ } catch {+ // Watching is best-effort; manual reload still works.+ }+ }++ function unwatchSession(key) {+ const watcher = watchers.get(key);+ if (watcher) {+ watcher.close();+ watchers.delete(key);+ }+ }++ // --- session actions ------------------------------------------------------++ function endSession(key, endedBy) {+ const session = store.end(key, endedBy);+ if (!session) return null;+ wake.emit(`wake:${key}`);+ broadcast(key, 'ended', { endedBy: session.endedBy });+ broadcastPresence(key);+ unwatchSession(key);+ return session;+ }++ // --- request handlers -------------------------------------------------------++ async function handleApi(req, res, url) {+ const { pathname } = url;++ if (req.method === 'POST' && pathname === '/api/sessions') {+ const body = await readJsonBody(req);+ if (!body.file || typeof body.file !== 'string') {+ return sendJson(res, 400, { error: 'file is required' });+ }+ if (!fs.existsSync(path.resolve(body.file))) {+ return sendJson(res, 404, { error: `artifact not found: ${body.file}` });+ }+ const { session, refused } = store.open(body.file, { reopen: Boolean(body.reopen) });+ if (refused) {+ return sendJson(res, 409, {+ status: 'user-ended',+ key: session.key,+ next_step: 'The user ended this review from the browser. Do not reopen it unless they ask; pass reopen:true when they do.'+ });+ }+ watchSession(session);+ broadcastPresence(session.key);+ return sendJson(res, 200, {+ status: 'open',+ key: session.key,+ file: session.file,+ url: `/canvas/${session.key}`+ });+ }++ if (req.method === 'GET' && pathname === '/api/sessions') {+ return sendJson(res, 200, { sessions: store.list() });+ }++ if (req.method === 'GET' && pathname === '/api/await') {+ const file = url.searchParams.get('file');+ if (!file) return sendJson(res, 400, { error: 'file query parameter is required' });+ const session = store.findByFile(file);+ if (!session) return sendJson(res, 200, { status: 'missing' });+ const key = session.key;+ const timeoutRaw = url.searchParams.get('timeoutMs');+ const timeoutMs = timeoutRaw === null ? null : Math.max(0, Number.parseInt(timeoutRaw, 10) || 0);++ const first = store.takeFeedback(key);+ if (first.status !== 'waiting') {+ if (first.status === 'feedback') workingKeys.add(key);+ broadcastPresence(key);+ return sendJson(res, 200, first);+ }++ // Long poll: hold the request open until feedback or session end.+ noteConnectionOpened();+ awaitCounts.set(key, (awaitCounts.get(key) || 0) + 1);+ workingKeys.delete(key);+ broadcastPresence(key);++ let settled = false;+ let heartbeat = null;+ let waitTimer = null;+ const finish = payload => {+ if (settled) return;+ settled = true;+ cleanup();+ if (payload) {+ if (payload.status === 'feedback') workingKeys.add(key);+ res.end(JSON.stringify(payload));+ }+ broadcastPresence(key);+ noteConnectionClosed();+ };+ const onWake = () => {+ const result = store.takeFeedback(key);+ if (result.status !== 'waiting') finish(result);+ };+ // Settle held polls on shutdown so server.close() can complete; the+ // CLI tells agents to simply re-run await.+ const onServerClose = () =>+ finish({ status: 'waiting', note: 'canvas server is shutting down; re-run await' });+ const cleanup = () => {+ wake.removeListener(`wake:${key}`, onWake);+ wake.removeListener('server-close', onServerClose);+ clearInterval(heartbeat);+ clearTimeout(waitTimer);+ awaitCounts.set(key, Math.max(0, (awaitCounts.get(key) || 1) - 1));+ };++ res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });+ // Leading whitespace keeps the connection visibly alive without+ // corrupting the JSON payload written at the end.+ res.write(' ');+ heartbeat = setInterval(() => {+ if (!settled) res.write(' ');+ }, heartbeatMs);+ if (timeoutMs !== null) {+ waitTimer = setTimeout(() => finish({ status: 'waiting' }), timeoutMs);+ }+ wake.on(`wake:${key}`, onWake);+ wake.once('server-close', onServerClose);+ req.on('close', () => finish(null));+ return undefined;+ }++ if (req.method === 'POST' && pathname === '/api/end') {+ const body = await readJsonBody(req);+ if (!body.file || typeof body.file !== 'string') {+ return sendJson(res, 400, { error: 'file is required' });+ }+ const session = store.findByFile(body.file);+ if (!session) return sendJson(res, 404, { error: 'no session for that file' });+ endSession(session.key, 'agent');+ return sendJson(res, 200, { status: 'ended', endedBy: 'agent' });+ }++ const sessionMatch = pathname.match(/^\/api\/session\/([a-f0-9]{12})\/(feedback|end|reply)$/);+ if (sessionMatch && req.method === 'POST') {+ const [, key, action] = sessionMatch;+ const session = store.get(key);+ if (!session) return sendJson(res, 404, { error: 'unknown session' });++ if (action === 'feedback') {+ const body = await readJsonBody(req);+ const result = store.queueFeedback(key, body.items, { endSession: Boolean(body.endSession) });+ if (!result) return sendJson(res, 409, { error: 'session already ended' });+ wake.emit(`wake:${key}`);+ broadcast(key, 'chat-sync', { chat: store.get(key).chat });+ if (body.endSession) broadcast(key, 'ended', { endedBy: 'user' });+ return sendJson(res, 200, { status: 'queued', accepted: result.accepted.length, pending: result.pending });+ }++ if (action === 'end') {+ endSession(key, 'user');+ return sendJson(res, 200, { status: 'ended', endedBy: 'user' });+ }++ if (action === 'reply') {+ const body = await readJsonBody(req);+ if (!body.text || typeof body.text !== 'string') {+ return sendJson(res, 400, { error: 'text is required' });+ }+ const entry = store.addAgentReply(key, body.text);+ broadcast(key, 'chat-sync', { chat: store.get(key).chat });+ return sendJson(res, 200, { status: 'sent', at: entry.at });+ }+ }++ return sendJson(res, 404, { error: 'not found' });+ }++ function handleEvents(req, res, key) {+ const session = store.get(key);+ if (!session) return sendJson(res, 404, { error: 'unknown session' });+ noteConnectionOpened();+ res.writeHead(200, {+ 'content-type': 'text/event-stream',+ 'cache-control': 'no-store',+ connection: 'keep-alive'+ });+ res.write(`event: chat-sync\ndata: ${JSON.stringify({ chat: session.chat })}\n\n`);+ res.write(`event: presence\ndata: ${JSON.stringify({ state: presenceFor(key) })}\n\n`);+ if (!sseClients.has(key)) sseClients.set(key, new Set());+ sseClients.get(key).add(res);+ const ping = setInterval(() => res.write(': ping\n\n'), 25000);+ if (ping.unref) ping.unref();+ req.on('close', () => {+ clearInterval(ping);+ const clients = sseClients.get(key);+ if (clients) {+ clients.delete(res);+ if (clients.size === 0) sseClients.delete(key);+ }+ noteConnectionClosed();+ });+ }++ function serveArtifact(res, key, assetPath) {+ const session = store.get(key);+ if (!session) return sendHtml(res, 404, '<h1>Unknown session</h1>');++ if (!assetPath) {+ let content;+ try {+ content = fs.readFileSync(session.file, 'utf8');+ } catch {+ return sendHtml(res, 404, `<h1>Artifact missing</h1><p>${session.file} no longer exists.</p>`, { csp: false });+ }+ const ext = path.extname(session.file).toLowerCase();+ if (ext === '.md' || ext === '.markdown') {+ const html = renderMarkdownArtifactHtml(renderMarkdown(content), {+ title: path.basename(session.file),+ sdkSrc: '/sdk.js'+ });+ return sendHtml(res, 200, html, { csp: false });+ }+ const sdkTag = '<script src="/sdk.js"></script>';+ const injected = content.includes('</body>')+ ? content.replace('</body>', `${sdkTag}\n</body>`)+ : `${content}\n${sdkTag}`;+ return sendHtml(res, 200, injected, { csp: false });+ }++ // Sibling assets resolve relative to the artifact's directory and must+ // stay confined to it.+ const baseDir = path.dirname(session.file);+ const resolved = path.resolve(baseDir, assetPath);+ if (resolved !== baseDir && !resolved.startsWith(baseDir + path.sep)) {+ return sendJson(res, 403, { error: 'asset path escapes artifact directory' });+ }+ let data;+ try {+ data = fs.readFileSync(resolved);+ } catch {+ return sendJson(res, 404, { error: 'asset not found' });+ }+ const type = CONTENT_TYPES[path.extname(resolved).toLowerCase()] || 'application/octet-stream';+ res.writeHead(200, { 'content-type': type, 'cache-control': 'no-store' });+ return res.end(data);+ }++ const server = http.createServer((req, res) => {+ if (!isAllowedHostHeader(req.headers.host, allowedHostnames)) {+ return sendJson(res, 403, { error: 'forbidden host header' });+ }+ if (!isAllowedOrigin(req.headers.origin, allowedHostnames)) {+ return sendJson(res, 403, { error: 'forbidden origin' });+ }+ const url = new URL(req.url, `http://${req.headers.host}`);+ const { pathname } = url;++ Promise.resolve()+ .then(() => {+ if (req.method === 'GET' && pathname === '/health') {+ return sendJson(res, 200, { ok: true, app: 'ecc-plan-canvas', version });+ }+ if (req.method === 'POST' && pathname === '/shutdown') {+ sendJson(res, 200, { status: 'stopping' });+ setImmediate(() => {+ if (onIdleShutdown) onIdleShutdown();+ });+ return undefined;+ }+ if (req.method === 'GET' && pathname === '/') {+ return sendHtml(res, 200, renderSessionListHtml(store.list()));+ }+ if (req.method === 'GET' && pathname === '/canvas.css') {+ res.writeHead(200, { 'content-type': 'text/css; charset=utf-8', 'cache-control': 'no-store' });+ return res.end(canvasCss());+ }+ if (req.method === 'GET' && pathname === '/client.js') {+ res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' });+ return res.end(canvasClientJs());+ }+ if (req.method === 'GET' && pathname === '/sdk.js') {+ res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' });+ return res.end(artifactSdkJs());+ }+ const canvasMatch = pathname.match(/^\/canvas\/([a-f0-9]{12})$/);+ if (req.method === 'GET' && canvasMatch) {+ const session = store.get(canvasMatch[1]);+ if (!session) return sendHtml(res, 404, '<h1>Unknown session</h1>');+ return sendHtml(res, 200, renderCanvasHtml(session));+ }+ const eventsMatch = pathname.match(/^\/events\/([a-f0-9]{12})$/);+ if (req.method === 'GET' && eventsMatch) {+ return handleEvents(req, res, eventsMatch[1]);+ }+ const artifactMatch = pathname.match(/^\/artifact\/([a-f0-9]{12})\/(.*)$/);+ if (req.method === 'GET' && artifactMatch) {+ const assetPath = decodeURIComponent(artifactMatch[2]);+ return serveArtifact(res, artifactMatch[1], assetPath || null);+ }+ if (pathname.startsWith('/api/')) {+ return handleApi(req, res, url);+ }+ return sendJson(res, 404, { error: 'not found' });+ })+ .catch(error => {+ if (!res.headersSent) sendJson(res, 400, { error: error.message });+ else res.end();+ });+ });++ function close() {+ closed = true;+ clearTimeout(idleTimer);+ for (const key of watchers.keys()) unwatchSession(key);+ for (const clients of sseClients.values()) {+ for (const client of clients) client.end();+ }+ sseClients.clear();+ wake.emit('server-close');+ return new Promise((resolve, reject) => {+ server.close(error => (error ? reject(error) : resolve()));+ // Browser keep-alive sockets would otherwise hold close() open.+ if (typeof server.closeIdleConnections === 'function') server.closeIdleConnections();+ });+ }++ function listen(port = resolvePort()) {+ return new Promise((resolve, reject) => {+ server.once('error', reject);+ server.listen(port, host, () => {+ armIdleTimer();+ resolve({ port: server.address().port, host });+ });+ });+ }++ return { server, listen, close, presenceFor, watchSession };+}++module.exports = {+ DEFAULT_HOST,+ DEFAULT_PORT,+ createPlanCanvasServer,+ resolveIdleTimeoutMs,+ resolvePort+};diff --git a/scripts/lib/plan-canvas/sessions.js b/scripts/lib/plan-canvas/sessions.jsnew file mode 100644index 000000000..799cf4b36--- /dev/null+++ b/scripts/lib/plan-canvas/sessions.js@@ -0,0 +1,269 @@+'use strict';++/**+ * Plan Canvas session store.+ *+ * Sessions are keyed by the canonical artifact file path so agents never+ * juggle opaque ids. State is persisted as JSON in the Plan Canvas state+ * dir so queued human feedback survives a server restart.+ */++const crypto = require('crypto');+const fs = require('fs');+const os = require('os');+const path = require('path');++const FEEDBACK_KINDS = new Set(['chat', 'annotation', 'verdict']);+const VERDICTS = new Set(['approve', 'request-changes']);++function resolveStateDir(env = process.env) {+ const override = env.ECC_PLAN_CANVAS_STATE_DIR;+ if (override && String(override).trim()) return path.resolve(String(override).trim());+ return path.join(os.homedir(), '.claude', 'plan-canvas');+}++// Canonicalize so `./plan.md`, symlinks, and absolute paths all land on the+// same session.+function canonicalizeArtifactPath(filePath) {+ const absolute = path.resolve(filePath);+ try {+ return fs.realpathSync(absolute);+ } catch {+ return absolute;+ }+}++function sessionKeyFor(canonicalPath) {+ return crypto.createHash('sha256').update(canonicalPath).digest('hex').slice(0, 12);+}++function nowIso() {+ return new Date().toISOString();+}++function sanitizeText(value, maxLength = 4000) {+ if (typeof value !== 'string') return '';+ return value.slice(0, maxLength);+}++// Normalize one browser-submitted feedback item into the shape delivered to+// the agent. Returns null for unusable input rather than throwing so a+// malformed item can never wedge the queue.+function normalizeFeedbackItem(raw, counter) {+ if (!raw || typeof raw !== 'object') return null;+ const kind = FEEDBACK_KINDS.has(raw.kind) ? raw.kind : null;+ if (!kind) return null;+ const item = {+ id: `fb-${counter}`,+ kind,+ text: sanitizeText(raw.text),+ at: nowIso()+ };+ if (kind === 'verdict') {+ if (!VERDICTS.has(raw.verdict)) return null;+ item.verdict = raw.verdict;+ }+ if (kind === 'annotation') {+ const anchor = raw.anchor && typeof raw.anchor === 'object' ? raw.anchor : null;+ if (!anchor || typeof anchor.selector !== 'string') return null;+ item.anchor = {+ selector: sanitizeText(anchor.selector, 500),+ tag: sanitizeText(anchor.tag, 60),+ snippet: sanitizeText(anchor.snippet, 400)+ };+ if (anchor.textRange && typeof anchor.textRange === 'object') {+ item.anchor.textRange = {+ text: sanitizeText(anchor.textRange.text, 1000)+ };+ }+ if (!item.text) return null;+ }+ if (kind === 'chat' && !item.text) return null;+ return item;+}++function createSessionStore({ stateDir = resolveStateDir() } = {}) {+ const stateFile = path.join(stateDir, 'sessions.json');+ let state = { sessions: {}, feedbackCounter: 0 };++ function load() {+ try {+ const parsed = JSON.parse(fs.readFileSync(stateFile, 'utf8'));+ if (parsed && typeof parsed === 'object' && parsed.sessions) {+ state = {+ sessions: parsed.sessions,+ feedbackCounter: Number(parsed.feedbackCounter) || 0+ };+ }+ } catch {+ // Missing or corrupt state starts fresh; queued feedback loss on a+ // corrupt file beats refusing to start at all.+ }+ }++ function persist() {+ fs.mkdirSync(stateDir, { recursive: true });+ const tmpFile = `${stateFile}.tmp`;+ fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2));+ fs.renameSync(tmpFile, stateFile);+ }++ load();++ function get(key) {+ return state.sessions[key] || null;+ }++ function findByFile(filePath) {+ const canonical = canonicalizeArtifactPath(filePath);+ return get(sessionKeyFor(canonical));+ }++ // Open (or resume) a session. A session the *user* ended from the browser+ // is sticky: it refuses a plain reopen so agents do not pop the browser+ // back up uninvited. Pass reopen:true only when the human asked.+ function open(filePath, { reopen = false } = {}) {+ const canonical = canonicalizeArtifactPath(filePath);+ const key = sessionKeyFor(canonical);+ const existing = state.sessions[key];+ if (existing && existing.status === 'ended' && existing.endedBy === 'user' && !reopen) {+ return { session: existing, refused: true };+ }+ const session = existing || {+ key,+ file: canonical,+ chat: [],+ pendingFeedback: [],+ createdAt: nowIso()+ };+ session.status = 'open';+ delete session.endedBy;+ session.updatedAt = nowIso();+ state.sessions[key] = session;+ persist();+ return { session, refused: false };+ }++ // Queue feedback from the browser. Chat-shaped items are mirrored into the+ // session transcript immediately so the conversation panel stays coherent+ // across reloads.+ function queueFeedback(key, rawItems, { endSession = false } = {}) {+ const session = get(key);+ if (!session || session.status === 'ended') return null;+ const accepted = [];+ for (const raw of Array.isArray(rawItems) ? rawItems : []) {+ state.feedbackCounter += 1;+ const item = normalizeFeedbackItem(raw, state.feedbackCounter);+ if (item) accepted.push(item);+ }+ session.pendingFeedback.push(...accepted);+ for (const item of accepted) {+ session.chat.push({ role: 'user', kind: item.kind, text: chatLineFor(item), at: item.at });+ }+ if (endSession) {+ session.status = 'ended';+ session.endedBy = 'user';+ } else if (accepted.length > 0) {+ session.status = 'feedback';+ }+ session.updatedAt = nowIso();+ persist();+ return { accepted, pending: session.pendingFeedback.length, session };+ }++ // Deliver-and-drain: feedback is handed to exactly one await call, after+ // which the session flips back to open. An ended session keeps reporting+ // ended (with attribution) so agents know to stop polling.+ function takeFeedback(key) {+ const session = get(key);+ if (!session) return { status: 'missing' };+ if (session.pendingFeedback.length > 0) {+ const items = session.pendingFeedback;+ session.pendingFeedback = [];+ const result = { status: 'feedback', items };+ if (session.status === 'ended') {+ result.sessionEnded = true;+ result.endedBy = session.endedBy;+ } else {+ session.status = 'open';+ }+ session.updatedAt = nowIso();+ persist();+ return result;+ }+ if (session.status === 'ended') {+ return { status: 'ended', endedBy: session.endedBy };+ }+ return { status: 'waiting' };+ }++ function addAgentReply(key, text) {+ const session = get(key);+ if (!session) return null;+ const entry = { role: 'agent', kind: 'chat', text: sanitizeText(text), at: nowIso() };+ session.chat.push(entry);+ session.updatedAt = nowIso();+ persist();+ return entry;+ }++ function end(key, endedBy) {+ const session = get(key);+ if (!session) return null;+ session.status = 'ended';+ session.endedBy = endedBy === 'user' ? 'user' : 'agent';+ session.updatedAt = nowIso();+ persist();+ return session;+ }++ function list() {+ return Object.values(state.sessions).map(session => ({+ key: session.key,+ file: session.file,+ status: session.status,+ endedBy: session.endedBy,+ pending: session.pendingFeedback.length,+ updatedAt: session.updatedAt+ }));+ }++ function hasOpenSessions() {+ return Object.values(state.sessions).some(session => session.status !== 'ended');+ }++ return {+ stateDir,+ stateFile,+ open,+ get,+ findByFile,+ queueFeedback,+ takeFeedback,+ addAgentReply,+ end,+ list,+ hasOpenSessions+ };+}++// One-line rendering of a feedback item for the conversation transcript.+function chatLineFor(item) {+ if (item.kind === 'verdict') {+ const label = item.verdict === 'approve' ? 'Approved the plan' : 'Requested changes';+ return item.text ? `${label}: ${item.text}` : label;+ }+ if (item.kind === 'annotation') {+ const where = item.anchor.snippet || item.anchor.selector;+ return `[${where}] ${item.text}`;+ }+ return item.text;+}++module.exports = {+ canonicalizeArtifactPath,+ createSessionStore,+ normalizeFeedbackItem,+ resolveStateDir,+ sessionKeyFor+};diff --git a/scripts/lib/plan-canvas/ui.js b/scripts/lib/plan-canvas/ui.jsnew file mode 100644index 000000000..0432282f6--- /dev/null+++ b/scripts/lib/plan-canvas/ui.js@@ -0,0 +1,542 @@+'use strict';++/**+ * Plan Canvas browser chrome: the editor shell that frames an artifact,+ * plus the rendered-markdown artifact template.+ *+ * Visual language mirrors the ECC web dashboard (scripts/dashboard-web.js):+ * same design tokens, dark-first with a light theme, accent→pink brand+ * gradient. Everything is served inline — no CDNs, no external assets.+ */++const path = require('path');++const { escapeHtml } = require('./markdown');++// Pinned Mermaid ESM build, loaded in the browser only when an artifact+// actually contains a diagram. Override with a local/vendored URL (e.g. an+// air-gapped mirror) via ECC_PLAN_CANVAS_MERMAID_URL. If the fetch fails, the+// diagram source stays visible as a styled code block — nothing breaks.+const DEFAULT_MERMAID_URL = 'https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.esm.min.mjs';++function mermaidUrl(env = process.env) {+ const override = env.ECC_PLAN_CANVAS_MERMAID_URL;+ return override && String(override).trim() ? String(override).trim() : DEFAULT_MERMAID_URL;+}++// Browser module that renders `<pre class="mermaid">` blocks, themed to match+// the ECC canvas. Kept import-only so a CDN failure degrades gracefully.+function mermaidLoaderScript(url) {+ return `<script type="module">+ try {+ const mermaid = (await import(${JSON.stringify(url)})).default;+ mermaid.initialize({+ startOnLoad: false,+ securityLevel: 'strict',+ theme: 'dark',+ fontFamily: "-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif",+ themeVariables: {+ primaryColor: '#13161e', primaryBorderColor: '#6885e8', primaryTextColor: '#dfe2e9',+ lineColor: '#80859a', secondaryColor: '#191d2a', tertiaryColor: '#101218',+ background: '#080a0e', mainBkg: '#13161e', clusterBkg: '#0d0f14'+ }+ });+ await mermaid.run({ querySelector: '.mermaid' });+ } catch (err) {+ document.querySelectorAll('.mermaid').forEach(el => el.classList.add('mermaid-unrendered'));+ console.warn('Mermaid render skipped:', err && err.message);+ }+</script>`;+}++// Design tokens shared by the chrome and the markdown artifact template.+const TOKENS_CSS = `+ :root{+ --bg:#080a0e; --bg2:#0d0f14; --bg3:#13161e; --bg4:#191d2a;+ --surface:#101218; --surface-hover:#171a24; --border:#1d2130; --border-light:#272c3e;+ --text:#dfe2e9; --text2:#80859a; --text3:#4c5168;+ --accent:#6885e8; --accent-glow:rgba(104,133,232,0.15); --accent-dim:#3d5ab8;+ --green:#4acb8a; --green-glow:rgba(74,203,138,0.15);+ --orange:#eca85a; --orange-glow:rgba(236,168,90,0.15);+ --pink:#e26a9e; --pink-glow:rgba(226,106,158,0.15);+ --red:#e86060; --red-glow:rgba(232,96,96,0.15);+ --teal:#4acbbe; --teal-glow:rgba(74,203,190,0.15);+ --radius:8px; --radius-sm:5px;+ --font:-apple-system,BlinkMacSystemFont,'SF Pro Display','Inter','Segoe UI',Roboto,sans-serif;+ --mono:'SF Mono','Fira Code','JetBrains Mono','Cascadia Code',monospace;+ --shadow:0 1px 2px rgba(0,0,0,0.4);+ --shadow-lg:0 8px 32px rgba(0,0,0,0.6);+ }+ [data-theme="light"]{+ --bg:#f4f5f7; --bg2:#ffffff; --bg3:#eaecef; --bg4:#dfe2e6;+ --surface:#ffffff; --surface-hover:#f4f5f7; --border:#cdd1d9; --border-light:#dde1e8;+ --text:#181b23; --text2:#585e6e; --text3:#9197a8;+ --accent:#4560d0; --accent-glow:rgba(69,96,208,0.08); --accent-dim:#2f44a0;+ --green:#16a34a; --green-glow:rgba(22,163,74,0.08);+ --orange:#d97706; --orange-glow:rgba(217,119,6,0.08);+ --pink:#c73877; --pink-glow:rgba(199,56,119,0.08);+ --red:#dc2626; --red-glow:rgba(220,38,38,0.08);+ --teal:#0d9488; --teal-glow:rgba(13,148,136,0.08);+ --shadow:0 1px 2px rgba(0,0,0,0.04);+ --shadow-lg:0 8px 32px rgba(0,0,0,0.08);+ }+`;++function canvasCss() {+ return `${TOKENS_CSS}+ *{margin:0;padding:0;box-sizing:border-box}+ html,body{height:100%}+ body{font-family:var(--font);background:var(--bg);color:var(--text);-webkit-font-smoothing:antialiased;line-height:1.4;overflow:hidden}+ ::selection{background:var(--accent);color:#fff}+ ::-webkit-scrollbar{width:8px;height:8px}+ ::-webkit-scrollbar-track{background:transparent}+ ::-webkit-scrollbar-thumb{background:var(--border);border-radius:4px}+ button{font-family:var(--font)}++ .bar{display:flex;align-items:center;gap:12px;height:52px;padding:0 16px;background:color-mix(in srgb,var(--bg2) 88%,transparent);border-bottom:1px solid var(--border);backdrop-filter:blur(16px)}+ .brand{display:flex;align-items:center;gap:9px;min-width:0}+ .brand .logo{width:26px;height:26px;flex:none;background:linear-gradient(135deg,var(--accent),var(--pink));border-radius:6px;display:flex;align-items:center;justify-content:center;font-size:13px;font-weight:700;color:#fff}+ .brand .name{font-size:13.5px;font-weight:600;white-space:nowrap}+ .brand .file{font-size:11.5px;color:var(--text2);font-family:var(--mono);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:34vw}+ .bar .spacer{flex:1}++ .presence{display:flex;align-items:center;gap:6px;font-size:11px;font-weight:500;color:var(--text2);background:var(--bg3);border:1px solid var(--border);border-radius:99px;padding:3px 10px 3px 8px;white-space:nowrap}+ .presence .dot{width:7px;height:7px;border-radius:99px;background:var(--text3)}+ .presence[data-state="listening"] .dot{background:var(--green);box-shadow:0 0 0 3px var(--green-glow);animation:pulse 2s infinite}+ .presence[data-state="working"] .dot{background:var(--orange);box-shadow:0 0 0 3px var(--orange-glow)}+ @keyframes pulse{0%,100%{opacity:1}50%{opacity:.45}}++ .toggle{display:flex;align-items:center;gap:7px;font-size:11.5px;color:var(--text2);cursor:pointer;user-select:none}+ .toggle .track{width:30px;height:17px;border-radius:99px;background:var(--bg4);border:1px solid var(--border);position:relative;transition:background .15s}+ .toggle .knob{position:absolute;top:1px;left:1px;width:13px;height:13px;border-radius:99px;background:var(--text2);transition:transform .15s,background .15s}+ .toggle[aria-pressed="true"] .track{background:var(--accent);border-color:var(--accent-dim)}+ .toggle[aria-pressed="true"] .knob{transform:translateX(13px);background:#fff}++ .icon-btn{height:28px;padding:0 10px;border-radius:6px;border:1px solid var(--border);background:var(--bg3);color:var(--text2);cursor:pointer;font-size:11.5px;display:flex;align-items:center;gap:5px;transition:all .12s}+ .icon-btn:hover{border-color:var(--border-light);color:var(--text);background:var(--bg4)}+ .icon-btn.danger:hover{border-color:var(--red);color:var(--red);background:var(--red-glow)}++ .layout{display:flex;height:calc(100% - 52px)}+ .frame{flex:1;min-width:0;position:relative;background:var(--bg2)}+ .frame iframe{width:100%;height:100%;border:0;background:#fff}+ [data-theme] .frame iframe{background:var(--bg2)}++ .panel{width:340px;flex:none;display:flex;flex-direction:column;border-left:1px solid var(--border);background:var(--bg2)}+ .panel h2{font-size:11px;font-weight:600;letter-spacing:.06em;text-transform:uppercase;color:var(--text3);padding:12px 14px 8px}++ .verdict{display:flex;gap:8px;padding:0 14px 12px;border-bottom:1px solid var(--border)}+ .verdict button{flex:1;height:30px;border-radius:6px;font-size:12px;font-weight:600;cursor:pointer;transition:all .12s}+ .verdict .approve{border:1px solid var(--green);background:var(--green-glow);color:var(--green)}+ .verdict .approve:hover{background:var(--green);color:#fff}+ .verdict .changes{border:1px solid var(--orange);background:var(--orange-glow);color:var(--orange)}+ .verdict .changes:hover{background:var(--orange);color:#fff}++ .chat{flex:1;overflow-y:auto;padding:10px 14px;display:flex;flex-direction:column;gap:8px}+ .msg{max-width:92%;padding:7px 10px;border-radius:10px;font-size:12.5px;white-space:pre-wrap;word-break:break-word}+ .msg.user{align-self:flex-end;background:var(--accent-glow);border:1px solid color-mix(in srgb,var(--accent) 35%,transparent);color:var(--text);border-bottom-right-radius:3px}+ .msg.agent{align-self:flex-start;background:var(--bg3);border:1px solid var(--border);color:var(--text);border-bottom-left-radius:3px}+ .msg .meta{display:block;font-size:9.5px;color:var(--text3);margin-top:3px}+ .msg.kind-annotation{border-left:2px solid var(--teal)}+ .msg.kind-verdict{border-left:2px solid var(--green)}+ .chat .empty{color:var(--text3);font-size:12px;text-align:center;margin-top:24px;line-height:1.6}++ .queue{padding:8px 14px 0;display:flex;flex-direction:column;gap:6px;max-height:180px;overflow-y:auto}+ .pill{display:flex;align-items:flex-start;gap:8px;background:var(--bg3);border:1px solid var(--border);border-left:2px solid var(--teal);border-radius:6px;padding:6px 8px;font-size:11.5px}+ .pill.kind-chat{border-left-color:var(--accent)}+ .pill.kind-verdict{border-left-color:var(--green)}+ .pill .where{color:var(--teal);font-family:var(--mono);font-size:10px;display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}+ .pill .body{flex:1;min-width:0;color:var(--text2)}+ .pill .txt{display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--text)}+ .pill button{border:none;background:none;color:var(--text3);cursor:pointer;font-size:13px;line-height:1;padding:1px}+ .pill button:hover{color:var(--red)}++ .composer{padding:10px 14px 14px;border-top:1px solid var(--border);display:flex;flex-direction:column;gap:8px}+ .composer .hint{font-size:10px;color:var(--text3)}+ .composer textarea{width:100%;min-height:60px;max-height:160px;resize:vertical;background:var(--bg3);border:1px solid var(--border);border-radius:6px;padding:8px 10px;color:var(--text);font-size:12.5px;font-family:var(--font);outline:none;transition:all .15s}+ .composer textarea:focus{border-color:var(--accent);box-shadow:0 0 0 3px var(--accent-glow)}+ .composer .row{display:flex;gap:8px;align-items:center}+ .composer .send{flex:1;height:32px;border:none;border-radius:6px;background:var(--accent);color:#fff;font-size:12.5px;font-weight:600;cursor:pointer;transition:all .12s}+ .composer .send:hover{background:var(--accent-dim)}+ .composer .send:disabled{opacity:.5;cursor:default}+ .composer .status{font-size:10.5px;color:var(--text3)}++ .overlay{position:absolute;inset:0;display:none;align-items:center;justify-content:center;background:color-mix(in srgb,var(--bg) 80%,transparent);backdrop-filter:blur(6px);z-index:50}+ .overlay.show{display:flex}+ .overlay .card{background:var(--surface);border:1px solid var(--border);border-radius:var(--radius);box-shadow:var(--shadow-lg);padding:26px 32px;text-align:center;max-width:340px}+ .overlay .card h3{font-size:14px;margin-bottom:6px}+ .overlay .card p{font-size:12px;color:var(--text2);line-height:1.5}+ `;+}++// Client logic for the chrome page (runs in the top window).+function canvasClientJs() {+ return `'use strict';+(() => {+ const boot = JSON.parse(document.getElementById('pc-session').textContent);+ const key = boot.key;+ const $ = id => document.getElementById(id);+ const frame = $('artifact');+ const chatLog = $('chatLog');+ const queueEl = $('queue');+ const input = $('chatInput');+ const sendBtn = $('send');+ const statusEl = $('sendStatus');+ const presence = $('presence');+ const QKEY = 'ecc-plan-canvas:queue:' + key;+ let queue = [];+ let lastScroll = { x: 0, y: 0 };+ let ended = boot.status === 'ended';+ let sending = false;++ try { queue = JSON.parse(sessionStorage.getItem(QKEY) || '[]'); } catch { queue = []; }++ // --- theme ---------------------------------------------------------+ const themeKey = 'ecc-plan-canvas:theme';+ function applyTheme(t) {+ if (t === 'light') document.documentElement.setAttribute('data-theme', 'light');+ else document.documentElement.removeAttribute('data-theme');+ $('themeBtn').textContent = t === 'light' ? '\\u263E dark' : '\\u2600 light';+ }+ let theme = localStorage.getItem(themeKey) || 'dark';+ applyTheme(theme);+ $('themeBtn').addEventListener('click', () => {+ theme = theme === 'light' ? 'dark' : 'light';+ localStorage.setItem(themeKey, theme);+ applyTheme(theme);+ });++ // --- annotate mode -------------------------------------------------+ let annotate = true;+ function setAnnotate(on) {+ annotate = on;+ $('annotate').setAttribute('aria-pressed', String(on));+ postToFrame({ type: 'pc:set-mode', annotate: on });+ }+ $('annotate').addEventListener('click', () => setAnnotate(!annotate));+ document.addEventListener('keydown', e => {+ if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'i') {+ e.preventDefault();+ setAnnotate(!annotate);+ }+ }, true);++ // --- iframe bridge --------------------------------------------------+ function postToFrame(msg) {+ if (frame.contentWindow) frame.contentWindow.postMessage(msg, '*');+ }+ window.addEventListener('message', e => {+ if (e.source !== frame.contentWindow) return;+ const msg = e.data || {};+ if (msg.type === 'pc:queue' && msg.item) addToQueue(msg.item);+ else if (msg.type === 'pc:queue-and-send' && msg.item) { addToQueue(msg.item); send(); }+ else if (msg.type === 'pc:scroll') lastScroll = { x: msg.x || 0, y: msg.y || 0 };+ else if (msg.type === 'pc:toggle-mode') setAnnotate(!annotate);+ else if (msg.type === 'pc:ready') {+ postToFrame({ type: 'pc:set-mode', annotate });+ postToFrame({ type: 'pc:restore-scroll', x: lastScroll.x, y: lastScroll.y });+ }+ });++ // --- queue ----------------------------------------------------------+ function persistQueue() { try { sessionStorage.setItem(QKEY, JSON.stringify(queue)); } catch { /* full */ } }+ function addToQueue(item) { queue.push(item); persistQueue(); renderQueue(); }+ function renderQueue() {+ queueEl.innerHTML = '';+ queue.forEach((item, i) => {+ const pill = document.createElement('div');+ pill.className = 'pill kind-' + item.kind;+ const body = document.createElement('span');+ body.className = 'body';+ if (item.anchor) {+ const where = document.createElement('span');+ where.className = 'where';+ where.textContent = item.anchor.snippet || item.anchor.selector;+ body.appendChild(where);+ }+ const txt = document.createElement('span');+ txt.className = 'txt';+ txt.textContent = item.kind === 'verdict' ? (item.verdict === 'approve' ? 'Approve plan' : 'Request changes') + (item.text ? ': ' + item.text : '') : item.text;+ body.appendChild(txt);+ const rm = document.createElement('button');+ rm.textContent = '\\u00D7';+ rm.title = 'Remove';+ rm.addEventListener('click', () => { queue.splice(i, 1); persistQueue(); renderQueue(); });+ pill.append(body, rm);+ queueEl.appendChild(pill);+ });+ }+ renderQueue();++ // --- chat -----------------------------------------------------------+ function renderChat(entries) {+ chatLog.innerHTML = '';+ if (!entries.length) {+ const empty = document.createElement('div');+ empty.className = 'empty';+ empty.textContent = 'Click anything in the plan to annotate it, or type below. Feedback goes straight to your agent.';+ chatLog.appendChild(empty);+ return;+ }+ for (const entry of entries) {+ const div = document.createElement('div');+ div.className = 'msg ' + (entry.role === 'agent' ? 'agent' : 'user') + ' kind-' + (entry.kind || 'chat');+ div.textContent = entry.text;+ const meta = document.createElement('span');+ meta.className = 'meta';+ meta.textContent = (entry.role === 'agent' ? 'agent' : 'you') + ' \\u00B7 ' + new Date(entry.at).toLocaleTimeString();+ div.appendChild(meta);+ chatLog.appendChild(div);+ }+ chatLog.scrollTop = chatLog.scrollHeight;+ }+ renderChat(boot.chat || []);++ // --- send -----------------------------------------------------------+ async function send(extraItems) {+ if (ended || sending) return;+ const items = queue.slice();+ if (extraItems) items.push(...extraItems);+ const text = input.value.trim();+ if (text) items.push({ kind: 'chat', text });+ if (!items.length) {+ statusEl.textContent = 'Nothing to send yet - annotate the plan or type a message.';+ return;+ }+ sending = true;+ sendBtn.disabled = true;+ statusEl.textContent = 'Sending\\u2026';+ try {+ const res = await fetch('/api/session/' + key + '/feedback', {+ method: 'POST',+ headers: { 'content-type': 'application/json' },+ body: JSON.stringify({ items })+ });+ if (!res.ok) throw new Error('HTTP ' + res.status);+ queue = [];+ persistQueue();+ renderQueue();+ input.value = '';+ statusEl.textContent = 'Sent. Your agent picks this up on its next check-in.';+ } catch (err) {+ statusEl.textContent = 'Send failed (' + err.message + ') - is the canvas server still running?';+ } finally {+ sending = false;+ sendBtn.disabled = ended;+ }+ }+ sendBtn.addEventListener('click', () => send());+ input.addEventListener('keydown', e => {+ if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); send(); }+ });+ $('approve').addEventListener('click', () => send([{ kind: 'verdict', verdict: 'approve' }]));+ $('changes').addEventListener('click', () => send([{ kind: 'verdict', verdict: 'request-changes' }]));++ // --- session controls ------------------------------------------------+ $('reloadBtn').addEventListener('click', reloadArtifact);+ $('endBtn').addEventListener('click', async () => {+ if (!window.confirm('End this review session?')) return;+ try { await fetch('/api/session/' + key + '/end', { method: 'POST' }); } catch { /* server gone */ }+ });+ function reloadArtifact() {+ const base = frame.getAttribute('data-artifact-src');+ frame.src = base + '?t=' + Date.now();+ }+ function markEnded(endedBy) {+ ended = true;+ sendBtn.disabled = true;+ input.disabled = true;+ presence.setAttribute('data-state', 'ended');+ presence.querySelector('.label').textContent = 'session ended';+ $('endedOverlay').classList.add('show');+ $('endedWho').textContent = endedBy === 'agent'+ ? 'Your agent closed this review.'+ : 'You ended this review. Head back to your agent session.';+ }+ if (ended) markEnded(boot.endedBy);++ // --- server events ----------------------------------------------------+ const PRESENCE_LABELS = { waiting: 'agent not connected', listening: 'agent listening', working: 'agent working\\u2026' };+ function connectEvents() {+ const es = new EventSource('/events/' + key);+ es.addEventListener('chat-sync', e => renderChat(JSON.parse(e.data).chat || []));+ es.addEventListener('presence', e => {+ const state = JSON.parse(e.data).state;+ if (ended) return;+ presence.setAttribute('data-state', state);+ presence.querySelector('.label').textContent = PRESENCE_LABELS[state] || state;+ });+ es.addEventListener('reload', reloadArtifact);+ es.addEventListener('ended', e => { markEnded(JSON.parse(e.data).endedBy); es.close(); });+ es.onerror = () => {+ if (ended) return;+ presence.setAttribute('data-state', 'waiting');+ presence.querySelector('.label').textContent = 'canvas server offline';+ };+ }+ connectEvents();+})();`;+}++// The chrome page: header bar, artifact iframe, conversation rail.+function renderCanvasHtml(session, { clientPath = '/client.js', cssPath = '/canvas.css' } = {}) {+ const name = path.basename(session.file);+ const bootstrap = JSON.stringify({+ key: session.key,+ file: session.file,+ status: session.status,+ endedBy: session.endedBy || null,+ chat: session.chat+ }).replace(/</g, '\\u003c');+ const artifactSrc = `/artifact/${session.key}/`;+ return `<!DOCTYPE html>+<html lang="en">+<head>+<meta charset="utf-8">+<meta name="viewport" content="width=device-width, initial-scale=1">+<title>${escapeHtml(name)} · Plan Canvas</title>+<link rel="stylesheet" href="${cssPath}">+<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><defs><linearGradient id='g' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='%236885e8'/><stop offset='1' stop-color='%23e26a9e'/></linearGradient></defs><rect width='100' height='100' rx='22' fill='url(%23g)'/><text x='50' y='68' font-size='52' font-weight='700' font-family='sans-serif' fill='white' text-anchor='middle'>E</text></svg>">+</head>+<body>+<script id="pc-session" type="application/json">${bootstrap}</script>+<header class="bar">+ <div class="brand">+ <div class="logo">E</div>+ <span class="name">Plan Canvas</span>+ <span class="file" title="${escapeHtml(session.file)}">${escapeHtml(name)}</span>+ </div>+ <div class="spacer"></div>+ <div id="presence" class="presence" data-state="waiting"><span class="dot"></span><span class="label">agent not connected</span></div>+ <div id="annotate" class="toggle" role="switch" aria-pressed="true" title="Toggle annotate mode (Cmd/Ctrl+I)">+ <span>Annotate</span><span class="track"><span class="knob"></span></span>+ </div>+ <button id="themeBtn" class="icon-btn" type="button">light</button>+ <button id="reloadBtn" class="icon-btn" type="button" title="Reload artifact">Reload</button>+ <button id="endBtn" class="icon-btn danger" type="button">End session</button>+</header>+<div class="layout">+ <main class="frame">+ <iframe id="artifact" title="Artifact under review" src="${artifactSrc}" data-artifact-src="${artifactSrc}" sandbox="allow-scripts allow-forms allow-popups"></iframe>+ <div id="endedOverlay" class="overlay"><div class="card"><h3>Session ended</h3><p id="endedWho"></p></div></div>+ </main>+ <aside class="panel">+ <h2>Plan verdict</h2>+ <div class="verdict">+ <button id="approve" class="approve" type="button">Approve plan</button>+ <button id="changes" class="changes" type="button">Request changes</button>+ </div>+ <h2>Conversation</h2>+ <div id="chatLog" class="chat"></div>+ <div id="queue" class="queue"></div>+ <div class="composer">+ <textarea id="chatInput" placeholder="Message your agent Enter to send · Shift+Enter for a new line"></textarea>+ <div class="row">+ <button id="send" class="send" type="button">Send to agent</button>+ </div>+ <div id="sendStatus" class="status"></div>+ <div class="hint">Annotations queue up here until you send them together.</div>+ </div>+ </aside>+</div>+<script src="${clientPath}"></script>+</body>+</html>`;+}++// ECC-styled document template for rendered markdown plan artifacts.+function renderMarkdownArtifactHtml(bodyHtml, { title, sdkSrc }) {+ const hasMermaid = bodyHtml.includes('class="mermaid"');+ return `<!DOCTYPE html>+<html lang="en">+<head>+<meta charset="utf-8">+<meta name="viewport" content="width=device-width, initial-scale=1">+<title>${escapeHtml(title)}</title>+<style>+${TOKENS_CSS}+ *{margin:0;padding:0;box-sizing:border-box}+ body{font-family:var(--font);background:var(--bg);color:var(--text);-webkit-font-smoothing:antialiased;line-height:1.65;font-size:14.5px}+ .doc{max-width:860px;margin:0 auto;padding:44px 36px 90px}+ h1,h2,h3,h4,h5,h6{line-height:1.25;margin:1.6em 0 .55em;letter-spacing:-.01em}+ h1{font-size:26px;margin-top:.3em;padding-bottom:.45em;border-bottom:1px solid var(--border)}+ h1:after{content:'';display:block;width:56px;height:3px;margin-top:14px;border-radius:2px;background:linear-gradient(90deg,var(--accent),var(--pink))}+ h2{font-size:19px;padding-bottom:.3em;border-bottom:1px solid var(--border)}+ h3{font-size:15.5px}+ h4,h5,h6{font-size:13.5px;color:var(--text2);text-transform:uppercase;letter-spacing:.05em}+ p,ul,ol,blockquote,table,pre{margin-bottom:.9em}+ ul,ol{padding-left:1.5em}+ li{margin:.25em 0}+ li.task{list-style:none;margin-left:-1.3em}+ li.task input{margin-right:.5em;accent-color:var(--accent)}+ a{color:var(--accent);text-decoration:none;border-bottom:1px solid var(--accent-glow)}+ a:hover{border-bottom-color:var(--accent)}+ code{font-family:var(--mono);font-size:.88em;background:var(--bg3);border:1px solid var(--border);border-radius:4px;padding:.12em .38em}+ pre{background:var(--bg3);border:1px solid var(--border);border-radius:var(--radius);padding:14px 16px;overflow-x:auto}+ pre code{background:none;border:none;padding:0;font-size:12.5px;line-height:1.55}+ blockquote{border-left:3px solid var(--accent);background:var(--accent-glow);border-radius:0 var(--radius-sm) var(--radius-sm) 0;padding:8px 14px;color:var(--text2)}+ table{width:100%;border-collapse:collapse;font-size:13px;display:block;overflow-x:auto}+ th,td{text-align:left;padding:7px 12px;border:1px solid var(--border)}+ th{background:var(--bg3);font-weight:600;font-size:11.5px;text-transform:uppercase;letter-spacing:.04em;color:var(--text2);white-space:nowrap}+ tbody tr:hover{background:var(--surface-hover)}+ hr{border:none;border-top:1px solid var(--border);margin:1.6em 0}+ img{max-width:100%;border-radius:var(--radius-sm)}+ pre.mermaid{font-family:var(--mono);font-size:12.5px;line-height:1.55;white-space:pre-wrap}+ pre.mermaid[data-processed]{background:transparent;border:none;padding:4px 0;text-align:center;overflow-x:auto}+ pre.mermaid[data-processed] svg{max-width:100%;height:auto}+ pre.mermaid.mermaid-unrendered:before{content:'diagram source (renderer unavailable)';display:block;font-family:var(--font);font-size:10.5px;text-transform:uppercase;letter-spacing:.05em;color:var(--text3);margin-bottom:6px}+</style>+</head>+<body>+<article class="doc">+${bodyHtml}+</article>+${hasMermaid ? mermaidLoaderScript(mermaidUrl()) : ''}+<script src="${sdkSrc}"></script>+</body>+</html>`;+}++// Landing page listing sessions (GET /).+function renderSessionListHtml(sessions) {+ const rows = sessions.map(s => {+ const status = s.status === 'ended' ? `ended by ${escapeHtml(s.endedBy || 'agent')}` : s.status;+ const link = s.status === 'ended'+ ? escapeHtml(path.basename(s.file))+ : `<a href="/canvas/${escapeHtml(s.key)}">${escapeHtml(path.basename(s.file))}</a>`;+ return `<tr><td>${link}</td><td class="mono">${escapeHtml(s.file)}</td><td><span class="badge ${escapeHtml(s.status)}">${status}</span></td></tr>`;+ }).join('\n');+ return `<!DOCTYPE html>+<html lang="en">+<head>+<meta charset="utf-8">+<title>Plan Canvas · sessions</title>+<style>+${TOKENS_CSS}+ *{margin:0;padding:0;box-sizing:border-box}+ body{font-family:var(--font);background:var(--bg);color:var(--text);padding:40px;line-height:1.5}+ .logo{width:30px;height:30px;background:linear-gradient(135deg,var(--accent),var(--pink));border-radius:7px;display:inline-flex;align-items:center;justify-content:center;font-weight:700;color:#fff;margin-right:10px;vertical-align:middle}+ h1{font-size:18px;display:inline-block;vertical-align:middle}+ table{margin-top:24px;border-collapse:collapse;width:100%;max-width:900px;font-size:13px}+ th,td{text-align:left;padding:8px 12px;border-bottom:1px solid var(--border)}+ th{color:var(--text3);font-size:11px;text-transform:uppercase;letter-spacing:.05em}+ a{color:var(--accent);text-decoration:none}+ .mono{font-family:var(--mono);font-size:11.5px;color:var(--text2)}+ .badge{font-size:11px;padding:2px 8px;border-radius:99px;background:var(--bg3);border:1px solid var(--border);color:var(--text2)}+ .badge.open,.badge.feedback{color:var(--green);border-color:var(--green);background:var(--green-glow)}+ .empty{margin-top:24px;color:var(--text3);font-size:13px}+</style>+</head>+<body>+<span class="logo">E</span><h1>Plan Canvas sessions</h1>+${sessions.length ? `<table><thead><tr><th>Artifact</th><th>Path</th><th>Status</th></tr></thead><tbody>${rows}</tbody></table>` : '<p class="empty">No sessions yet. Ask your agent to open a plan with the plan-canvas skill.</p>'}+</body>+</html>`;+}++module.exports = {+ canvasCss,+ canvasClientJs,+ renderCanvasHtml,+ renderMarkdownArtifactHtml,+ renderSessionListHtml+};diff --git a/scripts/plan-canvas.js b/scripts/plan-canvas.jsnew file mode 100755index 000000000..3f1206817--- /dev/null+++ b/scripts/plan-canvas.js@@ -0,0 +1,339 @@+#!/usr/bin/env node+'use strict';++/**+ * Plan Canvas CLI — open plan artifacts in a browser review canvas and block+ * on human feedback.+ *+ * node scripts/plan-canvas.js open .claude/plans/feature.plan.md+ * node scripts/plan-canvas.js await .claude/plans/feature.plan.md+ * node scripts/plan-canvas.js await <file> --reply "Updated section 3."+ * node scripts/plan-canvas.js end <file>+ * node scripts/plan-canvas.js stop+ *+ * Agents: `open` returns immediately (the server is a detached process);+ * `await` long-polls until the human sends feedback, a verdict, or ends the+ * session, then prints a JSON payload to stdout. Progress notes go to stderr+ * so stdout stays parseable.+ */++const fs = require('fs');+const http = require('http');+const path = require('path');+const { spawn } = require('child_process');++const {+ canonicalizeArtifactPath,+ createSessionStore,+ resolveStateDir,+ sessionKeyFor+} = require('./lib/plan-canvas/sessions');+const {+ DEFAULT_HOST,+ createPlanCanvasServer,+ resolveIdleTimeoutMs,+ resolvePort+} = require('./lib/plan-canvas/server');++const VERSION = require('../package.json').version;++function usage() {+ return [+ 'Plan Canvas - review plans and HTML artifacts in the browser',+ '',+ 'Usage:',+ ' node scripts/plan-canvas.js Show server status and sessions',+ ' node scripts/plan-canvas.js open <file> Open (or resume) a review session',+ ' node scripts/plan-canvas.js await <file> Block until the human sends feedback',+ ' node scripts/plan-canvas.js end <file> End a session as the agent',+ ' node scripts/plan-canvas.js stop Shut down the canvas server',+ ' node scripts/plan-canvas.js server Run the server in the foreground',+ '',+ 'Options:',+ ' open: --no-open Do not launch a browser window',+ ' --reopen Reopen a session the user ended from the browser',+ ' await: --reply <msg> Show an agent reply in the canvas chat before waiting',+ ' --timeout-ms <n> Return {status:"waiting"} after n ms (tests/debug only)',+ ' server: --port <n> --host <h>',+ '',+ 'Environment: ECC_PLAN_CANVAS_PORT, ECC_PLAN_CANVAS_STATE_DIR, ECC_PLAN_CANVAS_IDLE_MS'+ ].join('\n');+}++function valueAfter(args, name) {+ const index = args.indexOf(name);+ return index >= 0 && index + 1 < args.length ? args[index + 1] : null;+}++function serverInfoPath(stateDir) {+ return path.join(stateDir, 'server.json');+}++function readServerInfo(stateDir) {+ try {+ return JSON.parse(fs.readFileSync(serverInfoPath(stateDir), 'utf8'));+ } catch {+ return null;+ }+}++function request(port, method, requestPath, body = null) {+ return new Promise((resolve, reject) => {+ const payload = body === null ? null : JSON.stringify(body);+ const req = http.request(+ {+ host: DEFAULT_HOST,+ port,+ method,+ path: requestPath,+ headers: payload+ ? { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) }+ : {}+ },+ res => {+ let data = '';+ res.on('data', chunk => {+ data += chunk;+ });+ res.on('end', () => {+ try {+ resolve({ statusCode: res.statusCode, body: JSON.parse(data.trim() || '{}') });+ } catch {+ resolve({ statusCode: res.statusCode, body: {} });+ }+ });+ }+ );+ req.on('error', reject);+ if (payload) req.write(payload);+ req.end();+ });+}++async function healthCheck(port) {+ try {+ const res = await request(port, 'GET', '/health');+ return res.body && res.body.app === 'ecc-plan-canvas' ? res.body : null;+ } catch {+ return null;+ }+}++function sleep(ms) {+ return new Promise(resolve => setTimeout(resolve, ms));+}++// Start (or reuse) the detached canvas server and return its port. A version+// mismatch after an ECC update restarts the server so browser and CLI never+// disagree about the protocol.+async function ensureServer({ stateDir, port }) {+ const health = await healthCheck(port);+ if (health && health.version === VERSION) return port;+ if (health) {+ await request(port, 'POST', '/shutdown').catch(() => {});+ for (let i = 0; i < 20 && (await healthCheck(port)); i++) await sleep(100);+ }+ fs.mkdirSync(stateDir, { recursive: true });+ const logFd = fs.openSync(path.join(stateDir, 'server.log'), 'a');+ const child = spawn(process.execPath, [__filename, 'server', '--port', String(port)], {+ detached: true,+ stdio: ['ignore', logFd, logFd],+ env: { ...process.env, ECC_PLAN_CANVAS_STATE_DIR: stateDir }+ });+ child.unref();+ fs.closeSync(logFd);+ for (let i = 0; i < 50; i++) {+ await sleep(100);+ if (await healthCheck(port)) return port;+ }+ throw new Error(`plan-canvas server did not become healthy on port ${port}; check ${path.join(stateDir, 'server.log')}`);+}++function openBrowser(url) {+ const platform = process.platform;+ const [cmd, args] =+ platform === 'darwin' ? ['open', [url]]+ : platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]+ : ['xdg-open', [url]];+ try {+ spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();+ return true;+ } catch {+ return false;+ }+}++function output(payload) {+ process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);+}++async function cmdStatus({ stateDir, port }) {+ const health = await healthCheck(port);+ if (!health) {+ return { server: 'not running', hint: 'open an artifact to start one', stateDir };+ }+ const sessions = await request(port, 'GET', '/api/sessions');+ return { server: `http://${DEFAULT_HOST}:${port}`, version: health.version, sessions: sessions.body.sessions };+}++async function cmdOpen(file, args, { stateDir, port }) {+ if (!file) throw new Error('open requires a file path');+ if (!fs.existsSync(path.resolve(file))) throw new Error(`artifact not found: ${file}`);+ await ensureServer({ stateDir, port });+ const res = await request(port, 'POST', '/api/sessions', {+ file: path.resolve(file),+ reopen: args.includes('--reopen')+ });+ if (res.statusCode === 409) return res.body;+ if (res.statusCode !== 200) throw new Error(res.body.error || `open failed (HTTP ${res.statusCode})`);+ const url = `http://${DEFAULT_HOST}:${port}${res.body.url}`;+ const launched = args.includes('--no-open') ? false : openBrowser(url);+ return {+ status: 'open',+ url,+ browser: launched ? 'opened' : 'not opened',+ next_step:+ 'Run `ecc-plan-canvas await <file>` and leave it running; it returns when the human sends feedback, a verdict, or ends the session.'+ };+}++function awaitRequest(port, file, timeoutMs) {+ const params = new URLSearchParams({ file });+ if (timeoutMs !== null) params.set('timeoutMs', String(timeoutMs));+ return new Promise((resolve, reject) => {+ const req = http.request(+ { host: DEFAULT_HOST, port, method: 'GET', path: `/api/await?${params}` },+ res => {+ let data = '';+ res.on('data', chunk => {+ data += chunk;+ });+ res.on('end', () => {+ try {+ resolve(JSON.parse(data.trim()));+ } catch {+ reject(new Error('await response was not JSON (server restarted?) - re-run await; feedback is never lost'));+ }+ });+ }+ );+ req.setTimeout(0);+ req.on('error', reject);+ req.end();+ });+}++async function cmdAwait(file, args, { stateDir, port }) {+ if (!file) throw new Error('await requires a file path');+ if (!(await healthCheck(port))) {+ return { status: 'no-server', hint: 'no canvas server is running; use `open` first', stateDir };+ }+ const reply = valueAfter(args, '--reply');+ if (reply) {+ const key = sessionKeyFor(canonicalizeArtifactPath(file));+ await request(port, 'POST', `/api/session/${key}/reply`, { text: reply });+ }+ const timeoutRaw = valueAfter(args, '--timeout-ms');+ const timeoutMs = timeoutRaw === null ? null : Number.parseInt(timeoutRaw, 10) || 0;+ process.stderr.write('[plan-canvas] waiting for human feedback... leave this running (re-run if interrupted; queued feedback is never lost)\n');+ const result = await awaitRequest(port, path.resolve(file), timeoutMs);+ if (result.status === 'feedback') {+ result.next_step = result.sessionEnded+ ? 'The user sent this feedback and ended the session. Address it and report in chat; do not reopen the canvas uninvited.'+ : 'Address the feedback, then run `ecc-plan-canvas await <file> --reply "<what you changed>"` to answer in the canvas and keep listening.';+ } else if (result.status === 'ended') {+ result.next_step =+ result.endedBy === 'user'+ ? 'The user ended this review. Stop polling and deliver any remaining updates in chat; do not reopen uninvited.'+ : 'Session ended. Stop polling.';+ }+ return result;+}++async function cmdEnd(file, { port }) {+ if (!file) throw new Error('end requires a file path');+ if (!(await healthCheck(port))) return { status: 'no-server' };+ const res = await request(port, 'POST', '/api/end', { file: path.resolve(file) });+ return res.body;+}++async function cmdStop({ stateDir, port }) {+ if (!(await healthCheck(port))) return { status: 'not running' };+ await request(port, 'POST', '/shutdown').catch(() => {});+ fs.rmSync(serverInfoPath(stateDir), { force: true });+ return { status: 'stopping' };+}++async function cmdServer(args, { stateDir, port }) {+ const portArg = valueAfter(args, '--port');+ const hostArg = valueAfter(args, '--host');+ const listenPort = portArg !== null ? Number.parseInt(portArg, 10) : port;+ const store = createSessionStore({ stateDir });+ let shuttingDown = false;+ const shutdown = async code => {+ if (shuttingDown) return;+ shuttingDown = true;+ fs.rmSync(serverInfoPath(stateDir), { force: true });+ await canvas.close().catch(() => {});+ process.exit(code);+ };+ const canvas = createPlanCanvasServer({+ store,+ host: hostArg || DEFAULT_HOST,+ version: VERSION,+ idleTimeoutMs: resolveIdleTimeoutMs(),+ onIdleShutdown: () => shutdown(0),+ log: line => process.stderr.write(`${line}\n`)+ });+ const bound = await canvas.listen(listenPort);+ fs.mkdirSync(stateDir, { recursive: true });+ fs.writeFileSync(+ serverInfoPath(stateDir),+ JSON.stringify({ pid: process.pid, port: bound.port, version: VERSION, startedAt: new Date().toISOString() }, null, 2)+ );+ // Sessions restored from disk resume their file watchers.+ for (const session of store.list()) {+ if (session.status !== 'ended') canvas.watchSession(store.get(session.key));+ }+ process.on('SIGINT', () => shutdown(0));+ process.on('SIGTERM', () => shutdown(0));+ process.stderr.write(`[plan-canvas] serving on http://${bound.host}:${bound.port}\n`);+ return new Promise(() => {}); // run until a signal or idle shutdown+}++async function main(argv = process.argv.slice(2)) {+ const args = argv.slice();+ if (args.includes('--help') || args.includes('-h')) {+ process.stdout.write(`${usage()}\n`);+ return 0;+ }+ const command = args[0] && !args[0].startsWith('--') ? args.shift() : null;+ const stateDir = resolveStateDir();+ // A running server may sit on a non-default port; trust its recorded info.+ const recorded = readServerInfo(stateDir);+ const context = { stateDir, port: (recorded && recorded.port) || resolvePort() };+ try {+ if (command === null) output(await cmdStatus(context));+ else if (command === 'open') output(await cmdOpen(args[0], args, context));+ else if (command === 'await') output(await cmdAwait(args[0], args, context));+ else if (command === 'end') output(await cmdEnd(args[0], context));+ else if (command === 'stop') output(await cmdStop(context));+ else if (command === 'server') await cmdServer(args, context);+ else {+ process.stderr.write(`Unknown command: ${command}\n\n${usage()}\n`);+ return 1;+ }+ return 0;+ } catch (error) {+ output({ error: error.message });+ return 1;+ }+}++if (require.main === module) {+ main().then(code => {+ process.exitCode = code;+ });+}++module.exports = { main, ensureServer, healthCheck };diff --git a/skills/plan-canvas/SKILL.md b/skills/plan-canvas/SKILL.mdnew file mode 100644index 000000000..342033fde--- /dev/null+++ b/skills/plan-canvas/SKILL.md@@ -0,0 +1,153 @@+---+name: plan-canvas+description: Open plans and HTML artifacts in a local browser canvas where the human annotates elements, chats, and approves or requests changes without leaving the page. Use when presenting a plan for review, or when feedback like "move this, change that" is easier pointed at than typed.+metadata:+ origin: ECC+version: "1.0.0"+---++# Plan Canvas++Review loop for plans and visual artifacts: you write the artifact, the human+reviews it in the browser — annotating the exact element they mean, chatting,+and delivering an **Approve plan / Request changes** verdict — while you block+on a single CLI call that returns their feedback as JSON.++Inspired by [lavish-axi](https://github.com/kunchenguid/lavish-axi); rebuilt+ECC-native around the `/plan` confirmation gate, with zero dependencies.++## When to Use++- You just wrote a plan artifact (`.claude/plans/*.plan.md` from `/plan`) and+ need the CONFIRM/approve decision — the canvas verdict replaces a typed+ "yes/proceed".+- The user should *point at* what to change: reviewing designs, comparisons,+ reports, or any local `.md` / `.html` artifact.+- The user asks for `/plan-canvas`, a visual review, or "open it in the browser".++Do NOT use for: code review of diffs (`/code-review`), running web apps, or+remote URLs. The canvas serves local artifact files only.++## How It Works++Invoke the CLI as `ecc-plan-canvas` — the bin shipped by the `ecc-universal`+package (on PATH after a global/plugin install; `node "$CLAUDE_PLUGIN_ROOT/scripts/plan-canvas.js"`+also works for plugin installs). Run it from the project you are reviewing in;+it works from any working directory. It manages a detached loopback server+(`127.0.0.1:4517`) shared by all sessions, keyed by artifact path — no session+ids to track.++The workflow is a plain CLI-plus-JSON loop, so it is model- and harness-agnostic:+any agent that can run a shell command and read stdout drives it the same way+(Claude Code, Codex, Cursor, Gemini, OpenCode, Copilot). Trigger it however your+harness surfaces skills — e.g. `/plan-canvas` in Claude Code, `$plan-canvas` in+Codex — or just run the `ecc-plan-canvas` commands directly.++```bash+# 1. Open the artifact in the user's browser (returns immediately)+ecc-plan-canvas open .claude/plans/feature.plan.md++# 2. Block until the human responds. Leave running; re-run if interrupted —+# queued feedback is never lost. Run in the background if your harness+# time-limits foreground commands.+ecc-plan-canvas await .claude/plans/feature.plan.md+```++`await` prints JSON when the human acts:++```json+{+ "status": "feedback",+ "items": [+ { "kind": "annotation", "text": "Split this into two phases",+ "anchor": { "selector": "h2:nth-of-type(3)", "tag": "h2", "snippet": "Phase 2: Migration" } },+ { "kind": "verdict", "verdict": "request-changes" }+ ]+}+```++- `kind: "chat"` — freeform message; answer in the canvas, not the terminal.+- `kind: "annotation"` — feedback anchored to an element (`anchor.selector`,+ `anchor.snippet` show what they pointed at; `anchor.textRange.text` when+ they highlighted a passage).+- `kind: "verdict"` — `approve` means the plan is CONFIRMED: stop polling,+ end the session, and start implementing. `request-changes` means revise the+ artifact (the canvas live-reloads it) and keep the loop going.++**3. Respond in the canvas**, then keep listening — one command does both:++```bash+ecc-plan-canvas await <file> --reply "Split Phase 2 as requested — take a look."+```++**4. End** when review concludes: `ecc-plan-canvas end <file>`.++## Diagrams (Mermaid)++When part of the plan is a flow, architecture, sequence, state machine, ER+model, or dependency graph, author it as a fenced ` ```mermaid ` block instead+of ASCII art or a wall of prose — the canvas renders it as a themed diagram the+human can point at. Reach for it when a picture reads faster than a paragraph;+skip it for simple lists or tables.++````markdown+```mermaid+flowchart LR+ A[Market resolves] --> B{Watchers?}+ B -->|yes| C[Enqueue jobs] --> D[Fan-out worker]+```+````++Diagrams render in the ECC dark theme with the accent palette. Mermaid loads in+the browser from a pinned CDN; if that is unavailable (offline), the block+degrades to showing its source, so the review is never blocked. Point a local+mirror at `ECC_PLAN_CANVAS_MERMAID_URL` for air-gapped use.++## Rules++- Markdown artifacts render in ECC's plan template (including Mermaid blocks);+ `.html` artifacts render as-is with the annotation layer injected. For HTML+ authoring guidance use the `frontend-design-direction` and `artifact-design`+ skills.+- Edit the artifact file to revise — the canvas live-reloads on save. Never+ re-run `open` to refresh.+- `{"status": "ended", "endedBy": "user"}` (or `sessionEnded: true` on a+ feedback batch) means the user closed the review: stop polling, deliver+ remaining updates in chat, and do not reopen. A plain `open` on that+ session is refused; pass `--reopen` only when the user asks to resume.+- Sibling assets (images, CSS) must sit next to the artifact and be+ referenced by relative path.+- The server is loopback-only and exits after 30 idle minutes+ (`ECC_PLAN_CANVAS_IDLE_MS`); `stop` shuts it down explicitly. State lives+ in `~/.claude/plan-canvas/` (`ECC_PLAN_CANVAS_STATE_DIR`).++## Examples++**Plan approval flow** — `/plan` writes+`.claude/plans/notifications.plan.md` and must WAIT for confirmation:++```bash+ecc-plan-canvas open .claude/plans/notifications.plan.md+ecc-plan-canvas await .claude/plans/notifications.plan.md+# → {"status":"feedback","items":[{"kind":"verdict","verdict":"approve"}]}+ecc-plan-canvas end .claude/plans/notifications.plan.md+# plan is confirmed — begin implementation+```++**Revision loop** — feedback arrives, you edit the file, reply, keep listening:++```bash+# await returned annotations → edit the .plan.md (canvas live-reloads)+ecc-plan-canvas await <file> --reply "Reworked the risk table."+# → blocks again until the next response+```++## Anti-Patterns++- Polling with `--timeout-ms` in a loop — it exists for tests. Leave the+ plain `await` running instead.+- Reopening after a user-initiated end "just to show" something.+- Pasting the whole plan into chat *and* opening a canvas — pick the canvas+ and keep the terminal summary to one line.+- Parsing the canvas chat from state files — everything you need arrives via+ `await`.diff --git a/tests/hooks/plan-canvas-sessions-hook.test.js b/tests/hooks/plan-canvas-sessions-hook.test.jsnew file mode 100644index 000000000..5e8c3ee2d--- /dev/null+++ b/tests/hooks/plan-canvas-sessions-hook.test.js@@ -0,0 +1,100 @@+/**+ * Integration tests for scripts/hooks/plan-canvas-sessions.js (SessionStart)+ *+ * Run with: node tests/hooks/plan-canvas-sessions-hook.test.js+ */++const assert = require('assert');+const fs = require('fs');+const os = require('os');+const path = require('path');+const { spawnSync } = require('child_process');++const HOOK = path.join(__dirname, '..', '..', 'scripts', 'hooks', 'plan-canvas-sessions.js');++function test(name, fn) {+ try {+ fn();+ console.log(` ✓ ${name}`);+ return true;+ } catch (err) {+ console.log(` ✗ ${name}`);+ console.log(` Error: ${err.message}`);+ return false;+ }+}++function runHook(stateDir) {+ return spawnSync('node', [HOOK], {+ encoding: 'utf8',+ input: '{}',+ env: { ...process.env, ECC_PLAN_CANVAS_STATE_DIR: stateDir }+ });+}++function writeState(stateDir, sessions) {+ fs.mkdirSync(stateDir, { recursive: true });+ fs.writeFileSync(path.join(stateDir, 'sessions.json'), JSON.stringify({ sessions }));+}++function runTests() {+ console.log('\n=== Testing plan-canvas-sessions hook ===\n');++ let passed = 0;+ let failed = 0;+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-canvas-hook-'));++ if (test('exits 0 and prints nothing when no state exists', () => {+ const result = runHook(path.join(tmp, 'missing'));+ assert.strictEqual(result.status, 0);+ assert.strictEqual(result.stdout, '');+ })) passed++; else failed++;++ if (test('exits 0 and prints nothing when all sessions are ended', () => {+ const dir = path.join(tmp, 'ended');+ writeState(dir, {+ abc123abc123: { key: 'abc123abc123', file: '/x/plan.md', status: 'ended', endedBy: 'user', pendingFeedback: [] }+ });+ const result = runHook(dir);+ assert.strictEqual(result.status, 0);+ assert.strictEqual(result.stdout, '');+ })) passed++; else failed++;++ if (test('surfaces open sessions with resume guidance', () => {+ const dir = path.join(tmp, 'open');+ writeState(dir, {+ abc123abc123: {+ key: 'abc123abc123',+ file: '/projects/x/.claude/plans/feature.plan.md',+ status: 'feedback',+ pendingFeedback: [{ id: 'fb-1' }, { id: 'fb-2' }]+ }+ });+ const result = runHook(dir);+ assert.strictEqual(result.status, 0);+ assert.ok(result.stdout.includes('[PlanCanvas]'));+ assert.ok(result.stdout.includes('/projects/x/.claude/plans/feature.plan.md'));+ assert.ok(result.stdout.includes('2 undelivered feedback items'));+ assert.ok(result.stdout.includes('plan-canvas.js await'));+ })) passed++; else failed++;++ if (test('exits 0 on corrupt state (never blocks session start)', () => {+ const dir = path.join(tmp, 'corrupt');+ fs.mkdirSync(dir, { recursive: true });+ fs.writeFileSync(path.join(dir, 'sessions.json'), '{nope');+ const result = runHook(dir);+ assert.strictEqual(result.status, 0);+ assert.strictEqual(result.stdout, '');+ })) passed++; else failed++;++ fs.rmSync(tmp, { recursive: true, force: true });++ console.log('\n' + '='.repeat(40));+ console.log(`Passed: ${passed}`);+ console.log(`Failed: ${failed}`);+ console.log('='.repeat(40));++ process.exit(failed > 0 ? 1 : 0);+}++runTests();diff --git a/tests/integration/plan-canvas-e2e.test.js b/tests/integration/plan-canvas-e2e.test.jsnew file mode 100644index 000000000..e4c971a95--- /dev/null+++ b/tests/integration/plan-canvas-e2e.test.js@@ -0,0 +1,265 @@+/**+ * End-to-end test for Plan Canvas: the complete review workflow through the+ * real CLI (scripts/plan-canvas.js) and a real detached server process, with+ * the browser side simulated over the same HTTP surface the chrome uses.+ *+ * Flow under test:+ * agent: open --no-open → detached server starts, session opens+ * browser: loads canvas + artifact+ * agent: await (blocking child) → long poll+ * browser: POST annotation + request-changes verdict+ * agent: await resolves with feedback JSON+ * agent: edits plan, await --reply → reply lands in canvas chat+ * browser: POST end → user end is sticky+ * agent: open refused / --reopen works / end / stop+ *+ * Run with: node tests/integration/plan-canvas-e2e.test.js+ */++const assert = require('assert');+const fs = require('fs');+const http = require('http');+const os = require('os');+const path = require('path');+const { spawn, spawnSync } = require('child_process');++const CLI = path.join(__dirname, '..', '..', 'scripts', 'plan-canvas.js');+const HOOK = path.join(__dirname, '..', '..', 'scripts', 'hooks', 'plan-canvas-sessions.js');++const results = [];+async function test(name, fn) {+ try {+ await fn();+ console.log(` ✓ ${name}`);+ results.push(true);+ } catch (err) {+ console.log(` ✗ ${name}`);+ console.log(` Error: ${err.stack || err.message}`);+ results.push(false);+ }+}++function cli(env, args, { timeoutMs = 15000 } = {}) {+ const result = spawnSync('node', [CLI, ...args], {+ encoding: 'utf8',+ timeout: timeoutMs,+ env: { ...process.env, ...env }+ });+ let parsed = null;+ try {+ parsed = JSON.parse(result.stdout.trim());+ } catch {+ // leave null; callers assert+ }+ return { ...result, parsed };+}++function request(port, method, requestPath, body = null) {+ return new Promise((resolve, reject) => {+ const payload = body === null ? null : JSON.stringify(body);+ const req = http.request(+ {+ host: '127.0.0.1',+ port,+ method,+ path: requestPath,+ agent: false,+ headers: payload ? { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) } : {}+ },+ res => {+ let data = '';+ res.on('data', chunk => {+ data += chunk;+ });+ res.on('end', () => resolve({ statusCode: res.statusCode, body: data }));+ }+ );+ req.on('error', reject);+ if (payload) req.write(payload);+ req.end();+ });+}++async function main() {+ console.log('\n=== Plan Canvas end-to-end workflow ===\n');++ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-canvas-e2e-'));+ const stateDir = path.join(tmp, 'state');+ const plansDir = path.join(tmp, '.claude', 'plans');+ fs.mkdirSync(plansDir, { recursive: true });+ const plan = path.join(plansDir, 'notifications.plan.md');+ fs.writeFileSync(+ plan,+ [+ '# Plan: Real-Time Notifications',+ '',+ '**Complexity**: Medium',+ '',+ '## Summary',+ 'Notify users when watched markets resolve.',+ '',+ '## Files to Change',+ '| File | Action | Why |',+ '|---|---|---|',+ '| `lib/notify.ts` | CREATE | delivery service |',+ '',+ '## Tasks',+ '### Task 1: Schema',+ '- **Action**: add notifications table',+ '- **Validate**: `npm test`',+ ''+ ].join('\n')+ );++ // Unique port so the test never collides with a user's real canvas server.+ const port = 20000 + Math.floor(Math.random() * 20000);+ const env = { ECC_PLAN_CANVAS_STATE_DIR: stateDir, ECC_PLAN_CANVAS_PORT: String(port) };+ let key = null;++ try {+ await test('agent opens the plan: detached server starts, session created', async () => {+ const result = cli(env, ['open', plan, '--no-open']);+ assert.strictEqual(result.status, 0, result.stderr);+ assert.strictEqual(result.parsed.status, 'open');+ assert.ok(result.parsed.url.includes(`127.0.0.1:${port}/canvas/`));+ key = result.parsed.url.split('/canvas/')[1];+ const info = JSON.parse(fs.readFileSync(path.join(stateDir, 'server.json'), 'utf8'));+ assert.strictEqual(info.port, port);+ });++ await test('browser loads the canvas chrome and the rendered plan', async () => {+ const chrome = await request(port, 'GET', `/canvas/${key}`);+ assert.strictEqual(chrome.statusCode, 200);+ assert.ok(chrome.body.includes('Plan Canvas'));+ assert.ok(chrome.body.includes('notifications.plan.md'));+ const doc = await request(port, 'GET', `/artifact/${key}/`);+ assert.ok(doc.body.includes('<h1 id="plan-real-time-notifications">'));+ assert.ok(doc.body.includes('lib/notify.ts'));+ assert.ok(doc.body.includes('/sdk.js'));+ });++ await test('SessionStart hook surfaces the open review', async () => {+ const hook = spawnSync('node', [HOOK], { encoding: 'utf8', input: '{}', env: { ...process.env, ...env } });+ assert.strictEqual(hook.status, 0);+ assert.ok(hook.stdout.includes('notifications.plan.md'));+ });++ let awaitChild = null;+ let awaitStdout = '';+ const awaitExit = () =>+ new Promise(resolve => {+ awaitChild.on('close', resolve);+ });++ await test('agent blocks on await; user annotation + verdict resolve it', async () => {+ awaitChild = spawn('node', [CLI, 'await', plan], { env: { ...process.env, ...env } });+ awaitChild.stdout.on('data', chunk => {+ awaitStdout += chunk;+ });+ const exited = awaitExit();+ // Queued-then-drained semantics make this race-free: feedback posted+ // before the poll attaches is delivered the moment it does.+ const post = await request(port, 'POST', `/api/session/${key}/feedback`, {+ items: [+ {+ kind: 'annotation',+ text: 'Also notify via webhook, not just email',+ anchor: { selector: 'h3:nth-of-type(1)', tag: 'h3', snippet: 'Task 1: Schema' }+ },+ { kind: 'verdict', verdict: 'request-changes' }+ ]+ });+ assert.strictEqual(post.statusCode, 200);+ await exited;+ const feedback = JSON.parse(awaitStdout.trim());+ assert.strictEqual(feedback.status, 'feedback');+ assert.strictEqual(feedback.items.length, 2);+ assert.strictEqual(feedback.items[0].kind, 'annotation');+ assert.ok(feedback.items[0].anchor.snippet.includes('Task 1'));+ assert.strictEqual(feedback.items[1].verdict, 'request-changes');+ assert.ok(feedback.next_step.includes('--reply'));+ });++ await test('agent edits the plan and replies; reply reaches the canvas chat', async () => {+ fs.appendFileSync(plan, '\n### Task 2: Webhook channel\n- **Action**: add webhook delivery\n');+ const result = cli(env, ['await', plan, '--reply', 'Added webhook delivery as Task 2.', '--timeout-ms', '400']);+ assert.strictEqual(result.status, 0, result.stderr);+ assert.strictEqual(result.parsed.status, 'waiting');+ // The chrome bootstraps its chat from the canvas page.+ const chrome = await request(port, 'GET', `/canvas/${key}`);+ assert.ok(chrome.body.includes('Added webhook delivery as Task 2.'));+ const doc = await request(port, 'GET', `/artifact/${key}/`);+ assert.ok(doc.body.includes('Webhook channel'));+ });++ await test('user approves; the verdict arrives as plan confirmation', async () => {+ awaitChild = spawn('node', [CLI, 'await', plan], { env: { ...process.env, ...env } });+ awaitStdout = '';+ awaitChild.stdout.on('data', chunk => {+ awaitStdout += chunk;+ });+ const exited = awaitExit();+ await request(port, 'POST', `/api/session/${key}/feedback`, {+ items: [{ kind: 'verdict', verdict: 'approve' }]+ });+ await exited;+ const feedback = JSON.parse(awaitStdout.trim());+ assert.strictEqual(feedback.items[0].verdict, 'approve');+ });++ await test('user ends the session; plain reopen is refused, --reopen works', async () => {+ await request(port, 'POST', `/api/session/${key}/end`);+ const refused = cli(env, ['open', plan, '--no-open']);+ assert.strictEqual(refused.parsed.status, 'user-ended');+ assert.ok(refused.parsed.next_step.includes('Do not reopen'));+ const forced = cli(env, ['open', plan, '--no-open', '--reopen']);+ assert.strictEqual(forced.parsed.status, 'open');+ });++ await test('await on a user-ended session reports ended with guidance', async () => {+ await request(port, 'POST', `/api/session/${key}/end`);+ const result = cli(env, ['await', plan, '--timeout-ms', '400']);+ assert.strictEqual(result.parsed.status, 'ended');+ assert.strictEqual(result.parsed.endedBy, 'user');+ assert.ok(result.parsed.next_step.includes('Stop polling'));+ });++ await test('agent end + status + stop shut everything down', async () => {+ cli(env, ['open', plan, '--no-open', '--reopen']);+ const ended = cli(env, ['end', plan]);+ assert.strictEqual(ended.parsed.endedBy, 'agent');+ const status = cli(env, []);+ assert.ok(String(status.parsed.server).includes(`127.0.0.1:${port}`));+ const stop = cli(env, ['stop']);+ assert.strictEqual(stop.parsed.status, 'stopping');+ // Server actually exits: health checks fail shortly after.+ let gone = false;+ for (let i = 0; i < 30 && !gone; i++) {+ await new Promise(resolve => setTimeout(resolve, 100));+ gone = await request(port, 'GET', '/health').then(() => false).catch(() => true);+ }+ assert.ok(gone, 'server should stop listening after stop');+ const after = cli(env, []);+ assert.strictEqual(after.parsed.server, 'not running');+ });+ } finally {+ // Belt and braces: never leave a server running even if a test failed.+ cli(env, ['stop']);+ fs.rmSync(tmp, { recursive: true, force: true });+ }++ const passed = results.filter(Boolean).length;+ const failed = results.length - passed;+ console.log('\n' + '='.repeat(40));+ console.log(`Passed: ${passed}`);+ console.log(`Failed: ${failed}`);+ console.log('='.repeat(40));+ process.exit(failed > 0 ? 1 : 0);+}++main().catch(err => {+ console.error(err);+ console.log('Passed: 0');+ console.log('Failed: 1');+ process.exit(1);+});diff --git a/tests/lib/loopback-guard.test.js b/tests/lib/loopback-guard.test.jsnew file mode 100644index 000000000..61b01dd56--- /dev/null+++ b/tests/lib/loopback-guard.test.js@@ -0,0 +1,122 @@+/**+ * Tests for scripts/lib/loopback-guard.js+ *+ * Run with: node tests/lib/loopback-guard.test.js+ */++const assert = require('assert');++const {+ LOOPBACK_HOSTNAMES,+ buildAllowedHostnames,+ isAllowedHostHeader,+ isAllowedOrigin,+ parseHostHeader+} = require('../../scripts/lib/loopback-guard');++function test(name, fn) {+ try {+ fn();+ console.log(` ✓ ${name}`);+ return true;+ } catch (err) {+ console.log(` ✗ ${name}`);+ console.log(` Error: ${err.message}`);+ return false;+ }+}++function runTests() {+ console.log('\n=== Testing loopback-guard.js ===\n');++ let passed = 0;+ let failed = 0;++ console.log('parseHostHeader:');++ if (test('strips port from hostname', () => {+ assert.strictEqual(parseHostHeader('127.0.0.1:4517'), '127.0.0.1');+ assert.strictEqual(parseHostHeader('localhost:80'), 'localhost');+ })) passed++; else failed++;++ if (test('handles bare hostnames', () => {+ assert.strictEqual(parseHostHeader('localhost'), 'localhost');+ })) passed++; else failed++;++ if (test('lowercases hostnames', () => {+ assert.strictEqual(parseHostHeader('LocalHost:3000'), 'localhost');+ })) passed++; else failed++;++ if (test('keeps bracketed IPv6 hosts intact', () => {+ assert.strictEqual(parseHostHeader('[::1]:4517'), '[::1]');+ })) passed++; else failed++;++ if (test('returns null for missing or malformed values', () => {+ assert.strictEqual(parseHostHeader(null), null);+ assert.strictEqual(parseHostHeader(undefined), null);+ assert.strictEqual(parseHostHeader(''), null);+ assert.strictEqual(parseHostHeader(' '), null);+ assert.strictEqual(parseHostHeader(42), null);+ assert.strictEqual(parseHostHeader('bad:host:extra'), null);+ })) passed++; else failed++;++ console.log('\nbuildAllowedHostnames:');++ if (test('always includes loopback names', () => {+ const set = buildAllowedHostnames(null);+ for (const name of LOOPBACK_HOSTNAMES) assert.ok(set.has(name));+ })) passed++; else failed++;++ if (test('adds the configured host lowercased', () => {+ const set = buildAllowedHostnames('MyBox.Local');+ assert.ok(set.has('mybox.local'));+ })) passed++; else failed++;++ console.log('\nisAllowedHostHeader:');++ const allowed = buildAllowedHostnames('127.0.0.1');++ if (test('accepts loopback host headers', () => {+ assert.strictEqual(isAllowedHostHeader('127.0.0.1:4517', allowed), true);+ assert.strictEqual(isAllowedHostHeader('localhost:4517', allowed), true);+ assert.strictEqual(isAllowedHostHeader('[::1]:4517', allowed), true);+ })) passed++; else failed++;++ if (test('rejects DNS-rebinding style hostnames', () => {+ assert.strictEqual(isAllowedHostHeader('evil.example.com', allowed), false);+ assert.strictEqual(isAllowedHostHeader('127.0.0.1.evil.example.com', allowed), false);+ })) passed++; else failed++;++ if (test('rejects missing host header', () => {+ assert.strictEqual(isAllowedHostHeader(undefined, allowed), false);+ })) passed++; else failed++;++ console.log('\nisAllowedOrigin:');++ if (test('absent origin is allowed (same-origin nav, CLI)', () => {+ assert.strictEqual(isAllowedOrigin(undefined, allowed), true);+ assert.strictEqual(isAllowedOrigin(null, allowed), true);+ })) passed++; else failed++;++ if (test('loopback origins are allowed', () => {+ assert.strictEqual(isAllowedOrigin('http://127.0.0.1:4517', allowed), true);+ assert.strictEqual(isAllowedOrigin('http://localhost:4517', allowed), true);+ })) passed++; else failed++;++ if (test('cross-site origins are rejected', () => {+ assert.strictEqual(isAllowedOrigin('https://evil.example.com', allowed), false);+ })) passed++; else failed++;++ if (test('malformed origins are rejected', () => {+ assert.strictEqual(isAllowedOrigin('not a url', allowed), false);+ })) passed++; else failed++;++ console.log('\n' + '='.repeat(40));+ console.log(`Passed: ${passed}`);+ console.log(`Failed: ${failed}`);+ console.log('='.repeat(40));++ process.exit(failed > 0 ? 1 : 0);+}++runTests();diff --git a/tests/lib/plan-canvas-markdown.test.js b/tests/lib/plan-canvas-markdown.test.jsnew file mode 100644index 000000000..5b401ff42--- /dev/null+++ b/tests/lib/plan-canvas-markdown.test.js@@ -0,0 +1,409 @@+/**+ * Tests for scripts/lib/plan-canvas/markdown.js+ *+ * Run with: node tests/lib/plan-canvas-markdown.test.js+ */++const assert = require('assert');++// Import the module+const { renderMarkdown, escapeHtml, slugify } = require('../../scripts/lib/plan-canvas/markdown');++// Test helper+function test(name, fn) {+ try {+ fn();+ console.log(` ✓ ${name}`);+ return true;+ } catch (err) {+ console.log(` ✗ ${name}`);+ console.log(` Error: ${err.message}`);+ return false;+ }+}++// Test suite+function runTests() {+ console.log('\n=== Testing plan-canvas/markdown.js ===\n');++ let passed = 0;+ let failed = 0;++ // escapeHtml tests+ console.log('escapeHtml:');++ if (test('escapes & < > " \'', () => {+ assert.strictEqual(+ escapeHtml('<a href="x" & \'y\'>'),+ '<a href="x" & 'y'>'+ );+ })) passed++; else failed++;++ if (test('leaves safe text unchanged', () => {+ assert.strictEqual(escapeHtml('plain text 123'), 'plain text 123');+ })) passed++; else failed++;++ if (test('handles null/undefined as empty string', () => {+ assert.strictEqual(escapeHtml(null), '');+ assert.strictEqual(escapeHtml(undefined), '');+ })) passed++; else failed++;++ // slugify tests+ console.log('\nslugify:');++ if (test('lowercases and hyphenates spaces', () => {+ assert.strictEqual(slugify('Plan Overview'), 'plan-overview');+ })) passed++; else failed++;++ if (test('strips punctuation', () => {+ assert.strictEqual(slugify('Files to Change: Phase 1!'), 'files-to-change-phase-1');+ })) passed++; else failed++;++ if (test('collapses repeated separators and trims', () => {+ assert.strictEqual(slugify(' A B--C '), 'a-b-c');+ })) passed++; else failed++;++ if (test('returns empty string for symbol-only input', () => {+ assert.strictEqual(slugify('***'), '');+ })) passed++; else failed++;++ // Heading tests+ console.log('\nHeadings:');++ for (let level = 1; level <= 6; level++) {+ if (test(`renders h${level} with slug id`, () => {+ const md = `${'#'.repeat(level)} Title ${level}`;+ assert.strictEqual(+ renderMarkdown(md),+ `<h${level} id="title-${level}">Title ${level}</h${level}>`+ );+ })) passed++; else failed++;+ }++ if (test('heading supports inline formatting, slug ignores markers', () => {+ assert.strictEqual(+ renderMarkdown('## Rollout **Plan**'),+ '<h2 id="rollout-plan">Rollout <strong>Plan</strong></h2>'+ );+ })) passed++; else failed++;++ // Paragraph and inline tests+ console.log('\nParagraphs and Inline:');++ if (test('splits paragraphs on blank lines', () => {+ assert.strictEqual(+ renderMarkdown('first para\n\nsecond para'),+ '<p>first para</p>\n<p>second para</p>'+ );+ })) passed++; else failed++;++ if (test('joins consecutive lines into one paragraph', () => {+ assert.strictEqual(renderMarkdown('line a\nline b'), '<p>line a\nline b</p>');+ })) passed++; else failed++;++ if (test('renders bold, italic, strikethrough, inline code', () => {+ const out = renderMarkdown('has **bold**, *ital*, _emph_, ~~gone~~, and `a < b`.');+ assert.strictEqual(+ out,+ '<p>has <strong>bold</strong>, <em>ital</em>, <em>emph</em>, <del>gone</del>, and <code>a < b</code>.</p>'+ );+ })) passed++; else failed++;++ if (test('does not italicize snake_case identifiers', () => {+ const out = renderMarkdown('use snake_case_name here');+ assert.ok(!out.includes('<em>'), `No <em> expected, got ${out}`);+ })) passed++; else failed++;++ if (test('inline code contents are not parsed further', () => {+ assert.strictEqual(renderMarkdown('`**x**`'), '<p><code>**x**</code></p>');+ })) passed++; else failed++;++ // List tests+ console.log('\nLists:');++ if (test('renders nested unordered list (2 levels)', () => {+ const out = renderMarkdown('- top one\n - child one\n - child two\n- top two');+ assert.ok(out.startsWith('<ul>'), 'Should start with <ul>');+ assert.ok(out.includes('<li>top one\n<ul>'), 'Nested list should sit inside first <li>');+ assert.ok(out.includes('<li>child one</li>'), 'Should contain first child');+ assert.ok(out.includes('</ul>\n</li>\n<li>top two</li>'), 'Second top item follows nested list');+ })) passed++; else failed++;++ if (test('renders ordered list', () => {+ assert.strictEqual(+ renderMarkdown('1. first\n2. second'),+ '<ol>\n<li>first</li>\n<li>second</li>\n</ol>'+ );+ })) passed++; else failed++;++ if (test('renders unordered list nested inside ordered list', () => {+ const out = renderMarkdown('1. step one\n - detail\n2. step two');+ assert.ok(out.startsWith('<ol>'), 'Outer list should be <ol>');+ assert.ok(out.includes('<li>step one\n<ul>\n<li>detail</li>\n</ul>\n</li>'), `Nested <ul> expected, got ${out}`);+ })) passed++; else failed++;++ if (test('renders task list items (checked and unchecked)', () => {+ const out = renderMarkdown('- [ ] draft plan\n- [x] review plan');+ assert.ok(out.includes('<li class="task"><input type="checkbox" disabled> draft plan</li>'), `Unchecked task expected, got ${out}`);+ assert.ok(out.includes('<li class="task"><input type="checkbox" disabled checked> review plan</li>'), `Checked task expected, got ${out}`);+ })) passed++; else failed++;++ if (test('asterisk bullets work like hyphen bullets', () => {+ assert.strictEqual(renderMarkdown('* a\n* b'), '<ul>\n<li>a</li>\n<li>b</li>\n</ul>');+ })) passed++; else failed++;++ // Table tests+ console.log('\nTables:');++ const planTable = [+ '| File | Action | Why |',+ '|:-----|:------:|----:|',+ '| `scripts/lib/plan-canvas/markdown.js` | Create | GFM renderer |',+ '| `tests/lib/plan-canvas-markdown.test.js` | Create | **Required** coverage |'+ ].join('\n');++ if (test('renders plan-artifact table with thead/tbody', () => {+ const out = renderMarkdown(planTable);+ assert.ok(out.startsWith('<table>'), 'Should start with <table>');+ assert.ok(out.includes('<thead>'), 'Should contain <thead>');+ assert.ok(out.includes('<tbody>'), 'Should contain <tbody>');+ })) passed++; else failed++;++ if (test('applies alignment styles to header and body cells', () => {+ const out = renderMarkdown(planTable);+ assert.ok(out.includes('<th style="text-align:left">File</th>'), 'Left-aligned header');+ assert.ok(out.includes('<th style="text-align:center">Action</th>'), 'Center-aligned header');+ assert.ok(out.includes('<th style="text-align:right">Why</th>'), 'Right-aligned header');+ assert.ok(out.includes('<td style="text-align:center">Create</td>'), 'Center-aligned cell');+ })) passed++; else failed++;++ if (test('renders inline code and bold inside table cells', () => {+ const out = renderMarkdown(planTable);+ assert.ok(out.includes('<code>scripts/lib/plan-canvas/markdown.js</code>'), 'Code span in cell');+ assert.ok(out.includes('<strong>Required</strong> coverage'), 'Bold in cell');+ })) passed++; else failed++;++ if (test('omits style attribute when column has no alignment', () => {+ const out = renderMarkdown('| A | B |\n|---|---|\n| 1 | 2 |');+ assert.ok(out.includes('<th>A</th>'), 'Header without style');+ assert.ok(out.includes('<td>1</td>'), 'Cell without style');+ assert.ok(!out.includes('style='), 'No style attributes at all');+ })) passed++; else failed++;++ // Code fence tests+ console.log('\nFenced Code Blocks:');++ if (test('renders fence with language class and escaped content', () => {+ assert.strictEqual(+ renderMarkdown('```js\nconst x = 1 < 2;\n```'),+ '<pre><code class="language-js">const x = 1 < 2;</code></pre>'+ );+ })) passed++; else failed++;++ if (test('escapes <script> inside code blocks', () => {+ const out = renderMarkdown('```html\n<script>alert(1)</script>\n```');+ assert.ok(!out.includes('<script>'), 'Raw script tag must not survive');+ assert.ok(out.includes('<script>alert(1)</script>'), 'Escaped script expected');+ })) passed++; else failed++;++ if (test('does not parse inline markdown inside code blocks', () => {+ const out = renderMarkdown('```\n**not bold**\n```');+ assert.ok(out.includes('**not bold**'), 'Literal asterisks expected');+ assert.ok(!out.includes('<strong>'), 'No strong tag expected');+ })) passed++; else failed++;++ if (test('sanitizes language attribute to [a-z0-9-]', () => {+ const out = renderMarkdown('```C++ extra info\ncode\n```');+ assert.ok(out.includes('class="language-c"'), `Sanitized lang expected, got ${out}`);+ })) passed++; else failed++;++ if (test('unclosed fence consumes to end of input', () => {+ const out = renderMarkdown('```\nno closing fence');+ assert.strictEqual(out, '<pre><code>no closing fence</code></pre>');+ })) passed++; else failed++;++ // Blockquote and horizontal rule tests+ console.log('\nBlockquotes and Rules:');++ if (test('renders blockquote with inline formatting', () => {+ assert.strictEqual(+ renderMarkdown('> planning note with **bold**'),+ '<blockquote>\n<p>planning note with <strong>bold</strong></p>\n</blockquote>'+ );+ })) passed++; else failed++;++ if (test('renders nested blockquotes', () => {+ const out = renderMarkdown('> outer\n> > inner');+ const opens = out.split('<blockquote>').length - 1;+ assert.strictEqual(opens, 2, `Expected 2 blockquotes, got ${opens}`);+ assert.ok(out.includes('<p>outer</p>'), 'Outer text expected');+ assert.ok(out.includes('<p>inner</p>'), 'Inner text expected');+ })) passed++; else failed++;++ if (test('renders --- and *** as horizontal rules', () => {+ assert.strictEqual(+ renderMarkdown('above\n\n---\n\nbelow'),+ '<p>above</p>\n<hr>\n<p>below</p>'+ );+ assert.strictEqual(renderMarkdown('***'), '<hr>');+ })) passed++; else failed++;++ // XSS tests+ console.log('\nXSS Hardening:');++ if (test('escapes raw <script> in a paragraph', () => {+ const out = renderMarkdown('<script>alert(1)</script>');+ assert.strictEqual(out, '<p><script>alert(1)</script></p>');+ })) passed++; else failed++;++ if (test('javascript: link renders as plain label text', () => {+ const out = renderMarkdown('[x](javascript:alert(1))');+ assert.ok(!out.includes('<a'), 'No anchor expected');+ assert.ok(!out.includes('javascript'), 'Payload URL must be dropped');+ assert.ok(out.includes('x'), 'Label text should remain');+ })) passed++; else failed++;++ if (test('mixed-case JaVaScRiPt: link is blocked', () => {+ const out = renderMarkdown('[x](JaVaScRiPt:alert(1))');+ assert.ok(!out.includes('<a'), 'No anchor expected');+ assert.ok(!/javascript/i.test(out), 'Payload URL must be dropped');+ })) passed++; else failed++;++ if (test('whitespace-obfuscated scheme is blocked', () => {+ const out = renderMarkdown('[x](java\tscript:alert(1))');+ assert.ok(!out.includes('<a'), 'No anchor expected');+ assert.ok(!out.includes('script:'), 'Payload URL must be dropped');+ })) passed++; else failed++;++ if (test('data: and vbscript: links are blocked', () => {+ assert.strictEqual(renderMarkdown('[x](data:text/html;base64,AAAA)'), '<p>x</p>');+ const vb = renderMarkdown('[x](vbscript:msgbox(1))');+ assert.ok(!vb.includes('<a'), 'No anchor expected');+ assert.ok(!vb.includes('vbscript'), 'Payload URL must be dropped');+ })) passed++; else failed++;++ if (test('javascript: image renders as plain alt text', () => {+ const out = renderMarkdown(')');+ assert.ok(!out.includes('<img'), 'No img expected');+ assert.ok(!out.includes('javascript'), 'Payload URL must be dropped');+ })) passed++; else failed++;++ if (test('raw <img onerror> HTML is escaped', () => {+ const out = renderMarkdown('<img src=x onerror=alert(1)>');+ assert.strictEqual(out, '<p><img src=x onerror=alert(1)></p>');+ })) passed++; else failed++;++ if (test('event-handler injection via link text is escaped', () => {+ const out = renderMarkdown('["><img src=x onerror=alert(1)>](https://evil.example)');+ assert.ok(!out.includes('<img'), 'No raw img expected');+ assert.ok(out.includes('"><img src=x onerror=alert(1)>'), `Escaped label expected, got ${out}`);+ })) passed++; else failed++;++ if (test('image alt attribute value is escaped', () => {+ assert.strictEqual(+ renderMarkdown(''),+ '<p><img src="x.png" alt="a"b"></p>'+ );+ })) passed++; else failed++;++ // Link protocol tests+ console.log('\nLink Protocols:');++ if (test('https link gets target=_blank and rel=noopener', () => {+ assert.strictEqual(+ renderMarkdown('[docs](https://example.com)'),+ '<p><a href="https://example.com" target="_blank" rel="noopener">docs</a></p>'+ );+ })) passed++; else failed++;++ if (test('#anchor link has no target/rel', () => {+ assert.strictEqual(+ renderMarkdown('[phase](#phase-1)'),+ '<p><a href="#phase-1">phase</a></p>'+ );+ })) passed++; else failed++;++ if (test('relative link has no target/rel', () => {+ assert.strictEqual(+ renderMarkdown('[utils](./scripts/lib/utils.js)'),+ '<p><a href="./scripts/lib/utils.js">utils</a></p>'+ );+ })) passed++; else failed++;++ if (test('mailto link allowed without target/rel', () => {+ assert.strictEqual(+ renderMarkdown('[mail](mailto:[email protected])'),+ '<p><a href="mailto:[email protected]">mail</a></p>'+ );+ })) passed++; else failed++;++ if (test('relative image src allowed', () => {+ assert.strictEqual(+ renderMarkdown(''),+ '<p><img src="assets/plan.png" alt="diagram"></p>'+ );+ })) passed++; else failed++;++ if (test('inline formatting works inside link labels', () => {+ const out = renderMarkdown('[`code` and **bold** docs](https://example.com)');+ assert.ok(out.includes('<code>code</code> and <strong>bold</strong> docs</a>'), `Formatted label expected, got ${out}`);+ })) passed++; else failed++;++ // Edge case tests+ console.log('\nEdge Cases:');++ if (test('empty input returns empty string', () => {+ assert.strictEqual(renderMarkdown(''), '');+ assert.strictEqual(renderMarkdown(null), '');+ assert.strictEqual(renderMarkdown(undefined), '');+ })) passed++; else failed++;++ if (test('input without trailing newline works', () => {+ assert.strictEqual(renderMarkdown('final line'), '<p>final line</p>');+ })) passed++; else failed++;++ if (test('CRLF line endings are normalized', () => {+ assert.strictEqual(renderMarkdown('one\r\n\r\ntwo'), '<p>one</p>\n<p>two</p>');+ })) passed++; else failed++;++ if (test('whitespace-only input returns empty string', () => {+ assert.strictEqual(renderMarkdown(' \n\n '), '');+ })) passed++; else failed++;++ console.log('\nMermaid diagrams:');++ if (test('```mermaid becomes <pre class="mermaid">, not a code block', () => {+ const html = renderMarkdown('```mermaid\nflowchart LR\n A --> B\n```');+ assert.ok(html.includes('<pre class="mermaid">'), 'expected mermaid container');+ assert.ok(!html.includes('language-mermaid'), 'should not render as a code block');+ })) passed++; else failed++;++ if (test('mermaid arrows are entity-escaped so textContent decodes them', () => {+ // The browser decodes > back to > in textContent, so the renderer+ // still receives valid `-->` while HTML injection is prevented.+ const html = renderMarkdown('```mermaid\nA --> B\n```');+ assert.ok(html.includes('A --> B'));+ })) passed++; else failed++;++ if (test('script tags inside a mermaid block are inert', () => {+ const html = renderMarkdown('```mermaid\n<script>alert(1)</script>\n```');+ assert.ok(!html.includes('<script>alert(1)</script>'));+ assert.ok(html.includes('<script>'));+ })) passed++; else failed++;++ if (test('a </pre> in the source cannot break out of the container', () => {+ const html = renderMarkdown('```mermaid\nA</pre><img src=x onerror=1>\n```');+ assert.ok(!html.includes('</pre><img'));+ assert.ok(html.includes('</pre><img'));+ })) passed++; else failed++;++ // Summary+ console.log('\n=== Test Results ===');+ console.log(`Passed: ${passed}`);+ console.log(`Failed: ${failed}`);+ console.log(`Total: ${passed + failed}\n`);++ process.exit(failed > 0 ? 1 : 0);+}++runTests();diff --git a/tests/lib/plan-canvas-sessions.test.js b/tests/lib/plan-canvas-sessions.test.jsnew file mode 100644index 000000000..ea712a2fa--- /dev/null+++ b/tests/lib/plan-canvas-sessions.test.js@@ -0,0 +1,227 @@+/**+ * Tests for scripts/lib/plan-canvas/sessions.js+ *+ * Run with: node tests/lib/plan-canvas-sessions.test.js+ */++const assert = require('assert');+const fs = require('fs');+const os = require('os');+const path = require('path');++const {+ canonicalizeArtifactPath,+ createSessionStore,+ normalizeFeedbackItem,+ sessionKeyFor+} = require('../../scripts/lib/plan-canvas/sessions');++function test(name, fn) {+ try {+ fn();+ console.log(` ✓ ${name}`);+ return true;+ } catch (err) {+ console.log(` ✗ ${name}`);+ console.log(` Error: ${err.message}`);+ return false;+ }+}++function makeFixture() {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-canvas-test-'));+ const artifact = path.join(dir, 'demo.plan.md');+ fs.writeFileSync(artifact, '# Plan\n');+ const store = createSessionStore({ stateDir: path.join(dir, 'state') });+ return { dir, artifact, store };+}++function runTests() {+ console.log('\n=== Testing plan-canvas sessions.js ===\n');++ let passed = 0;+ let failed = 0;+ const fixtures = [];++ console.log('Keys and normalization:');++ if (test('sessionKeyFor is a stable 12-char hex key', () => {+ const key = sessionKeyFor('/tmp/x.md');+ assert.match(key, /^[a-f0-9]{12}$/);+ assert.strictEqual(key, sessionKeyFor('/tmp/x.md'));+ assert.notStrictEqual(key, sessionKeyFor('/tmp/y.md'));+ })) passed++; else failed++;++ if (test('canonicalizeArtifactPath resolves relative paths', () => {+ const abs = canonicalizeArtifactPath('some-file.md');+ assert.ok(path.isAbsolute(abs));+ })) passed++; else failed++;++ if (test('normalizeFeedbackItem accepts chat, annotation, verdict', () => {+ assert.strictEqual(normalizeFeedbackItem({ kind: 'chat', text: 'hi' }, 1).kind, 'chat');+ const ann = normalizeFeedbackItem(+ { kind: 'annotation', text: 'fix', anchor: { selector: 'h2', tag: 'h2', snippet: 'Phase 2' } },+ 2+ );+ assert.strictEqual(ann.anchor.selector, 'h2');+ const verdict = normalizeFeedbackItem({ kind: 'verdict', verdict: 'approve' }, 3);+ assert.strictEqual(verdict.verdict, 'approve');+ })) passed++; else failed++;++ if (test('normalizeFeedbackItem rejects malformed input', () => {+ assert.strictEqual(normalizeFeedbackItem(null, 1), null);+ assert.strictEqual(normalizeFeedbackItem({ kind: 'nope', text: 'x' }, 1), null);+ assert.strictEqual(normalizeFeedbackItem({ kind: 'chat', text: '' }, 1), null);+ assert.strictEqual(normalizeFeedbackItem({ kind: 'verdict', verdict: 'maybe' }, 1), null);+ assert.strictEqual(normalizeFeedbackItem({ kind: 'annotation', text: 'x' }, 1), null);+ assert.strictEqual(normalizeFeedbackItem({ kind: 'annotation', text: '', anchor: { selector: 'p' } }, 1), null);+ })) passed++; else failed++;++ console.log('\nOpen / reopen semantics:');++ if (test('open creates a session keyed by canonical path', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ const { session, refused } = fx.store.open(fx.artifact);+ assert.strictEqual(refused, false);+ assert.strictEqual(session.status, 'open');+ assert.strictEqual(session.file, canonicalizeArtifactPath(fx.artifact));+ assert.strictEqual(fx.store.findByFile(fx.artifact).key, session.key);+ })) passed++; else failed++;++ if (test('user-ended sessions refuse a plain reopen but allow --reopen', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ const { session } = fx.store.open(fx.artifact);+ fx.store.end(session.key, 'user');+ assert.strictEqual(fx.store.open(fx.artifact).refused, true);+ const forced = fx.store.open(fx.artifact, { reopen: true });+ assert.strictEqual(forced.refused, false);+ assert.strictEqual(forced.session.status, 'open');+ })) passed++; else failed++;++ if (test('agent-ended sessions reopen without a flag', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ const { session } = fx.store.open(fx.artifact);+ fx.store.end(session.key, 'agent');+ assert.strictEqual(fx.store.open(fx.artifact).refused, false);+ })) passed++; else failed++;++ console.log('\nFeedback queue / deliver-and-drain:');++ if (test('queueFeedback filters bad items and mirrors chat', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ const { session } = fx.store.open(fx.artifact);+ const result = fx.store.queueFeedback(session.key, [+ { kind: 'chat', text: 'hello agent' },+ { kind: 'bogus' },+ { kind: 'verdict', verdict: 'approve' }+ ]);+ assert.strictEqual(result.accepted.length, 2);+ assert.strictEqual(result.pending, 2);+ const chat = fx.store.get(session.key).chat;+ assert.strictEqual(chat.length, 2);+ assert.strictEqual(chat[0].role, 'user');+ assert.ok(chat[1].text.includes('Approved the plan'));+ })) passed++; else failed++;++ if (test('takeFeedback drains once, then returns waiting', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ const { session } = fx.store.open(fx.artifact);+ fx.store.queueFeedback(session.key, [{ kind: 'chat', text: 'one' }]);+ const first = fx.store.takeFeedback(session.key);+ assert.strictEqual(first.status, 'feedback');+ assert.strictEqual(first.items.length, 1);+ assert.strictEqual(fx.store.takeFeedback(session.key).status, 'waiting');+ })) passed++; else failed++;++ if (test('takeFeedback reports missing for unknown sessions', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ assert.strictEqual(fx.store.takeFeedback('deadbeef0000').status, 'missing');+ })) passed++; else failed++;++ if (test('send-and-end delivers final batch with attribution', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ const { session } = fx.store.open(fx.artifact);+ fx.store.queueFeedback(session.key, [{ kind: 'chat', text: 'last words' }], { endSession: true });+ const result = fx.store.takeFeedback(session.key);+ assert.strictEqual(result.status, 'feedback');+ assert.strictEqual(result.sessionEnded, true);+ assert.strictEqual(result.endedBy, 'user');+ const after = fx.store.takeFeedback(session.key);+ assert.strictEqual(after.status, 'ended');+ assert.strictEqual(after.endedBy, 'user');+ })) passed++; else failed++;++ if (test('queueFeedback on an ended session is refused', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ const { session } = fx.store.open(fx.artifact);+ fx.store.end(session.key, 'agent');+ assert.strictEqual(fx.store.queueFeedback(session.key, [{ kind: 'chat', text: 'late' }]), null);+ })) passed++; else failed++;++ console.log('\nPersistence:');++ if (test('queued feedback survives a store reload (server restart)', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ const { session } = fx.store.open(fx.artifact);+ fx.store.queueFeedback(session.key, [{ kind: 'chat', text: 'persist me' }]);+ const reloaded = createSessionStore({ stateDir: fx.store.stateDir });+ const result = reloaded.takeFeedback(session.key);+ assert.strictEqual(result.status, 'feedback');+ assert.strictEqual(result.items[0].text, 'persist me');+ })) passed++; else failed++;++ if (test('corrupt state file starts fresh instead of crashing', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ fs.mkdirSync(fx.store.stateDir, { recursive: true });+ fs.writeFileSync(fx.store.stateFile, '{not json');+ const reloaded = createSessionStore({ stateDir: fx.store.stateDir });+ assert.deepStrictEqual(reloaded.list(), []);+ })) passed++; else failed++;++ if (test('addAgentReply appends to the transcript', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ const { session } = fx.store.open(fx.artifact);+ fx.store.addAgentReply(session.key, 'done, take a look');+ const chat = fx.store.get(session.key).chat;+ assert.strictEqual(chat[chat.length - 1].role, 'agent');+ })) passed++; else failed++;++ if (test('list and hasOpenSessions reflect state', () => {+ const fx = makeFixture();+ fixtures.push(fx);+ assert.strictEqual(fx.store.hasOpenSessions(), false);+ const { session } = fx.store.open(fx.artifact);+ assert.strictEqual(fx.store.hasOpenSessions(), true);+ assert.strictEqual(fx.store.list().length, 1);+ fx.store.end(session.key, 'user');+ assert.strictEqual(fx.store.hasOpenSessions(), false);+ })) passed++; else failed++;++ for (const fx of fixtures) {+ try {+ fs.rmSync(fx.dir, { recursive: true, force: true });+ } catch {+ // best-effort cleanup+ }+ }++ console.log('\n' + '='.repeat(40));+ console.log(`Passed: ${passed}`);+ console.log(`Failed: ${failed}`);+ console.log('='.repeat(40));++ process.exit(failed > 0 ? 1 : 0);+}++runTests();diff --git a/tests/scripts/npm-publish-surface.test.js b/tests/scripts/npm-publish-surface.test.jsindex 8e33635db..47dc5c08a 100644--- a/tests/scripts/npm-publish-surface.test.js+++ b/tests/scripts/npm-publish-surface.test.js@@ -58,6 +58,7 @@ function buildExpectedPublishPaths(repoRoot) {"scripts/list-installed.js","scripts/loop-status.js","scripts/observability-readiness.js",+ "scripts/plan-canvas.js","scripts/operator-readiness-dashboard.js","scripts/platform-audit.js","scripts/preview-pack-smoke.js",diff --git a/tests/scripts/plan-canvas.test.js b/tests/scripts/plan-canvas.test.jsnew file mode 100644index 000000000..ebe9107f9--- /dev/null+++ b/tests/scripts/plan-canvas.test.js@@ -0,0 +1,377 @@+/**+ * Integration tests for the Plan Canvas server (scripts/lib/plan-canvas/).+ *+ * Spins up the real HTTP server in-process and drives it exactly like the+ * browser chrome (fetch + SSE) and the agent CLI (long-poll) do.+ *+ * Run with: node tests/scripts/plan-canvas.test.js+ */++const assert = require('assert');+const fs = require('fs');+const http = require('http');+const os = require('os');+const path = require('path');++const { createSessionStore } = require('../../scripts/lib/plan-canvas/sessions');+const { createPlanCanvasServer } = require('../../scripts/lib/plan-canvas/server');++async function test(name, fn) {+ try {+ await fn();+ console.log(` ✓ ${name}`);+ return true;+ } catch (err) {+ console.log(` ✗ ${name}`);+ console.log(` Error: ${err.stack || err.message}`);+ return false;+ }+}++function request(port, method, requestPath, { body = null, headers = {} } = {}) {+ return new Promise((resolve, reject) => {+ const payload = body === null ? null : JSON.stringify(body);+ const req = http.request(+ {+ host: '127.0.0.1',+ port,+ method,+ path: requestPath,+ agent: false,+ headers: payload+ ? { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload), ...headers }+ : headers+ },+ res => {+ let data = '';+ res.on('data', chunk => {+ data += chunk;+ });+ res.on('end', () => resolve({ statusCode: res.statusCode, headers: res.headers, body: data }));+ }+ );+ req.on('error', reject);+ if (payload) req.write(payload);+ req.end();+ });+}++function jsonBody(res) {+ return JSON.parse(res.body.trim());+}++// Open an SSE stream and collect parsed events into `received`.+function openSse(port, key) {+ const received = [];+ let close = () => {};+ const ready = new Promise((resolve, reject) => {+ const req = http.get(+ { host: '127.0.0.1', port, path: `/events/${key}`, agent: false },+ res => {+ let buffer = '';+ res.on('data', chunk => {+ buffer += chunk;+ let idx;+ while ((idx = buffer.indexOf('\n\n')) >= 0) {+ const frame = buffer.slice(0, idx);+ buffer = buffer.slice(idx + 2);+ const eventMatch = frame.match(/^event: (.+)$/m);+ const dataMatch = frame.match(/^data: (.+)$/m);+ if (eventMatch && dataMatch) {+ received.push({ event: eventMatch[1], data: JSON.parse(dataMatch[1]) });+ }+ }+ });+ resolve();+ }+ );+ req.on('error', reject);+ close = () => req.destroy();+ });+ return { received, ready, close: () => close() };+}++function waitFor(predicate, { timeoutMs = 3000, intervalMs = 20 } = {}) {+ return new Promise((resolve, reject) => {+ const startedAt = Date.now();+ const timer = setInterval(() => {+ if (predicate()) {+ clearInterval(timer);+ resolve();+ } else if (Date.now() - startedAt > timeoutMs) {+ clearInterval(timer);+ reject(new Error('waitFor timed out'));+ }+ }, intervalMs);+ });+}++async function main() {+ console.log('\n=== Testing plan-canvas server ===\n');++ let passed = 0;+ let failed = 0;++ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-canvas-server-'));+ const artifact = path.join(tmp, 'demo.plan.md');+ fs.writeFileSync(artifact, '# Plan: Demo\n\n## Files to Change\n\n| File | Action |\n|---|---|\n| `a.js` | UPDATE |\n');+ const htmlArtifact = path.join(tmp, 'report.html');+ fs.writeFileSync(htmlArtifact, '<!DOCTYPE html><html><body><h1>Report</h1></body></html>');+ fs.writeFileSync(path.join(tmp, 'style.css'), 'body { color: red }');+ fs.writeFileSync(path.join(os.tmpdir(), 'plan-canvas-outside.txt'), 'secret');++ const store = createSessionStore({ stateDir: path.join(tmp, 'state') });+ let idleFired = false;+ const canvas = createPlanCanvasServer({+ store,+ version: '9.9.9-test',+ heartbeatMs: 25,+ idleTimeoutMs: 0,+ onIdleShutdown: () => {+ idleFired = true;+ }+ });+ const { port } = await canvas.listen(0);++ let key = null;+ let htmlKey = null;++ if (await test('GET /health identifies the app and version', async () => {+ const res = await request(port, 'GET', '/health');+ assert.deepStrictEqual(jsonBody(res), { ok: true, app: 'ecc-plan-canvas', version: '9.9.9-test' });+ })) passed++; else failed++;++ if (await test('requests with a non-loopback Host header are rejected', async () => {+ const res = await request(port, 'GET', '/health', { headers: { host: 'evil.example.com' } });+ assert.strictEqual(res.statusCode, 403);+ })) passed++; else failed++;++ if (await test('requests with a cross-site Origin are rejected', async () => {+ const res = await request(port, 'POST', '/shutdown', { headers: { origin: 'https://evil.example.com' } });+ assert.strictEqual(res.statusCode, 403);+ })) passed++; else failed++;++ if (await test('POST /api/sessions opens a session for an existing artifact', async () => {+ const res = await request(port, 'POST', '/api/sessions', { body: { file: artifact } });+ assert.strictEqual(res.statusCode, 200);+ const body = jsonBody(res);+ assert.strictEqual(body.status, 'open');+ assert.match(body.key, /^[a-f0-9]{12}$/);+ key = body.key;+ })) passed++; else failed++;++ if (await test('POST /api/sessions 404s for a missing artifact', async () => {+ const res = await request(port, 'POST', '/api/sessions', { body: { file: path.join(tmp, 'nope.md') } });+ assert.strictEqual(res.statusCode, 404);+ })) passed++; else failed++;++ if (await test('GET /canvas/:key serves the ECC chrome with CSP', async () => {+ const res = await request(port, 'GET', `/canvas/${key}`);+ assert.strictEqual(res.statusCode, 200);+ assert.ok(res.headers['content-security-policy'].includes("default-src 'self'"));+ assert.ok(res.body.includes('Plan Canvas'));+ assert.ok(res.body.includes('pc-session'));+ assert.ok(res.body.includes('Approve plan'));+ assert.ok(res.body.includes('sandbox="allow-scripts allow-forms allow-popups"'));+ })) passed++; else failed++;++ if (await test('markdown artifacts render in the ECC plan template with the SDK', async () => {+ const res = await request(port, 'GET', `/artifact/${key}/`);+ assert.strictEqual(res.statusCode, 200);+ assert.ok(res.body.includes('<h1 id="plan-demo">'));+ assert.ok(res.body.includes('<table>'));+ assert.ok(res.body.includes('<script src="/sdk.js">'));+ assert.strictEqual(res.headers['content-security-policy'], undefined);+ // No diagram in this plan → no Mermaid loader shipped.+ assert.ok(!res.body.includes('mermaid.run'));+ })) passed++; else failed++;++ if (await test('a plan containing ```mermaid serves the themed Mermaid loader', async () => {+ const diagram = path.join(tmp, 'flow.plan.md');+ fs.writeFileSync(diagram, '# Flow\n\n```mermaid\nflowchart LR\n A --> B\n```\n');+ const opened = jsonBody(await request(port, 'POST', '/api/sessions', { body: { file: diagram } }));+ const res = await request(port, 'GET', `/artifact/${opened.key}/`);+ assert.ok(res.body.includes('<pre class="mermaid">'), 'diagram container present');+ assert.ok(res.body.includes('mermaid.run'), 'loader injected');+ assert.ok(res.body.includes("securityLevel: 'strict'"), 'sanitizing config present');+ await request(port, 'POST', '/api/end', { body: { file: diagram } });+ })) passed++; else failed++;++ if (await test('HTML artifacts pass through with the SDK injected before </body>', async () => {+ const open = await request(port, 'POST', '/api/sessions', { body: { file: htmlArtifact } });+ htmlKey = jsonBody(open).key;+ const res = await request(port, 'GET', `/artifact/${htmlKey}/`);+ assert.ok(res.body.includes('<h1>Report</h1>'));+ assert.ok(res.body.includes('<script src="/sdk.js"></script>\n</body>'));+ })) passed++; else failed++;++ if (await test('sibling assets are served, traversal is blocked', async () => {+ const ok = await request(port, 'GET', `/artifact/${key}/style.css`);+ assert.strictEqual(ok.statusCode, 200);+ assert.ok(ok.body.includes('color: red'));+ const escape = await request(port, 'GET', `/artifact/${key}/..%2Fplan-canvas-outside.txt`);+ assert.strictEqual(escape.statusCode, 403);+ })) passed++; else failed++;++ if (await test('static chrome assets are served', async () => {+ for (const asset of ['/canvas.css', '/client.js', '/sdk.js']) {+ const res = await request(port, 'GET', asset);+ assert.strictEqual(res.statusCode, 200, `${asset} should be 200`);+ }+ })) passed++; else failed++;++ if (await test('await with timeoutMs returns waiting when idle', async () => {+ const res = await request(port, 'GET', `/api/await?file=${encodeURIComponent(artifact)}&timeoutMs=50`);+ assert.strictEqual(jsonBody(res).status, 'waiting');+ })) passed++; else failed++;++ if (await test('await returns missing for files without a session', async () => {+ const res = await request(port, 'GET', `/api/await?file=${encodeURIComponent(path.join(tmp, 'other.md'))}`);+ assert.strictEqual(jsonBody(res).status, 'missing');+ })) passed++; else failed++;++ if (await test('browser feedback wakes a blocking await; presence transitions', async () => {+ const sse = openSse(port, key);+ await sse.ready;+ const awaitPromise = request(port, 'GET', `/api/await?file=${encodeURIComponent(artifact)}`);+ await waitFor(() => sse.received.some(e => e.event === 'presence' && e.data.state === 'listening'));++ const post = await request(port, 'POST', `/api/session/${key}/feedback`, {+ body: {+ items: [+ { kind: 'annotation', text: 'tighten this', anchor: { selector: 'h2:nth-of-type(1)', tag: 'h2', snippet: 'Files to Change' } },+ { kind: 'verdict', verdict: 'request-changes' }+ ]+ }+ });+ assert.strictEqual(jsonBody(post).accepted, 2);++ const result = jsonBody(await awaitPromise);+ assert.strictEqual(result.status, 'feedback');+ assert.strictEqual(result.items.length, 2);+ assert.strictEqual(result.items[0].anchor.selector, 'h2:nth-of-type(1)');+ assert.strictEqual(result.items[1].verdict, 'request-changes');++ await waitFor(() => sse.received.some(e => e.event === 'presence' && e.data.state === 'working'));+ await waitFor(() => sse.received.some(e => e.event === 'chat-sync' && e.data.chat.length === 2));+ sse.close();+ })) passed++; else failed++;++ if (await test('long-poll heartbeat whitespace arrives before the payload', async () => {+ const chunks = [];+ const done = new Promise((resolve, reject) => {+ const req = http.get(+ { host: '127.0.0.1', port, path: `/api/await?file=${encodeURIComponent(artifact)}`, agent: false },+ res => {+ res.on('data', chunk => chunks.push(chunk.toString()));+ res.on('end', resolve);+ }+ );+ req.on('error', reject);+ });+ // Heartbeats tick every 25ms in this test server; wait for a few first.+ await waitFor(() => chunks.join('').length >= 3);+ assert.ok(/^\s+$/.test(chunks.join('')), 'expected only whitespace before payload');+ await request(port, 'POST', `/api/session/${key}/feedback`, { body: { items: [{ kind: 'chat', text: 'wake up' }] } });+ await done;+ const full = chunks.join('');+ assert.strictEqual(JSON.parse(full.trim()).status, 'feedback');+ })) passed++; else failed++;++ if (await test('agent reply lands in the chat via SSE chat-sync', async () => {+ const sse = openSse(port, key);+ await sse.ready;+ const res = await request(port, 'POST', `/api/session/${key}/reply`, { body: { text: 'reworked, please re-check' } });+ assert.strictEqual(jsonBody(res).status, 'sent');+ await waitFor(() =>+ sse.received.some(+ e => e.event === 'chat-sync' && e.data.chat.some(m => m.role === 'agent' && m.text.includes('reworked'))+ )+ );+ sse.close();+ })) passed++; else failed++;++ if (await test('live reload: editing the artifact emits an SSE reload event', async () => {+ const sse = openSse(port, key);+ await sse.ready;+ fs.appendFileSync(artifact, '\n## Addendum\n');+ await waitFor(() => sse.received.some(e => e.event === 'reload'), { timeoutMs: 4000 });+ sse.close();+ })) passed++; else failed++;++ if (await test('send-and-end delivers the final batch and ends the session', async () => {+ const awaitPromise = request(port, 'GET', `/api/await?file=${encodeURIComponent(artifact)}`);+ await waitFor(() => canvas.presenceFor(key) === 'listening');+ await request(port, 'POST', `/api/session/${key}/feedback`, {+ body: { items: [{ kind: 'chat', text: 'looks good, wrapping up' }], endSession: true }+ });+ const result = jsonBody(await awaitPromise);+ assert.strictEqual(result.status, 'feedback');+ assert.strictEqual(result.sessionEnded, true);+ assert.strictEqual(result.endedBy, 'user');+ const after = await request(port, 'GET', `/api/await?file=${encodeURIComponent(artifact)}&timeoutMs=0`);+ assert.strictEqual(jsonBody(after).status, 'ended');+ })) passed++; else failed++;++ if (await test('user-ended sessions return 409 on plain reopen, open with reopen:true', async () => {+ const refused = await request(port, 'POST', '/api/sessions', { body: { file: artifact } });+ assert.strictEqual(refused.statusCode, 409);+ assert.strictEqual(jsonBody(refused).status, 'user-ended');+ const forced = await request(port, 'POST', '/api/sessions', { body: { file: artifact, reopen: true } });+ assert.strictEqual(forced.statusCode, 200);+ })) passed++; else failed++;++ if (await test('agent end via POST /api/end allows plain reopen', async () => {+ const res = await request(port, 'POST', '/api/end', { body: { file: artifact } });+ assert.strictEqual(jsonBody(res).endedBy, 'agent');+ const reopened = await request(port, 'POST', '/api/sessions', { body: { file: artifact } });+ assert.strictEqual(reopened.statusCode, 200);+ })) passed++; else failed++;++ if (await test('feedback on an ended session is refused with 409', async () => {+ await request(port, 'POST', `/api/end`, { body: { file: htmlArtifact } });+ const res = await request(port, 'POST', `/api/session/${htmlKey}/feedback`, {+ body: { items: [{ kind: 'chat', text: 'too late' }] }+ });+ assert.strictEqual(res.statusCode, 409);+ })) passed++; else failed++;++ if (await test('GET / lists sessions in the ECC shell', async () => {+ const res = await request(port, 'GET', '/');+ assert.ok(res.body.includes('Plan Canvas sessions'));+ assert.ok(res.body.includes('demo.plan.md'));+ })) passed++; else failed++;++ if (await test('POST /shutdown triggers the shutdown callback', async () => {+ const res = await request(port, 'POST', '/shutdown');+ assert.strictEqual(jsonBody(res).status, 'stopping');+ await waitFor(() => idleFired);+ })) passed++; else failed++;++ if (await test('close() settles a held long-poll instead of hanging', async () => {+ await request(port, 'POST', '/api/sessions', { body: { file: artifact, reopen: true } });+ const held = request(port, 'GET', `/api/await?file=${encodeURIComponent(artifact)}`);+ await waitFor(() => canvas.presenceFor(store.findByFile(artifact).key) === 'listening');+ await canvas.close();+ const result = jsonBody(await held);+ assert.strictEqual(result.status, 'waiting');+ assert.ok(result.note.includes('shutting down'));+ })) passed++; else failed++;++ fs.rmSync(tmp, { recursive: true, force: true });+ fs.rmSync(path.join(os.tmpdir(), 'plan-canvas-outside.txt'), { force: true });++ console.log('\n' + '='.repeat(40));+ console.log(`Passed: ${passed}`);+ console.log(`Failed: ${failed}`);+ console.log('='.repeat(40));++ process.exit(failed > 0 ? 1 : 0);+}++main().catch(err => {+ console.error(err);+ console.log('Passed: 0');+ console.log('Failed: 1');+ process.exit(1);+});diff --git a/yarn.lock b/yarn.lockindex fa21fac6e..dc33ebbac 100644--- a/yarn.lock+++ b/yarn.lock@@ -593,6 +593,7 @@ __metadata:ecc: scripts/ecc.jsecc-control-pane: scripts/control-pane.jsecc-install: scripts/install-apply.js+ ecc-plan-canvas: scripts/plan-canvas.jslanguageName: unknownlinkType: soft