From 0530392821c277b95e5cd65aa9d9fda4248718b2 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sun, 6 Sep 2026 08:54:25 -0700 Subject: [PATCH] v1.81.0.0 feat: Aside is the browser gstack drives first; every browsing skill, the PDF/diagram renderer, and web research; the bundled browser stays the automatic fallback (#2810) * feat(aside): browser-driver contract, cookbook, research and fallback resolvers {{ASIDE_SETUP}} (readiness probe + ten rules for driving the user's real browser), {{ASIDE_COOKBOOK}} (script shapes verified live against Aside CLI 1.26: one flow per aside repl script, CDP console hook before navigation, evidence lines, session-directory artifact handoff, GSTACK_STEP_OK sentinel), {{ASIDE_RESEARCH}} (research through aside exec, WebSearch when Aside is absent, knowledge otherwise) and {{BROWSE_FALLBACK}} (the fifteen-row Aside-step to $B-command table plus the rules that differ, so every browsing skill keeps working on gstack's own headless browser). test/aside-driver.test.ts pins the sentences and asserts every browsing skill carries the Aside block followed by the fallback; test/helpers/aside-available.ts is the shared live-Aside probe. Co-Authored-By: Claude Fable 5.1 * feat(render): Aside-first local-HTML renderer with the bundled browser as fallback lib/aside-render.ts serves the HTML's directory on loopback (Aside refuses file:// URLs), opens it with waitUntil load, prints through CDP Page.printToPDF so tagged output, outlines, header/footer templates and page numbers survive, emulates device metrics for sized screenshots, and writes in-page evaluations to files; when Aside is absent it runs the same spec through the browse daemon (newtab, load, js, pdf, screenshot, closetab) and reports ENGINE=aside|browse. bin/gstack-render.ts is the CLI skill templates call. lib/claude-bin.ts and lib/error-handling.ts become the canonical copies (browse/src re-exports them). Co-Authored-By: Claude Fable 5.1 * refactor(browse): /browse drives Aside first, with the $B reference behind the fallback Contract, cookbook, mode choice (aside repl by default, aside exec for reading), report format, the fallback section, and the full command reference carved on demand. Co-Authored-By: Claude Fable 5.1 * refactor(qa): /qa and /qa-only drive Aside, fall back to $B QA_METHODOLOGY runs every phase as Aside scripts (orient, explore, document, re-test, mobile viewport via CDP emulation, links via HEAD fetch); the authenticate phase is 'you are already signed in'; a 13th rule requires consent before mutating actions on non-local targets; the fallback section translates each step onto $B. The qa E2E tests run on whichever engine is present. Co-Authored-By: Claude Fable 5.1 * refactor(design): design-review, design-consultation, design-shotgun, plan-design-review, design-html drive Aside Design-system extraction is one script printing FONTS/COLORS/HEADINGS/TOUCH_TARGETS/NAV; competitor research confirms the exact URLs before opening them in the real browser and runs on the bundled browser when Aside is absent; design-html's viewport screenshots, sketches and comparison boards render through gstack-render. Co-Authored-By: Claude Fable 5.1 * refactor(deploy): benchmark, canary, land-and-deploy Step 7, devex-review drive Aside One aside repl script per page prints NAV/PAINT/LCP/RESOURCES/SCRIPTS/CSS/SUMMARY (benchmark), CONSOLE_ERRORS/NAV/TEXT + screenshot (canary, re-run every 60s), and the post-deploy check reads responseStatus from the navigation entry; each carries the $B fallback. Co-Authored-By: Claude Fable 5.1 * feat(third-party-actions): Aside is the recommended driver; gstack's visible browser stays the fallback The readiness probe is lifted from {{ASIDE_SETUP}} at gen time (byte-identity pinned) and rule 3 points at browse/SKILL.md for how to drive; the consent question offers Aside first and gstack's own visible browser (handoff/resume for sign-in) as the fallback, as v1.72 framed it. Co-Authored-By: Claude Fable 5.1 * refactor(scrape): /scrape reads pages through Aside; the browser-skills runtime rides the fallback Look-then-extract scripts build the JSON inside the page and print it between JSON_START/JSON_END; aside exec for fuzzy intents; on the $B fallback the browser-skills match/prototype flow and /skillify apply as before. Co-Authored-By: Claude Fable 5.1 * refactor(make-pdf): print through Aside first, the bundled browser otherwise asideClient.ts replaces the direct $B client with one render() call per PDF (the exact option mapping the browse pdf command had: paper, margins, header/footer/page numbers, tagged, outline, printBackground, preferCSSPageSize, Paged.js wait); the diagram pre-pass, oversized-image downscale and DOCX rasters each run as one render script with per-fence try/catch; exit 4 now means no browser is available and names both remedies; $P setup reports which engine it found. The e2e gates run on whichever engine is present, so the Linux lane exercises the fallback. Co-Authored-By: Claude Fable 5.1 * refactor(diagram): the triplet is one gstack-render call SVG, PNG and excalidraw from one invocation over the content-addressed bundle staged under /tmp/gstack-render; every diagram type gets an excalidraw export; gstack-render picks the engine and prints ENGINE=; the diagram E2E gates on either engine. Co-Authored-By: Claude Fable 5.1 * feat(research): web research runs in Aside first, WebSearch second The planning, review, design, security and investigate skills research through {{ASIDE_RESEARCH}}; WebSearch stays in allowed-tools as the fallback; testing.ts's bootstrap step follows; skeleton ceilings ratcheted for the research block. Co-Authored-By: Claude Fable 5.1 * feat(setup,gen-skill-docs): prune renders of skills that no longer exist setup gains _prune_stale_generated for every host tree and the doc generator removes gstack-* output dirs it did not write, so a skill removed from the source tree can never linger in an install. Co-Authored-By: Claude Fable 5.1 * test: registries, budgets and suite reconciled for Aside-first with the $B fallback Touchfiles + E2E tiers gain the Aside keys, coverage matrix and eval baselines updated, size budget re-baselined to parity-baseline-v1.80.0.0.json (the contract plus fallback ride in every browsing skill), parity ceilings ratcheted with measured values, LLM-judge prompts and the E2E fixtures speak Aside-first, browse-fallback. Co-Authored-By: Claude Fable 5.1 * docs: Aside first, gstack browser fallback README, BROWSER.md, docs/, CONTRIBUTING, CLAUDE.md, ARCHITECTURE, AGENTS.md, TODOS and the root router describe the one product story: Aside is the browser gstack drives first; the bundled headless browser is the automatic fallback (Linux, Windows, app closed) where cookie import, GStack Browser, pair-agent and browser-skills still apply. Co-Authored-By: Claude Fable 5.1 * chore: regenerate SKILL.md docs, llms.txt, agents digest, ship goldens, context-budget fixture bun run gen:skill-docs over the templates; goldens re-rendered; context-budget ceilings recaptured. Co-Authored-By: Claude Fable 5.1 * v1.80.0.0: Aside is the browser gstack drives first; the bundled browser is the fallback MINOR: new capability across ten skills, the renderer and research; nothing removed. CHANGELOG release summary + itemized changes; VERSION 1.80.0.0; package.json 1.80.0. Co-Authored-By: Claude Fable 5.1 * docs(todos): file non-Claude host ownership-gate and version-heading pin follow-ups Two follow-ups from the /plan-ceo-review + /plan-eng-review pass on merging PR #2804 with main's v1.80.0.0 ownership gate: bring the Codex/Factory/ OpenCode/Cursor/Kiro copy loops and the stale-render prune under the .gstack-owned marker rule, and a free test pinning that the CHANGELOG top heading equals VERSION (the collision that git cannot see). Co-Authored-By: Claude Fable 5.1 * fix: pre-landing review fixes for the Aside-first branch Review army + adversarial passes (Claude and Codex) on the merged branch: setup - _prune_stale_generated scans the host dirs too (the generator already removed the render before setup ran, so the host branch was dead), skips symlinks in the render tree (rm -rf on a slash-terminated link empties its target), removes a host symlink only when it resolves into gstack, cleans a bannered real dir through _cleanup_weak_dir, recognizes frontmatter-renamed skills, and logs through log. The always-run codex render passes every host dir that may link to it. - NEEDS_BUILD checks all three binaries (with $_EXE) and lib/ sources; the browser hint and the bootstrap summary honor GSTACK_SKIP_ASIDE, treat a requested skip as a request, and derive one skill list. lib/aside-render.ts + bin/gstack-render.ts - The loopback server carries a per-render secret path, checks containment on the real path (symlink escapes are 403), and rejects malformed encoding. - Inline eval results are one base64 line, so page text cannot forge ASIDE_DIR= or the sentinel; the last ASIDE_DIR wins. - runProc escalates SIGTERM to SIGKILL, bounds every wait, and clears every timer (an uncleared one kept gstack-render alive after printing OK). - renderTmpDir refuses a shared /tmp name owned by someone else; the work dir and server are created inside try; goto's budget follows the render budget. - probeAside classifies a present-but-failing CLI as ASIDE_NOT_RUNNING like the skills' bash probe; render() retries on gstack's own browser when Aside could not start or its private CDP bridge is gone (never on a page error or a timeout of a running script); the CLI reports the engine that actually rendered, exits 0 on --help, rejects non-numeric flags, documents --wait-timeout, fences EVAL/PAGE_ERRORS as untrusted content, and names the daemon's cookie-import JS lock remedy. - The browse path passes --scale only when asked (a scale change rebuilds the daemon context) and restores the viewport after a sized screenshot. resolvers / templates - The bash probe honors GSTACK_SKIP_ASIDE and has a perl deadline on stock macOS; .local is no longer LOCAL (mDNS); same-origin filters compare parsed origins; link status is HEAD-checked only on LOCAL targets; every aside exec goes through the receipted _aside_exec prelude ({{ASIDE_EXEC_PRELUDE}}), including nine template blocks that called it bare; the design sketch and diagram staging use private directories. - The generator prunes only bannered renders and never a host whose generation failed. Docs, stale comments and dead code cleaned; goldens re-rendered; tests updated and added for every behavior above. Co-Authored-By: Claude Fable 5.1 * test: coverage for the render CLI, setup rebuild check, make-pdf exit codes, and prose $B spans New free tests from the ship coverage audit: test/gstack-render-cli.test.ts (argv guards, --help, output contract with a fake daemon, failure and serve-root paths, no-browser case, prompt exit), test/setup-needs-build.test.ts (every binary and source set flips NEEDS_BUILD, Windows suffixes), make-pdf/test/cli-exit-codes.test.ts and setup-smoke.test.ts (error to exit code mapping, runSetup stages, renderPdf's engine), and prose-span cases for extractBrowseCommands in test/skill-parser.test.ts. Co-Authored-By: Claude Fable 5.1 * docs: CHANGELOG and TODOS cover the review fixes (v1.81.0.0) Co-Authored-By: Claude Fable 5.1 * docs: sync project docs with the v1.81.0.0 review fixes BROWSER.md, ARCHITECTURE.md, CONTRIBUTING.md, README.md, CLAUDE.md, docs/TESTING_INTERNALS.md and docs/PROJECT_STRUCTURE.md now describe the shipped renderer and setup: the loopback render server's per-render secret path and real-path containment, ENGINE= naming the engine that actually rendered (mid-run retry on gstack's own browser), EVAL/PAGE_ERRORS fenced as untrusted content, --wait-timeout and the CLI's argv guards, the receipted _aside_exec prelude ({{ASIDE_EXEC_PRELUDE}} in the placeholder table), the LOCAL host rule without .local, LOCAL-only HEAD checks in the links script, GSTACK_SKIP_ASIDE across probe/renderer/setup, the ownership-gated retired-skill prune, the widened NEEDS_BUILD check, and the new free tests (gstack-render-cli, setup-prune-stale-generated, setup-browser-hint, setup-needs-build, make-pdf cli-exit-codes and setup-smoke). Co-Authored-By: Claude Fable 5.1 * docs: CHANGELOG states the precise mid-run retry rule Co-Authored-By: Claude Fable 5.1 * fix(test): skill-e2e-bws slices the $B setup block from the Browser fallback section browse/SKILL.md no longer has '## SETUP' / '## Core QA Patterns' (Aside is the primary driver; the $B block moved under 'Browser fallback'), so the gate test sliced an empty block and handed the agent nothing to run. Anchor on '### Find the `$B` binary' up to the next heading. 7/7 pass. Co-Authored-By: Claude Fable 5.1 * fix(test): gate POSIX-only fixtures off Windows windows-free-tests: the gstack-render CLI tests drive a shebang fake browse that CreateProcess cannot exec, and two NEEDS_BUILD cases assert an execute bit and a bare-name miss that MSYS bash does not have (test -x ignores mode bits and resolves design -> design.exe). Those describes and cases now self-skip on win32; argument guards, --help, the no-browser case, and every other rebuild-check case still run there. Co-Authored-By: Claude Fable 5.1 * fix(render): runProc waits for the exit code until the kill deadline; newtab retries once on a cold daemon A process whose pipes have reached EOF is exiting, but runProc gave the exit code only five seconds to arrive and then returned null, which run() reports as a failed command. Under CI's six-shard load one such render failed with the artifact already written. The SIGTERM/SIGKILL timers already bound the wait, so the exit race now runs to the kill deadline. The first CLI call auto-starts the browse daemon; on a cold start it can answer 'Unable to connect' once while the server is still coming up. That single case is retried after 1.5s; every other newtab failure is not. Co-Authored-By: Claude Fable 5.1 * test(aside-render): warm the daemon before live fallback cases; failures name the render error - Live fallback cases run 'goto about:blank' up to twice before asserting and skip (never fail) when the daemon cannot come up. - expectOk() puts r.error and the browse transcript into the assertion so a failed render is diagnosable from the CI log. - The argv-contract cases dump the fake's log on a miss. - File default timeout is 30s: the subject is the CLI contract, not latency. - Two cases pin the cold-daemon newtab retry and that other errors are not retried. Co-Authored-By: Claude Fable 5.1 * docs: CHANGELOG notes the cold-start tolerance of the bundled-browser renderer Co-Authored-By: Claude Fable 5.1 --------- Co-authored-by: Sina Co-authored-by: Claude Fable 5.1 --- AGENTS.md | 32 +- ARCHITECTURE.md | 65 +- BROWSER.md | 272 +++- CHANGELOG.md | 64 + CLAUDE.md | 90 +- CONTRIBUTING.md | 54 +- README.md | 46 +- SKILL.md | 13 +- SKILL.md.tmpl | 13 +- TODOS.md | 225 ++- VERSION | 2 +- agents-digest/gstack-AGENTS.md | 2 +- autoplan/sections/dx-phase.md | 2 +- autoplan/sections/dx-phase.md.tmpl | 2 +- benchmark/SKILL.md | 153 +- benchmark/SKILL.md.tmpl | 52 +- bin/gstack-render.ts | 171 ++ bin/gstack-team-init | 4 +- browse/SKILL.md | 635 ++++---- browse/SKILL.md.tmpl | 407 +---- browse/sections/manifest.json | 2 +- browse/src/claude-bin.ts | 75 +- browse/src/error-handling.ts | 74 +- browse/src/find-browse.ts | 6 +- canary/SKILL.md | 174 +- canary/SKILL.md.tmpl | 73 +- cso/SKILL.md | 38 +- cso/SKILL.md.tmpl | 11 +- design-consultation/SKILL.md | 204 ++- design-consultation/SKILL.md.tmpl | 64 +- design-html/SKILL.md | 75 +- design-html/SKILL.md.tmpl | 23 +- design-review/SKILL.md | 290 ++-- design-review/SKILL.md.tmpl | 43 +- design-shotgun/SKILL.md | 33 +- design-shotgun/SKILL.md.tmpl | 21 +- devex-review/SKILL.md | 252 ++- devex-review/SKILL.md.tmpl | 44 +- diagram/SKILL.md | 126 +- diagram/SKILL.md.tmpl | 126 +- docs/BROWSER_INTERNALS.md | 2 + docs/OPENCLAW.md | 2 +- docs/PROJECT_STRUCTURE.md | 23 +- docs/REMOTE_BROWSER_ACCESS.md | 2 + docs/SLOP_SCAN.md | 2 +- docs/TESTING_INTERNALS.md | 57 +- docs/domain-skills.md | 2 + docs/howto-diagrams-and-formats.md | 13 +- docs/skills.md | 116 +- gstack/llms.txt | 6 +- investigate/SKILL.md | 42 +- investigate/SKILL.md.tmpl | 15 +- land-and-deploy/SKILL.md | 174 +- land-and-deploy/SKILL.md.tmpl | 55 +- lib/aside-render.ts | 652 ++++++++ lib/claude-bin.ts | 73 + lib/diagram-render/README.md | 16 +- lib/diagram-render/dist/BUILD_INFO.json | 4 +- lib/diagram-render/dist/diagram-render.html | 1397 ++++++++--------- lib/error-handling.ts | 72 + make-pdf/SKILL.md | 30 +- make-pdf/SKILL.md.tmpl | 24 +- make-pdf/src/asideClient.ts | 117 ++ make-pdf/src/browseClient.ts | 428 ----- make-pdf/src/cli.ts | 11 +- make-pdf/src/commands.ts | 2 +- make-pdf/src/diagram-prepass.ts | 426 +++-- make-pdf/src/orchestrator.ts | 249 ++- make-pdf/src/pdftotext.ts | 4 +- make-pdf/src/print-css.ts | 4 +- make-pdf/src/render.ts | 4 +- make-pdf/src/setup.ts | 62 +- make-pdf/src/types.ts | 47 +- make-pdf/test/asideClient.test.ts | 151 ++ make-pdf/test/browseClient.test.ts | 218 --- make-pdf/test/cli-exit-codes.test.ts | 329 ++++ make-pdf/test/coverage-gaps.test.ts | 98 +- make-pdf/test/diagram-prepass.test.ts | 197 ++- make-pdf/test/e2e/browser-available.ts | 15 + make-pdf/test/e2e/ci-prereqs.test.ts | 4 + make-pdf/test/e2e/combined-gate.test.ts | 19 +- make-pdf/test/e2e/diagram-gate.test.ts | 30 +- make-pdf/test/e2e/emoji-gate.test.ts | 31 +- make-pdf/test/e2e/format-gate.test.ts | 18 +- make-pdf/test/e2e/landscape-gate.test.ts | 18 +- make-pdf/test/image-policy.test.ts | 2 +- make-pdf/test/pdftotext.test.ts | 24 + make-pdf/test/render-offline-sanitize.test.ts | 2 +- make-pdf/test/render.test.ts | 2 +- make-pdf/test/setup-smoke.test.ts | 259 +++ office-hours/SKILL.md | 129 +- office-hours/SKILL.md.tmpl | 21 +- package.json | 2 +- plan-ceo-review/SKILL.md | 38 +- plan-ceo-review/SKILL.md.tmpl | 11 +- plan-design-review/SKILL.md | 14 +- plan-design-review/SKILL.md.tmpl | 2 +- plan-devex-review/SKILL.md | 41 +- plan-devex-review/SKILL.md.tmpl | 14 +- plan-eng-review/SKILL.md | 37 +- plan-eng-review/SKILL.md.tmpl | 10 +- qa-only/SKILL.md | 274 ++-- qa-only/SKILL.md.tmpl | 15 +- qa/SKILL.md | 159 +- qa/SKILL.md.tmpl | 58 +- qa/references/issue-taxonomy.md | 8 +- qa/sections/qa-patterns.md | 158 +- qa/sections/test-bootstrap.md | 11 +- qa/templates/qa-report-template.md | 9 +- review/SKILL.md | 38 +- review/SKILL.md.tmpl | 11 +- scrape/SKILL.md | 267 +++- scrape/SKILL.md.tmpl | 181 ++- scripts/free-test-durations.json | 1 - scripts/gen-skill-docs.ts | 36 + scripts/preflight-agent-sdk.ts | 2 +- scripts/resolvers/aside.ts | 266 ++++ scripts/resolvers/browse.ts | 65 + scripts/resolvers/design.ts | 160 +- scripts/resolvers/index.ts | 12 +- scripts/resolvers/make-pdf.ts | 10 +- scripts/resolvers/testing.ts | 14 +- scripts/resolvers/third-party-actions.ts | 43 +- scripts/resolvers/utility.ts | 158 +- setup | 142 +- setup-deploy/SKILL.md | 18 +- ship/SKILL.md | 18 +- ship/sections/tests.md | 11 +- skillify/SKILL.md | 8 +- spec/SKILL.md | 18 +- test/aside-driver.test.ts | 337 ++++ test/aside-render.test.ts | 947 +++++++++++ test/audit-compliance.test.ts | 22 +- test/fixtures/context-budget.json | 98 +- test/fixtures/golden/claude-ship-SKILL.md | 18 +- test/fixtures/golden/codex-ship-SKILL.md | 29 +- test/fixtures/golden/factory-ship-SKILL.md | 29 +- test/fixtures/parity-baseline-v1.81.0.0.json | 643 ++++++++ test/gen-skill-docs-prune-stale.test.ts | 101 ++ test/gen-skill-docs.test.ts | 18 +- test/gstack-home-module-scope.test.ts | 7 +- test/gstack-render-cli.test.ts | 547 +++++++ test/helpers/agent-sdk-runner.ts | 2 +- test/helpers/aside-available.ts | 18 + test/helpers/carve-guards.ts | 52 +- test/helpers/hermetic-env.ts | 2 +- test/helpers/providers/claude.ts | 2 +- test/helpers/skill-parser.ts | 33 +- test/helpers/tool-map.ts | 4 +- test/helpers/touchfiles-data.ts | 63 +- test/paid-orphan-tripwire.test.ts | 4 +- test/setup-browser-hint.test.ts | 237 +++ test/setup-needs-build.test.ts | 232 +++ test/setup-prune-stale-generated.test.ts | 183 +++ test/skill-coverage-matrix.ts | 41 +- test/skill-e2e-aside.test.ts | 302 ++++ test/skill-e2e-bws.test.ts | 30 +- test/skill-e2e-deploy.test.ts | 8 +- test/skill-e2e-design.test.ts | 103 +- test/skill-e2e-diagram.test.ts | 74 +- test/skill-e2e-qa-bugs.test.ts | 47 +- test/skill-e2e-qa-workflow.test.ts | 29 +- test/skill-e2e-skillify.test.ts | 4 +- test/skill-e2e-third-party-actions.test.ts | 50 +- test/skill-fixture.test.ts | 2 +- test/skill-llm-eval.test.ts | 16 +- test/skill-parser.test.ts | 79 + test/skill-size-budget.test.ts | 19 +- test/skill-validation.test.ts | 38 +- test/static-no-legacy-writes.test.ts | 2 +- test/third-party-actions.test.ts | 138 +- test/touchfiles.test.ts | 12 + 172 files changed, 12044 insertions(+), 4676 deletions(-) create mode 100644 bin/gstack-render.ts create mode 100644 lib/aside-render.ts create mode 100644 lib/claude-bin.ts create mode 100644 lib/error-handling.ts create mode 100644 make-pdf/src/asideClient.ts delete mode 100644 make-pdf/src/browseClient.ts create mode 100644 make-pdf/test/asideClient.test.ts delete mode 100644 make-pdf/test/browseClient.test.ts create mode 100644 make-pdf/test/cli-exit-codes.test.ts create mode 100644 make-pdf/test/e2e/browser-available.ts create mode 100644 make-pdf/test/setup-smoke.test.ts create mode 100644 scripts/resolvers/aside.ts create mode 100644 test/aside-driver.test.ts create mode 100644 test/aside-render.test.ts create mode 100644 test/fixtures/parity-baseline-v1.81.0.0.json create mode 100644 test/gen-skill-docs-prune-stale.test.ts create mode 100644 test/gstack-render-cli.test.ts create mode 100644 test/helpers/aside-available.ts create mode 100644 test/setup-browser-hint.test.ts create mode 100644 test/setup-needs-build.test.ts create mode 100644 test/setup-prune-stale-generated.test.ts create mode 100644 test/skill-e2e-aside.test.ts diff --git a/AGENTS.md b/AGENTS.md index 7d802490e..e9e210c09 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,8 +36,8 @@ Invoke them by name (e.g., `/office-hours`). | `/devex-review` | Live developer experience audit (TTHW measured against the real flow). | | `/qa` | Open a real browser, find bugs, fix them, re-verify. | | `/qa-only` | Same methodology as /qa but report only — no code changes. | -| `/scrape` | Pull data from a web page. First call prototypes; codified call runs in ~200ms. | -| `/skillify` | Codify the most recent successful `/scrape` flow into a permanent browser-skill. | +| `/scrape` | Pull data from a web page in your Aside browser, with your real logged-in state. Read-only. On the fallback browser a codified browser-skill answers a repeat intent in ~200ms. | +| `/skillify` | Codify the most recent successful `/scrape` flow into a permanent browser-skill (fallback browser only). | ### Release + deploy @@ -45,7 +45,7 @@ Invoke them by name (e.g., `/office-hours`). |-------|-------------| | `/ship` | Run tests, review, push, open PR. Workspace-aware version queue. | | `/land-and-deploy` | Merge the PR, wait for CI and deploy, verify production health. | -| `/canary` | Post-deploy monitoring loop using the browse daemon. | +| `/canary` | Post-deploy monitoring loop in your Aside browser (or gstack's own when Aside is absent). | | `/landing-report` | Read-only dashboard for the workspace-aware ship queue. | | `/document-release` | Update all docs to match what you just shipped. | | `/document-generate` | Generate Diataxis docs (tutorial / how-to / reference / explanation) from code. | @@ -69,12 +69,18 @@ Invoke them by name (e.g., `/office-hours`). ### Browser + agent integration +Every browser skill drives the Aside AI browser first (macOS 15+, aside.com) — +the user's real browser with their real sessions, through `aside repl` scripts; +gstack never installs it. When Aside is not installed or not running (Linux, +Windows, a closed Aside app) the same skills fall back automatically to gstack's +own headless Chromium (`$B`), which is where the three skills under `/browse` apply. + | Skill | What it does | |-------|-------------| -| `/browse` | Headless browser — real Chromium, real clicks, ~100ms/command. | -| `/open-gstack-browser` | Launch the visible GStack Browser with sidebar + stealth. | -| `/setup-browser-cookies` | Import cookies from your real browser for authenticated testing. | -| `/pair-agent` | Pair a remote AI agent (OpenClaw, Codex, etc.) with your browser. | +| `/browse` | Drive a browser: open a page, read it, click through a flow, screenshots, console errors. Aside first; gstack's own Chromium (~100ms/command) as the fallback. Every other browser skill stands on it. | +| `/open-gstack-browser` | Launch the visible GStack Browser with sidebar + stealth — the headed face of the fallback engine. | +| `/setup-browser-cookies` | Import cookies from your real browser into the fallback engine for authenticated testing. Unnecessary on Aside. | +| `/pair-agent` | Pair a remote AI agent (OpenClaw, Codex, etc.) with gstack's own browser over a scoped tunnel. | ### iOS QA — drive real iPhones over USB or Tailscale (v1.43.0.0+) @@ -104,8 +110,8 @@ End-to-end walkthrough: [docs/howto-ios-testing-with-gstack.md](docs/howto-ios-t | `/freeze` | Lock edits to one directory. Hard block, not just a warning. | | `/guard` | Activate both careful + freeze at once. | | `/unfreeze` | Remove directory edit restrictions. | -| `/make-pdf` | Turn any markdown file into a publication-quality PDF. | -| `/diagram` | English in, diagram out: mermaid source + editable .excalidraw + SVG/PNG, offline. | +| `/make-pdf` | Turn any markdown file into a publication-quality PDF. Renders through Aside, or gstack's own browser when Aside is absent. | +| `/diagram` | English in, diagram out: mermaid source + editable .excalidraw + SVG/PNG, offline. Renders through Aside, or gstack's own browser when Aside is absent. | ## Build commands @@ -126,12 +132,16 @@ bun run skill:check # health dashboard for all skills MSYS today; native PowerShell support is a future expansion. The `bin/gstack-paths` helper resolves state roots through `CLAUDE_PLUGIN_DATA` / `GSTACK_HOME` so plugin installs work on every platform. +- **Browser and renderer**: the browser skills, `/make-pdf`, and `/diagram` drive + the Aside browser first, which is macOS 15+ only. On Linux and Windows (or a + Mac with Aside closed) the readiness check says so once and the same skills use + gstack's own bundled browser, built by `./setup`. ## Key conventions - SKILL.md files are **generated** from `.tmpl` templates. Edit the template, not the output. - Run `bun run gen:skill-docs --host codex` to regenerate Codex-specific output. -- The browse binary provides headless browser access. Use `$B ` in skills. +- Browser steps in skills are `aside repl` scripts per `scripts/resolvers/aside.ts` (Aside first), each with a `$B` equivalent for the fallback engine — `$B ` is the browse binary and is a legitimate tool when the Aside probe does not print `READY`. Local HTML renders through `bin/gstack-render.ts`, which picks the same way. - Safety skills (careful, freeze, guard) use inline advisory prose — always confirm before destructive operations. - State paths resolve via `bin/gstack-paths` (sourced via `eval "$(...)"`). Honors `GSTACK_HOME`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_PLANS_DIR`. -- The `claude` CLI binary resolves via `browse/src/claude-bin.ts` (`Bun.which()` + `GSTACK_CLAUDE_BIN` override). Set `GSTACK_CLAUDE_BIN=wsl` plus `GSTACK_CLAUDE_BIN_ARGS='["claude"]'` to run Claude through WSL on Windows. +- The `claude` CLI binary resolves via `lib/claude-bin.ts` (re-exported from `browse/src/claude-bin.ts` for browse internals; `Bun.which()` + `GSTACK_CLAUDE_BIN` override). Set `GSTACK_CLAUDE_BIN=wsl` plus `GSTACK_CLAUDE_BIN_ARGS='["claude"]'` to run Claude through WSL on Windows. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 374dd8774..398a52004 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -4,9 +4,29 @@ This document explains **why** gstack is built the way it is. For setup and comm ## The core idea -gstack gives Claude Code a persistent browser and a set of opinionated workflow skills. The browser is the hard part — everything else is Markdown. +gstack gives Claude Code a set of opinionated workflow skills and a browser to see with. The browser it reaches for first is the user's own [Aside](https://aside.com) AI browser (macOS 15+): real cookies, real logged-in accounts, the tabs they already have open. When Aside is not installed or not running — Linux, Windows, a closed Aside app — gstack falls back, automatically, to the browser it ships itself: a persistent headless Chromium daemon behind a compiled CLI (`$B`). Same skills, same evidence lines, two engines. -The key insight: an AI agent interacting with a browser needs **sub-second latency** and **persistent state**. If every command cold-starts a browser, you're waiting 3-5 seconds per tool call. If the browser dies between commands, you lose cookies, tabs, and login sessions. So gstack runs a long-lived Chromium daemon that the CLI talks to over localhost HTTP. +The key insight, learned the expensive way: an AI agent wants to be in *your* browser, not in a browser that imitates you. Every feature of the daemon — cookie import so it could be logged in as you, headed mode so you could watch, a CAPTCHA handoff, a tunnel so other agents could join, a sidebar so it could talk back — existed to close the gap to the browser you already had open. Aside is that browser with an agent-grade CLI, so on a Mac with Aside open the skills use it directly: + +``` +Claude Code Aside (the user's browser, macOS 15+) +───────── ───── + bash: aside repl ' diff --git a/lib/error-handling.ts b/lib/error-handling.ts new file mode 100644 index 000000000..81420253b --- /dev/null +++ b/lib/error-handling.ts @@ -0,0 +1,72 @@ +/** + * Shared error-handling utilities for gstack's TypeScript tools and tests. + * + * Each wrapper uses selective catches (checks err.code) to avoid masking + * unexpected errors. Empty catches would be flagged by slop-scan. + */ + +import * as fs from 'fs'; + +// ─── Filesystem ──────────────────────────────────────────────── + +/** Remove a file, ignoring ENOENT (already gone). Rethrows other errors. */ +export function safeUnlink(filePath: string): void { + try { + fs.unlinkSync(filePath); + } catch (err: any) { + if (err?.code !== 'ENOENT') throw err; + } +} + +/** Remove a file, ignoring ALL errors. Use only in best-effort cleanup (shutdown, emergency). */ +export function safeUnlinkQuiet(filePath: string): void { + try { fs.unlinkSync(filePath); } catch {} +} + +// ─── Process ─────────────────────────────────────────────────── + +/** Send a signal to a process, ignoring ESRCH (already dead). Rethrows other errors. */ +export function safeKill(pid: number, signal: NodeJS.Signals | number): void { + try { + process.kill(pid, signal); + } catch (err: any) { + if (err?.code !== 'ESRCH') throw err; + } +} + +/** + * Check if a PID is alive. Pure boolean probe — never throws. + * + * Signal 0 on EVERY platform (#1952). Node maps `process.kill(pid, 0)` to an + * OpenProcess existence check on Windows — and on Windows the browse daemon + * runs under Node (dist/server-node.mjs + bun-polyfill, the documented + * fallback for oven-sh/bun#4253) — so the POSIX idiom is portable here. + * + * Windows used to shell out to `tasklist /FI "PID eq "` and + * string-match the CSV. That was wrong in two ways, both hit in production: + * + * 1. FALSE NEGATIVES UNDER LOAD (#2414/#2295): tasklist takes ~700-1700ms + * on an idle box and far longer under memory pressure. A Bun.spawnSync + * that hits its `timeout` still RETURNS, carrying partial stdout — so + * the `.includes()` match came back false and a LIVE process was + * reported dead. Callers that validate liveness before killing + * (killAgentByRecord, the terminal-agent watchdog) then skipped the + * kill and respawned around the survivor — one leaked terminal-agent + * per tick, self-reinforcing (each orphan slows the next tasklist). + * 2. A console window per probe (#1952): the watchdog blinked a conhost + * window into the foreground every 60s for the whole session. + * + * Signal 0 spawns nothing, cannot time out, and is orders of magnitude + * faster (~0.004ms vs ~270ms measured in #2414). + * + * EPERM means the process EXISTS but we lack rights to signal it. That is + * alive — returning false there would reintroduce failure mode 1. + */ +export function isProcessAlive(pid: number): boolean { + try { + process.kill(pid, 0); + return true; + } catch (err: any) { + return err?.code === 'EPERM'; + } +} diff --git a/make-pdf/SKILL.md b/make-pdf/SKILL.md index d7d934aac..3d3db401e 100644 --- a/make-pdf/SKILL.md +++ b/make-pdf/SKILL.md @@ -83,13 +83,15 @@ Core commands: - `$P generate --cover --toc essay.md out.pdf` — full publication layout - `$P generate --watermark DRAFT memo.md draft.pdf` — diagonal DRAFT watermark - `$P preview ` — render HTML and open in browser (fast iteration) -- `$P setup` — verify browse + Chromium + pdftotext and run a smoke test +- `$P setup` — verify the browser (Aside, or gstack's own headless fallback) + pdftotext and run a smoke test - `$P --help` — full flag reference Output contract: - `stdout`: ONLY the output path on success. One line. - `stderr`: progress (`Rendering HTML... Generating PDF...`) unless `--quiet`. -- Exit 0 success / 1 bad args / 2 render error / 3 Paged.js timeout / 4 browse unavailable. +- Exit 0 success / 1 bad args / 2 render error / 3 Paged.js timeout / 4 no browser available (open the Aside app, or run `./setup` to build gstack's own browser). + +PDFs print through Aside when it is running and through gstack's own headless browser otherwise; the stderr progress line says which (`Rendering PDF through Aside` / `through gstack's browser`). ## Plan Mode Safe Operations @@ -207,7 +209,15 @@ Emoji) ship one; most Linux distros and containers ship none, so emoji render as empty boxes (▯). `./setup` auto-installs `fonts-noto-color-emoji` on Linux (apt/dnf/pacman/apk, best-effort) and the print CSS falls back through Apple / Segoe / Noto emoji families. Set `GSTACK_SKIP_FONTS=1` to skip the install (CI -without sudo, managed or offline machines). +without sudo, managed or offline machines). These matter on the gstack-browser +fallback; Aside renders with the fonts already on the Mac. + +PDF output prints through the Aside browser (macOS 15+, aside.com) when it is +running, and falls back to gstack's own headless browser (built by `./setup`; +`GSTACK_BROWSE_BIN` / `BROWSE_BIN` point at a different build) everywhere +else — Linux, Windows, or a closed Aside app. Exit 4 means neither browser is +available. `--to html` and `--to docx` need no browser at all (diagrams in +DOCX need one to rasterize; without it they embed as source text). ## Core patterns @@ -383,7 +393,13 @@ If the user has a `.md` file open and says "make it look nice", propose ## Debugging -- Output looks empty / blank → check browse daemon is running: `$B status`. +- Exit 4 / "no browser available" → neither the Aside browser (macOS 15+, + aside.com) nor gstack's own headless browser is usable. Open Aside, or run + `./setup` in the gstack repo to build the fallback, re-run. `$P setup` checks + the whole chain and says which browser it found. +- Diagram shows a red "failed to render" block → the parse error is printed in + the block. If EVERY diagram fails with "diagram renderer:", the browser went + away mid-run (Aside closed, or the fallback daemon died). - Fragmented text on copy-paste → highlight.js output (Phase 4). Retry with `--no-syntax` once that flag exists. For now, remove fenced code blocks and regenerate. @@ -398,11 +414,11 @@ If the user has a `.md` file open and says "make it look nice", propose ``` stdout: /tmp/letter.pdf ← just the path, one line stderr: Rendering HTML... ← progress spinner (unless --quiet) - Generating PDF... - Done in 1.5s. 43 words · 22KB · /tmp/letter.pdf + Rendering PDF through Aside... ← or "through gstack's browser" + Done in 11.2s. 43 words · 22KB · /tmp/letter.pdf exit code: 0 success / 1 bad args / 2 render error / 3 Paged.js timeout - / 4 browse unavailable + / 4 no browser available (Aside not open, fallback not built) ``` Capture the path: `PDF=$($P generate letter.md)` — then use `$PDF`. diff --git a/make-pdf/SKILL.md.tmpl b/make-pdf/SKILL.md.tmpl index 9133a711d..cd7b319b5 100644 --- a/make-pdf/SKILL.md.tmpl +++ b/make-pdf/SKILL.md.tmpl @@ -46,7 +46,15 @@ Emoji) ship one; most Linux distros and containers ship none, so emoji render as empty boxes (▯). `./setup` auto-installs `fonts-noto-color-emoji` on Linux (apt/dnf/pacman/apk, best-effort) and the print CSS falls back through Apple / Segoe / Noto emoji families. Set `GSTACK_SKIP_FONTS=1` to skip the install (CI -without sudo, managed or offline machines). +without sudo, managed or offline machines). These matter on the gstack-browser +fallback; Aside renders with the fonts already on the Mac. + +PDF output prints through the Aside browser (macOS 15+, aside.com) when it is +running, and falls back to gstack's own headless browser (built by `./setup`; +`GSTACK_BROWSE_BIN` / `BROWSE_BIN` point at a different build) everywhere +else — Linux, Windows, or a closed Aside app. Exit 4 means neither browser is +available. `--to html` and `--to docx` need no browser at all (diagrams in +DOCX need one to rasterize; without it they embed as source text). ## Core patterns @@ -222,7 +230,13 @@ If the user has a `.md` file open and says "make it look nice", propose ## Debugging -- Output looks empty / blank → check browse daemon is running: `$B status`. +- Exit 4 / "no browser available" → neither the Aside browser (macOS 15+, + aside.com) nor gstack's own headless browser is usable. Open Aside, or run + `./setup` in the gstack repo to build the fallback, re-run. `$P setup` checks + the whole chain and says which browser it found. +- Diagram shows a red "failed to render" block → the parse error is printed in + the block. If EVERY diagram fails with "diagram renderer:", the browser went + away mid-run (Aside closed, or the fallback daemon died). - Fragmented text on copy-paste → highlight.js output (Phase 4). Retry with `--no-syntax` once that flag exists. For now, remove fenced code blocks and regenerate. @@ -237,11 +251,11 @@ If the user has a `.md` file open and says "make it look nice", propose ``` stdout: /tmp/letter.pdf ← just the path, one line stderr: Rendering HTML... ← progress spinner (unless --quiet) - Generating PDF... - Done in 1.5s. 43 words · 22KB · /tmp/letter.pdf + Rendering PDF through Aside... ← or "through gstack's browser" + Done in 11.2s. 43 words · 22KB · /tmp/letter.pdf exit code: 0 success / 1 bad args / 2 render error / 3 Paged.js timeout - / 4 browse unavailable + / 4 no browser available (Aside not open, fallback not built) ``` Capture the path: `PDF=$($P generate letter.md)` — then use `$PDF`. diff --git a/make-pdf/src/asideClient.ts b/make-pdf/src/asideClient.ts new file mode 100644 index 000000000..9f8aedf99 --- /dev/null +++ b/make-pdf/src/asideClient.ts @@ -0,0 +1,117 @@ +/** + * make-pdf's render client: final HTML → PDF through lib/aside-render's + * `render()` — the Aside browser (macOS 15+, aside.com) when it is running, + * otherwise gstack's own headless browser (the browse daemon; GSTACK_BROWSE_BIN + * / BROWSE_BIN override where it lives). The HTML is staged into a private + * dir, served over loopback for the duration of the render, printed, and the + * PDF copied to `output`. No browser at all is exit 4 (BrowserUnavailableError). + */ + +import * as fs from "node:fs"; +import * as path from "node:path"; + +import { + NO_BROWSER, + PAGE_NUMBER_FOOTER, + lengthToInches, + paperInches, + render, + renderTmpDir, + type PdfStepOptions, + type RenderEngine, +} from "../../lib/aside-render"; +import { BrowserUnavailableError } from "./types"; + +export interface PdfOptions { + output: string; + format?: string; + width?: string; + height?: string; + marginTop?: string; + marginRight?: string; + marginBottom?: string; + marginLeft?: string; + headerTemplate?: string; + footerTemplate?: string; + pageNumbers?: boolean; + tagged?: boolean; + outline?: boolean; + printBackground?: boolean; + preferCSSPageSize?: boolean; + /** Wait (≤3s, non-fatal) for Paged.js before printing. */ + toc?: boolean; +} + +/** + * make-pdf's option shape → CDP Page.printToPDF options (inches). Same + * mapping the browse `pdf` command applies: Letter when no size is + * given, empty `
` for whichever header/footer slot is unset so + * Chromium never prints its default URL/date, margins default to none. + */ +export function pdfStepOptions(opts: PdfOptions): PdfStepOptions { + const o: PdfStepOptions = {}; + + if (opts.format) { + const paper = paperInches(opts.format); + if (!paper) throw new Error(`unknown page size: ${opts.format}`); + [o.paperWidth, o.paperHeight] = paper; + } else if (opts.width && opts.height) { + o.paperWidth = lengthToInches(opts.width); + o.paperHeight = lengthToInches(opts.height); + } else { + [o.paperWidth, o.paperHeight] = paperInches("letter")!; + } + + o.marginTop = lengthToInches(opts.marginTop) ?? 0; + o.marginRight = lengthToInches(opts.marginRight) ?? 0; + o.marginBottom = lengthToInches(opts.marginBottom) ?? 0; + o.marginLeft = lengthToInches(opts.marginLeft) ?? 0; + + if (opts.headerTemplate !== undefined || opts.footerTemplate !== undefined || opts.pageNumbers === true) { + o.displayHeaderFooter = true; + o.headerTemplate = opts.headerTemplate ?? "
"; + o.footerTemplate = opts.pageNumbers ? PAGE_NUMBER_FOOTER : (opts.footerTemplate ?? "
"); + } + + if (opts.tagged === true) o.generateTaggedPDF = true; + if (opts.outline === true) o.generateDocumentOutline = true; + if (opts.printBackground === true) o.printBackground = true; + if (opts.preferCSSPageSize === true) o.preferCSSPageSize = true; + if (opts.toc === true) o.waitForPagedJs = true; + return o; +} + +/** + * Render a self-contained HTML document to `opts.output`. Everything the page + * needs must be inline (the orchestrator inlines images as data URIs): only + * the staging dir is served. + */ +export async function renderPdf( + html: string, + opts: PdfOptions, + renderFn: typeof render = render, +): Promise { + const dir = fs.mkdtempSync(path.join(renderTmpDir(), "make-pdf-")); + try { + const file = path.join(dir, "document.html"); + fs.writeFileSync(file, html, "utf8"); + const result = await renderFn({ + file, + steps: [{ kind: "pdf", out: path.resolve(opts.output), options: pdfStepOptions(opts) }], + }); + if (!result.ok) throw renderFailure(result.error ?? "unknown error"); + return result.engine; + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +} + +/** + * Classify a failed render: a BrowserUnavailableError (exit 4) when neither + * browser could run at all, otherwise a plain render error (exit 2). + */ +export function renderFailure(detail: string): Error { + return detail.startsWith(NO_BROWSER) + ? new BrowserUnavailableError(detail) + : new Error(`PDF render failed: ${detail}`); +} diff --git a/make-pdf/src/browseClient.ts b/make-pdf/src/browseClient.ts deleted file mode 100644 index 9ab8d6e9c..000000000 --- a/make-pdf/src/browseClient.ts +++ /dev/null @@ -1,428 +0,0 @@ -/** - * Typed shell-out wrapper for the browse CLI. - * - * Every browse call goes through this file. Reasons: - * - One place to do binary resolution. - * - One place to enforce the --from-file convention for large payloads - * (Windows argv cap is 8191 chars; 200KB HTML dies without this). - * - One place that maps non-zero exit codes to typed errors. - * - * Binary resolution order (Codex round 2 #4, v1.24-aligned): - * 1. $GSTACK_BROWSE_BIN env override (preferred, matches v1.24 GSTACK_*_BIN pattern) - * 2. $BROWSE_BIN env override (back-compat alias) - * 3. sibling dir: dirname(execPath)/../browse/dist/browse[.exe] - * (execPath, NOT argv[0]: in a bun-compiled binary argv[0] is the raw - * invocation string — often relative, so dirname() yields "." and the - * sibling candidates resolve against the CWD instead of the install - * dir; #2156. execPath is always the absolute binary path.) - * 4. ~/.claude/skills/gstack/browse/dist/browse[.exe] - * 5. PATH lookup via Bun.which('browse') — handles Windows PATHEXT natively - * 6. error with setup hint - * - * Windows quirks: - * - bun build --compile --outfile X emits X.exe on win32, so candidate paths - * need a .exe probe pass (fs.accessSync(X_OK) degrades to existence-checking - * on Windows per Node docs, so the bare path silently misses the .exe file). - * - `which` only exists in Git Bash; Bun.which() handles cmd.exe / PowerShell - * natively via PATHEXT semantics. - */ - -import { execFileSync } from "node:child_process"; -import * as fs from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; -import * as crypto from "node:crypto"; - -import { BrowseClientError } from "./types"; - -export interface LoadHtmlOptions { - html: string; // raw HTML string - waitUntil?: "load" | "domcontentloaded" | "networkidle"; - tabId: number; -} - -export interface PdfOptions { - output: string; - tabId: number; - format?: string; - width?: string; - height?: string; - marginTop?: string; - marginRight?: string; - marginBottom?: string; - marginLeft?: string; - headerTemplate?: string; - footerTemplate?: string; - pageNumbers?: boolean; - tagged?: boolean; - outline?: boolean; - printBackground?: boolean; - preferCSSPageSize?: boolean; - toc?: boolean; -} - -export interface JsOptions { - tabId: number; - expression: string; // JS expression to evaluate -} - -/** - * Resolve an absolute or PATH-resolvable command via Bun.which-style semantics, - * with a Windows .exe/.cmd/.bat extension probe for absolute paths. Mirrors - * the v1.24 claude-bin.ts override-resolution shape. - * - * Returns null if nothing resolves; callers degrade with a typed error rather - * than throwing here. - */ -function resolveOverride(value: string | undefined, env: NodeJS.ProcessEnv): string | null { - if (!value?.trim()) return null; - const trimmed = value.trim().replace(/^"(.*)"$/, '$1'); - if (path.isAbsolute(trimmed)) return findExecutable(trimmed); - const PATH = env.PATH ?? env.Path ?? ''; - return Bun.which(trimmed, { PATH }) ?? null; -} - -/** - * Probe a base path for executability, honoring Windows extension suffixes. - * - * On POSIX, isExecutable(base) is the only check that matters. On Windows, - * fs.accessSync(p, X_OK) degrades to an existence check — so a bare-path probe - * misses bun-compiled binaries (which land at base.exe). After the bare probe - * fails on win32, try .exe / .cmd / .bat. Linux/macOS behavior is unchanged. - */ -export function findExecutable(base: string): string | null { - if (isExecutable(base)) return base; - if (process.platform === "win32") { - for (const ext of [".exe", ".cmd", ".bat"]) { - const withExt = base + ext; - if (isExecutable(withExt)) return withExt; - } - } - return null; -} - -/** - * Locate the browse binary. Throws a BrowseClientError with a - * canonical setup message if not found. See header for resolution order. - */ -export function resolveBrowseBin( - env: NodeJS.ProcessEnv = process.env, - // Injectable for tests: under `bun test` the process path is the bun - // runtime, so the compiled-binary shapes are unreachable without a seam. - selfPath: string = process.execPath || process.argv[0], -): string { - // 1 + 2: env overrides (GSTACK_BROWSE_BIN preferred, BROWSE_BIN back-compat). - const overrideRaw = env.GSTACK_BROWSE_BIN ?? env.BROWSE_BIN; - const override = resolveOverride(overrideRaw, env); - if (override) return override; - - // 3: sibling — make-pdf and browse co-located in dist/. execPath, not - // argv[0] (#2156): see the header — argv[0] in a compiled binary is the - // invocation string, and a relative one resolved candidates against CWD. - const selfDir = path.dirname(selfPath); - const siblingCandidates = [ - path.resolve(selfDir, "../browse/dist/browse"), - path.resolve(selfDir, "../../browse/dist/browse"), - path.resolve(selfDir, "../browse"), - ]; - for (const candidate of siblingCandidates) { - const found = findExecutable(candidate); - if (found) return found; - } - - // 4: global install. - const home = os.homedir(); - const globalPath = path.join(home, ".claude/skills/gstack/browse/dist/browse"); - const globalFound = findExecutable(globalPath); - if (globalFound) return globalFound; - - // 5: PATH lookup via Bun.which — handles Windows PATHEXT natively (no `which` - // dependency on cmd.exe / PowerShell, no `where`-vs-`which` branch). - const PATH = env.PATH ?? env.Path ?? ''; - const onPath = Bun.which('browse', { PATH }); - if (onPath) return onPath; - - throw new BrowseClientError( - /* exitCode */ 127, - "resolve", - [ - "browse binary not found.", - "", - "make-pdf needs browse (the gstack Chromium daemon) to render PDFs.", - "Tried:", - ` - $GSTACK_BROWSE_BIN (${env.GSTACK_BROWSE_BIN || "unset"})`, - ` - $BROWSE_BIN (${env.BROWSE_BIN || "unset"})`, - ` - sibling: ${siblingCandidates.join(", ")}`, - ` - global: ${globalPath}`, - " - PATH: `browse`", - "", - "To fix: run gstack setup from the gstack repo:", - " cd ~/.claude/skills/gstack && ./setup", - "", - "Or set GSTACK_BROWSE_BIN explicitly:", - process.platform === "win32" - ? ' setx GSTACK_BROWSE_BIN "C:\\path\\to\\browse.exe"' - : " export GSTACK_BROWSE_BIN=/path/to/browse", - ].join("\n"), - ); -} - -function isExecutable(p: string): boolean { - try { - // Must be a regular FILE. access(X_OK) alone is true for directories — they carry the - // execute/traverse bit on POSIX and pass the Windows check too — so discovery happily - // "found" ~/.claude/skills/browse, which is the skill's docs folder containing nothing - // but SKILL.md, and returned a directory as the browse binary. - if (!fs.statSync(p).isFile()) return false; - fs.accessSync(p, fs.constants.X_OK); - return true; - } catch { - return false; - } -} - -/** - * Run a browse command. Returns stdout on success. - * Throws BrowseClientError on non-zero exit. - */ -function runBrowse(args: string[]): string { - const bin = resolveBrowseBin(); - try { - return execFileSync(bin, args, { - encoding: "utf8", - maxBuffer: 16 * 1024 * 1024, // 16MB; tab content can be large - stdio: ["ignore", "pipe", "pipe"], - // A wedged daemon (or a hostile mermaid source spinning the renderer) - // must fail the run, not hang it forever. - timeout: 120_000, - }); - } catch (err: any) { - const exitCode = typeof err.status === "number" ? err.status : 1; - const stderr = typeof err.stderr === "string" - ? err.stderr - : (err.stderr?.toString() ?? ""); - throw new BrowseClientError(exitCode, args[0] || "unknown", stderr); - } -} - -/** - * Temp dir for any file handed to browse (payloads, rendered HTML, PDF output). - * - * Path must be under the browse safe-dirs allowlist (/tmp or cwd on - * non-Windows; os.tmpdir on Windows). v1.6.0.0 tightened --from-file - * validation to close a CLI/API parity gap (PR #1103), so os.tmpdir() - * on macOS (/var/folders/...) now fails validateReadPath. Use the same - * TEMP_DIR convention as browse/src/platform.ts. - * - * Exported because orchestrator.ts and setup.ts write files that browse must - * read back; os.tmpdir() there trips the same validateReadPath rejection. - */ -export const PAYLOAD_TMP_DIR = process.platform === "win32" ? os.tmpdir() : "/tmp"; - -function writePayloadFile(payload: Record): string { - const hash = crypto.createHash("sha256") - .update(JSON.stringify(payload)) - .digest("hex") - .slice(0, 12); - const tmpPath = path.join(PAYLOAD_TMP_DIR, `make-pdf-browse-${process.pid}-${hash}.json`); - fs.writeFileSync(tmpPath, JSON.stringify(payload), "utf8"); - return tmpPath; -} - -function cleanupPayloadFile(p: string): void { - try { fs.unlinkSync(p); } catch { /* best-effort */ } -} - -// ─── Public API ───────────────────────────────────────────────── - -/** - * Open a new tab. Returns the tabId. - * Requires `$B newtab --json` to be available (added in the browse flag - * extension for this feature). If --json isn't supported yet, the fallback - * parses "Opened tab N" from stdout. - */ -export function newtab(url?: string): number { - const args = ["newtab"]; - if (url) args.push(url); - // Try --json first (preferred path for programmatic use) - try { - const out = runBrowse([...args, "--json"]); - const parsed = JSON.parse(out); - if (typeof parsed.tabId === "number") return parsed.tabId; - } catch { - // Fall back to stdout-string parsing. Brittle, but works on older browse builds. - } - const out = runBrowse(args); - const m = out.match(/tab\s+(\d+)/i); - if (!m) throw new BrowseClientError(1, "newtab", `could not parse tab id from: ${out}`); - return parseInt(m[1], 10); -} - -/** - * Close a tab (by id or the active tab). - */ -export function closetab(tabId?: number): void { - const args = ["closetab"]; - if (tabId !== undefined) args.push(String(tabId)); - runBrowse(args); -} - -/** - * Load raw HTML into a specific tab. - * Uses --from-file for any payload >4KB (Codex round 2 #3). - */ -export function loadHtml(opts: LoadHtmlOptions): void { - // Always use --from-file to dodge argv limits. The HTML is almost always >4KB. - const payload = { - html: opts.html, - waitUntil: opts.waitUntil ?? "domcontentloaded", - }; - const payloadFile = writePayloadFile(payload); - try { - runBrowse([ - "load-html", - "--from-file", payloadFile, - "--tab-id", String(opts.tabId), - ]); - } finally { - cleanupPayloadFile(payloadFile); - } -} - -/** - * Load an HTML file (already under browse's safe dirs, e.g. /tmp) into a tab - * by path. Cheaper than loadHtml for large pages — no JSON payload round-trip; - * browse reads the file directly (diagram-render bundle is ~9MB). - */ -export function loadHtmlFile(opts: { file: string; tabId: number; waitUntil?: "load" | "domcontentloaded" | "networkidle" }): void { - const args = ["load-html", opts.file, "--tab-id", String(opts.tabId)]; - if (opts.waitUntil) args.push("--wait-until", opts.waitUntil); - runBrowse(args); -} - -/** - * Evaluate a JS expression in a tab. Returns the serialized result as string. - */ -export function js(opts: JsOptions): string { - return runBrowse([ - "js", - opts.expression, - "--tab-id", String(opts.tabId), - ]).trim(); -} - -/** - * Evaluate a JS file in a tab (`browse eval `): the argv-safe transport - * for expressions too large for a command-line element. The file must live - * under browse's safe dirs (/tmp or cwd). - */ -export function evalFile(opts: { file: string; tabId: number }): string { - return runBrowse([ - "eval", - opts.file, - "--tab-id", String(opts.tabId), - ]).trim(); -} - -/** - * Poll a boolean JS expression until it evaluates to true, or timeout. - * Returns true if it succeeded, false if timed out. - */ -export function waitForExpression(opts: { - expression: string; - tabId: number; - timeoutMs: number; - pollIntervalMs?: number; -}): boolean { - const poll = opts.pollIntervalMs ?? 200; - const deadline = Date.now() + opts.timeoutMs; - while (Date.now() < deadline) { - try { - const result = js({ expression: opts.expression, tabId: opts.tabId }); - if (result === "true") return true; - } catch { - // Tab may still be loading; keep polling - } - const wait = Math.min(poll, Math.max(0, deadline - Date.now())); - if (wait <= 0) break; - // Real sleep, not a busy-wait: this poll now runs on every diagram-render - // bundle load (and after every fence render error), exactly while Chromium - // is parsing a 9MB page on the same machine — spinning a core competes - // with the work being awaited. - Bun.sleepSync(wait); - } - return false; -} - -/** - * Generate a PDF from the given tab. Uses --from-file when header/footer - * templates are present (they can be HTML strings of arbitrary size). - */ -export function pdf(opts: PdfOptions): void { - // If any large payload is present, send via --from-file - const hasLargePayload = - (opts.headerTemplate && opts.headerTemplate.length > 1024) || - (opts.footerTemplate && opts.footerTemplate.length > 1024); - - if (hasLargePayload) { - const payloadFile = writePayloadFile({ - output: opts.output, - tabId: opts.tabId, - ...optionsToPdfFlags(opts), - }); - try { - runBrowse(["pdf", "--from-file", payloadFile]); - } finally { - cleanupPayloadFile(payloadFile); - } - return; - } - - // Small payload: pass flags via argv - const args = ["pdf", opts.output, "--tab-id", String(opts.tabId)]; - pushFlagsFromOptions(args, opts); - runBrowse(args); -} - -function optionsToPdfFlags(opts: PdfOptions): Record { - // Shape mirrors what the browse `pdf` case expects when reading --from-file - const out: Record = {}; - if (opts.format) out.format = opts.format; - if (opts.width) out.width = opts.width; - if (opts.height) out.height = opts.height; - if (opts.marginTop) out.marginTop = opts.marginTop; - if (opts.marginRight) out.marginRight = opts.marginRight; - if (opts.marginBottom) out.marginBottom = opts.marginBottom; - if (opts.marginLeft) out.marginLeft = opts.marginLeft; - if (opts.headerTemplate !== undefined) out.headerTemplate = opts.headerTemplate; - if (opts.footerTemplate !== undefined) out.footerTemplate = opts.footerTemplate; - if (opts.pageNumbers !== undefined) out.pageNumbers = opts.pageNumbers; - if (opts.tagged !== undefined) out.tagged = opts.tagged; - if (opts.outline !== undefined) out.outline = opts.outline; - if (opts.printBackground !== undefined) out.printBackground = opts.printBackground; - if (opts.preferCSSPageSize !== undefined) out.preferCSSPageSize = opts.preferCSSPageSize; - if (opts.toc !== undefined) out.toc = opts.toc; - return out; -} - -function pushFlagsFromOptions(args: string[], opts: PdfOptions): void { - if (opts.format) { args.push("--format", opts.format); } - if (opts.width) { args.push("--width", opts.width); } - if (opts.height) { args.push("--height", opts.height); } - if (opts.marginTop) { args.push("--margin-top", opts.marginTop); } - if (opts.marginRight) { args.push("--margin-right", opts.marginRight); } - if (opts.marginBottom) { args.push("--margin-bottom", opts.marginBottom); } - if (opts.marginLeft) { args.push("--margin-left", opts.marginLeft); } - if (opts.headerTemplate !== undefined) { - args.push("--header-template", opts.headerTemplate); - } - if (opts.footerTemplate !== undefined) { - args.push("--footer-template", opts.footerTemplate); - } - if (opts.pageNumbers === true) args.push("--page-numbers"); - if (opts.tagged === true) args.push("--tagged"); - if (opts.outline === true) args.push("--outline"); - if (opts.printBackground === true) args.push("--print-background"); - if (opts.preferCSSPageSize === true) args.push("--prefer-css-page-size"); - if (opts.toc === true) args.push("--toc"); -} diff --git a/make-pdf/src/cli.ts b/make-pdf/src/cli.ts index 642e8a7a5..2307a4094 100644 --- a/make-pdf/src/cli.ts +++ b/make-pdf/src/cli.ts @@ -7,11 +7,12 @@ * stderr: progress spinner per stage, final "Done in Xs. N pages." * --quiet: suppress progress. Errors still print. * --verbose: per-stage timings. - * exit 0 success / 1 bad args / 2 render error / 3 Paged.js timeout / 4 browse unavailable. + * exit 0 success / 1 bad args / 2 render error / 3 Paged.js timeout / 4 no browser + * (Aside not running AND gstack's own browser not built). */ import { COMMANDS } from "./commands"; -import { ExitCode, BrowseClientError } from "./types"; +import { ExitCode, BrowserUnavailableError } from "./types"; import type { GenerateOptions, PreviewOptions } from "./types"; interface ParsedArgs { @@ -119,7 +120,7 @@ function printUsage(): void { lines.push(" $P generate --watermark DRAFT memo.md draft.pdf"); lines.push(" $P preview letter.md"); lines.push(""); - lines.push("Run `$P setup` to verify browse + Chromium + pdftotext install."); + lines.push("Run `$P setup` to verify the browser (Aside, or gstack's own fallback) + pdftotext install."); console.error(lines.join("\n")); } @@ -265,9 +266,9 @@ async function main(): Promise { process.exit(ExitCode.BadArgs); } } catch (err: any) { - if (err instanceof BrowseClientError) { + if (err instanceof BrowserUnavailableError) { console.error(`$P: ${err.message}`); - process.exit(ExitCode.BrowseUnavailable); + process.exit(ExitCode.BrowserUnavailable); } if (err?.code === "ENOENT") { console.error(`$P: file not found: ${err.path ?? err.message}`); diff --git a/make-pdf/src/commands.ts b/make-pdf/src/commands.ts index a5e781d1e..5ccb3aeda 100644 --- a/make-pdf/src/commands.ts +++ b/make-pdf/src/commands.ts @@ -48,7 +48,7 @@ export const COMMANDS = new Map2x content box @300dpi, @@ -19,9 +19,11 @@ * through the same sanitizer as user content before substitution (the bundle * renders with securityLevel strict — the sanitizer is the second layer). * - * Reset contract (eng-review D6.2): each fence renders with a fresh - * mermaid.render id; after ANY render error the bundle page is reloaded before - * the next fence so a poisoned global can't corrupt diagram N+1. + * Bundle calls are batched: one render per batch (Aside runs one script per `aside repl` process) and + * nothing survives it, so every consumer collects its calls, runs them in one + * script (`BundleRun`), and substitutes the results. A failed call is data + * (diagnostic block / warning), never an abort. Each PDF run gets a fresh + * bundle page and each fence a fresh mermaid.render id (eng-review D6.2). */ import * as fs from "node:fs"; @@ -30,7 +32,7 @@ import * as path from "node:path"; import * as crypto from "node:crypto"; import { fileURLToPath } from "node:url"; -import * as browseClient from "./browseClient"; +import { render as renderHtml, renderTmpDir } from "../../lib/aside-render"; import { escapeHtml, sanitizeUntrustedHtml } from "./render"; import { imageDims } from "./image-size"; @@ -72,8 +74,8 @@ export interface PrepassImageOptions { /** Physical content-box width in inches (page width minus margins). */ contentWidthIn: number; warn: (msg: string) => void; - /** Lazily provides a ready bundle tab (only opened when needed). */ - getTab: () => RenderTab | null; + /** Bundle runner for print-resolution downscaling; null = inline at full size. */ + run: BundleRun | null; } /** Print-resolution policy (eng-review D4): downscale rasters wider than @@ -289,145 +291,89 @@ function diagramLabel(fence: DiagramFence): string { return fence.title ?? `diagram ${fence.ordinal}`; } -// ─── Render tab (bundle page lifecycle) ─────────────────────────────── +// ─── Bundle runner (diagram-render page, driven through Aside or gstack's browser) ──────── + +export type BundleCall = { fn: string; args: unknown[] }; +export type BundleResult = + | { ok: true; value: string } + | { ok: false; error: string }; +/** Run bundle calls in order. Every call gets a result; failures are data. */ +export type BundleRun = (calls: BundleCall[]) => Promise; -const PAYLOAD_TMP_DIR = process.platform === "win32" ? os.tmpdir() : "/tmp"; const READY_TIMEOUT_MS = 20_000; -// Expressions bigger than this ship via `browse eval ` instead of argv. -// 8KB is safe on every platform (Windows CreateProcess caps the WHOLE command -// line at 32,767 chars; Linux MAX_ARG_STRLEN is ~128KiB) and the tmp-file -// round-trip costs microseconds — one spawn regardless of payload size. -const MAX_ARGV_EXPR_BYTES = 8_000; +/** Aside caps a script at 120s (the browse path shares the budget); ~40 mermaid renders fit with room to spare. */ +const CALLS_PER_SCRIPT = 40; -export class RenderTab { - private constructor( - public readonly tabId: number, - private readonly stagedBundlePath: string, - ) {} - - /** - * Open a tab and load the diagram-render bundle. The bundle HTML is staged - * under /tmp (content-addressed, reused across runs — load-html only reads - * inside its safe dirs) and loaded by PATH, not --from-file: a 9MB JSON - * round-trip per run would be pure waste. - */ - static open(): RenderTab { - const bundleSrc = resolveBundlePath(); - const html = fs.readFileSync(bundleSrc); - const sha = crypto.createHash("sha256").update(html).digest("hex").slice(0, 16); - const staged = path.join(PAYLOAD_TMP_DIR, `gstack-diagram-render-${sha}.html`); - // Never trust an existing file at the predictable shared-/tmp name: verify - // its content hash and re-stage on mismatch (a pre-planted file would - // otherwise be loaded into the render tab as the bundle). - let needsWrite = true; - if (fs.existsSync(staged)) { - try { - const existing = crypto.createHash("sha256").update(fs.readFileSync(staged)).digest("hex").slice(0, 16); - needsWrite = existing !== sha; - } catch { - needsWrite = true; - } - } - if (needsWrite) { - // Concurrent-safe: write to a unique temp name, then atomic rename. - const tmp = `${staged}.${process.pid}.${crypto.randomBytes(4).toString("hex")}`; - fs.writeFileSync(tmp, html); - try { - fs.renameSync(tmp, staged); - } catch (renameErr) { - try { fs.unlinkSync(tmp); } catch { /* best-effort tmp cleanup */ } - // Only swallow the rename failure when the surviving file HASHES to - // the expected bundle (a concurrent writer won an OS-level race). - // Sticky-bit /tmp makes rename-over-foreign-file fail EPERM — if the - // survivor were trusted on existence alone, a pre-planted file would - // ride through the exact check added to stop it. - let survivorOk = false; - try { - const survivor = crypto.createHash("sha256").update(fs.readFileSync(staged)).digest("hex").slice(0, 16); - survivorOk = survivor === sha; - } catch { /* unreadable survivor = not ok */ } - if (!survivorOk) throw renameErr; - } - } - const tabId = browseClient.newtab(); - const tab = new RenderTab(tabId, staged); - tab.loadBundle(); - return tab; - } - - /** (Re)load the bundle page — also the reset path after a render error. */ - loadBundle(): void { - browseClient.loadHtmlFile({ file: this.stagedBundlePath, tabId: this.tabId }); - const ready = browseClient.waitForExpression({ - expression: "document.getElementById('status') !== null && document.getElementById('status').textContent === 'ready'", - tabId: this.tabId, - timeoutMs: READY_TIMEOUT_MS, - }); - if (!ready) { - throw new Error( - "diagram-render bundle did not become ready in the browse tab " + - `(${READY_TIMEOUT_MS}ms). Check \`browse js "window.__errors"\` on tab ${this.tabId}.`, - ); - } - } - - /** - * Call one of the bundle's async window functions with JSON-safe string - * args. Errors come back as a recognizable ERR: prefix so a render failure - * is data, not a thrown browse exit. - */ - call(fn: string, ...args: Array): string { - const argList = args.map((a) => JSON.stringify(a)).join(","); - const expression = - `window.${fn}(${argList})` + - `.then(r => "OK:" + r)` + - `.catch(e => "ERR:" + String((e && e.message) || e))`; - const result = this.js(expression); - if (result.startsWith("OK:")) return result.slice(3); - if (result.startsWith("ERR:")) throw new RenderCallError(result.slice(4)); - throw new RenderCallError(`unexpected bundle result: ${result.slice(0, 200)}`); - } - - private js(expression: string): string { - // Large payloads (scene JSON, SVG text, data URIs) blow past argv limits — - // browseClient.js shells out with the expression as an argv element. The - // limit is BYTES, not chars (CJK content is 3x its char count in UTF-8), - // and Windows caps the whole command line at 32,767 chars — so anything - // big ships via `browse eval ` instead: one spawn, any size. - if (Buffer.byteLength(expression, "utf8") <= MAX_ARGV_EXPR_BYTES) { - return browseClient.js({ expression, tabId: this.tabId }); - } - return this.jsViaFile(expression); - } - - /** argv-safe path for big expressions: stage to a tmp file under browse's - * safe dirs and run `browse eval ` (one spawn regardless of size). */ - private jsViaFile(expression: string): string { - const file = path.join( - PAYLOAD_TMP_DIR, - `gstack-diagram-expr-${process.pid}-${crypto.randomBytes(4).toString("hex")}.js`, - ); - fs.writeFileSync(file, expression, "utf8"); +/** + * Build the runner. The bundle path resolves lazily on the first call so an + * image-only document never touches it; a missing bundle fails every call + * with the resolver's message instead of throwing. + */ +export function bundleRunner(opts: { bundlePath?: string; render?: typeof renderHtml } = {}): BundleRun { + const render = opts.render ?? renderHtml; + let bundlePath = opts.bundlePath; + return async (calls) => { + const results: BundleResult[] = []; try { - return browseClient.evalFile({ file, tabId: this.tabId }); - } finally { - try { fs.unlinkSync(file); } catch { /* best-effort tmp cleanup */ } + if (calls.length > 0) bundlePath ??= resolveBundlePath(); + for (let i = 0; i < calls.length; i += CALLS_PER_SCRIPT) { + results.push(...await runScript(bundlePath!, calls.slice(i, i + CALLS_PER_SCRIPT), render)); + } + } catch (err: any) { + // Unresolvable/unreadable bundle, staging failure: fail what's left as data. + const error = firstLine(err?.message ?? String(err)); + while (results.length < calls.length) results.push({ ok: false, error }); } - } - - close(): void { - try { - browseClient.closetab(this.tabId); - } catch { - // best-effort: orchestrator finally path - } - } + return results; + }; } -export class RenderCallError extends Error { - constructor(msg: string) { - super(msg); - this.name = "RenderCallError"; +/** + * One render (an Aside script, or a browse tab): open the bundle, wait for #done, evaluate one expression + * per call, write each result to a file and read them back. The bundle copy + * and one JSON args file per call sit in a private dir served over loopback, + * so multi-MB payloads (data URIs, scene JSON) never ride argv; results are + * files too (never inline stdout) so SVG/PNG text survives intact. + */ +async function runScript( + bundlePath: string, + calls: BundleCall[], + render: typeof renderHtml, +): Promise { + const dir = fs.mkdtempSync(path.join(renderTmpDir(), "make-pdf-diagrams-")); + try { + const bundle = path.join(dir, "diagram-render.html"); + fs.copyFileSync(bundlePath, bundle, fs.constants.COPYFILE_FICLONE); + const steps = calls.map((call, i) => { + fs.writeFileSync(path.join(dir, `call-${i}.json`), JSON.stringify(call.args)); + // try/catch INSIDE the expression: a throwing fence returns an ERR + // marker and the script keeps going for the other fences. The URL is + // resolved against location.href, not the document base: the bundle + // sets for excalidraw. + const expression = + `(async () => { try { const a = await (await fetch(new URL("call-${i}.json", location.href).href)).json(); ` + + `return "OK:" + await window[${JSON.stringify(call.fn)}](...a); } ` + + `catch (e) { return "ERR:" + String((e && e.message) || e); } })()`; + return { kind: "eval" as const, expression, out: path.join(dir, `result-${i}.txt`) }; + }); + const r = await render({ + file: bundle, + serveRoot: dir, + waitFor: { selector: "#done", timeoutMs: READY_TIMEOUT_MS }, + steps, + }); + if (!r.ok) { + const error = `diagram renderer: ${firstLine(r.error ?? "unknown error")}`; + return calls.map(() => ({ ok: false, error })); + } + return calls.map((_, i) => { + const text = fs.readFileSync(path.join(dir, `result-${i}.txt`), "utf8"); + if (text.startsWith("OK:")) return { ok: true, value: text.slice(3) }; + if (text.startsWith("ERR:")) return { ok: false, error: text.slice(4) }; + return { ok: false, error: `unexpected bundle result: ${text.slice(0, 200)}` }; + }); + } finally { + fs.rmSync(dir, { recursive: true, force: true }); } } @@ -457,38 +403,39 @@ export function resolveBundlePath(env: NodeJS.ProcessEnv = process.env): string // ─── Fence rendering ────────────────────────────────────────────────── /** - * Render every extracted fence to its slot HTML. One bundle tab serves all - * fences; a failed fence yields a diagnostic block and a bundle reload - * (reset contract) before the next fence renders. + * Render every extracted fence to its slot HTML in one batch. A failed fence + * yields a visible diagnostic block; the others still render. */ -export function renderFenceSlots( +export async function renderFenceSlots( fences: DiagramFence[], - tab: RenderTab, + run: BundleRun, warn: (msg: string) => void, -): Map { +): Promise> { const slots = new Map(); + const fail = (fence: DiagramFence, msg: string) => { + warn(`diagram ${fence.ordinal} (${fence.lang}) failed to render: ${firstLine(msg)}`); + slots.set(fence.token, buildDiagnosticBlock(fence, msg)); + }; + const todo: DiagramFence[] = []; for (const fence of fences) { - try { - let svg: string; - if (fence.lang === "mermaid") { - svg = tab.call("__renderMermaid", `mermaid-fence-${fence.ordinal}`, fence.source); - } else { - JSON.parse(fence.source); // fail fast with a JSON diagnostic, not a bundle stack - svg = tab.call("__excalidrawToSvg", fence.source); - } - slots.set(fence.token, buildDiagramFigure(fence, svg)); - } catch (err: any) { - const msg = err?.message ?? String(err); - warn(`diagram ${fence.ordinal} (${fence.lang}) failed to render: ${firstLine(msg)}`); - slots.set(fence.token, buildDiagnosticBlock(fence, msg)); - // Reset contract: a poisoned page must not corrupt the next fence. + if (fence.lang !== "mermaid") { try { - tab.loadBundle(); - } catch (reloadErr: any) { - warn(`bundle reload after render error failed: ${firstLine(reloadErr?.message ?? String(reloadErr))}`); + JSON.parse(fence.source); // fail fast with a JSON diagnostic, not a bundle stack + } catch (err: any) { + fail(fence, err?.message ?? String(err)); + continue; } } + todo.push(fence); } + const results = await run(todo.map((f) => f.lang === "mermaid" + ? { fn: "__renderMermaid", args: [`mermaid-fence-${f.ordinal}`, f.source] } + : { fn: "__excalidrawToSvg", args: [f.source] })); + todo.forEach((fence, i) => { + const r = results[i]; + if (r.ok) slots.set(fence.token, buildDiagramFigure(fence, r.value)); + else fail(fence, r.error); + }); return slots; } @@ -498,15 +445,26 @@ export function renderFenceSlots( * Replace inline diagram SVGs (and svg data-URI images) with PNG tags * for the DOCX export — Word's SVG support is unreliable, so the content- * fidelity contract embeds rasters at 300dpi of the placed width (the - * content box). Diagnostic blocks keep their text form. + * content box). Diagnostic blocks keep their text form. Two passes: swap + * each target for a token while collecting its bundle call, run the batch, + * substitute results. */ -export function rasterizeDiagramFigures( +export async function rasterizeDiagramFigures( html: string, - tab: RenderTab, + run: BundleRun, contentWidthIn: number, warn: (msg: string) => void, -): string { +): Promise { const targetPx = Math.round(contentWidthIn * PRINT_DPI); + const runId = crypto.randomBytes(4).toString("hex"); + const calls: BundleCall[] = []; + const pending: Array<{ token: string; onOk: (png: string) => string; onErr: (reason: string) => string }> = []; + const enqueue = (svgText: string, onOk: (png: string) => string, onErr: (reason: string) => string): string => { + const token = `gstack-raster-slot-${runId}-${calls.length}`; + calls.push({ fn: "__rasterize", args: [svgText, targetPx] }); + pending.push({ token, onOk, onErr }); + return token; + }; // 1. Rendered diagram figures → with the figure's aria-label as alt. let out = html.replace( @@ -515,21 +473,21 @@ export function rasterizeDiagramFigures( const svgMatch = figure.match(//i); if (!svgMatch) return figure; const label = figure.match(/\baria-label\s*=\s*"([^"]*)"/i)?.[1] ?? "diagram"; - try { - const png = tab.call("__rasterize", svgMatch[0], targetPx); - return `

${label}

`; - } catch (err: any) { - const reason = firstLine(err?.message ?? String(err)); - warn(`docx: diagram rasterization failed (${reason}); embedding source text instead`); - // The converter drops
/ entirely, so returning the figure - // would make the diagram vanish without a trace — the exact invisible - // failure the diagnostic contract forbids. Surface the source. - const source = decodeFigureSource(figure) ?? "(source unavailable)"; - return [ - `

Diagram could not be rasterized for DOCX (${escapeHtml(reason)}) — source:

`, - `
${escapeHtml(source)}
`, - ].join("\n"); - } + return enqueue( + svgMatch[0], + (png) => `

${label}

`, + (reason) => { + warn(`docx: diagram rasterization failed (${reason}); embedding source text instead`); + // The converter drops
/ entirely, so returning the figure + // would make the diagram vanish without a trace — the exact invisible + // failure the diagnostic contract forbids. Surface the source. + const source = decodeFigureSource(figure) ?? "(source unavailable)"; + return [ + `

Diagram could not be rasterized for DOCX (${escapeHtml(reason)}) — source:

`, + `
${escapeHtml(source)}
`, + ].join("\n"); + }, + ); }, ); @@ -538,18 +496,25 @@ export function rasterizeDiagramFigures( const m = tag.match(SRC_RE); const src = m?.[2] ?? m?.[3] ?? ""; if (!src.startsWith("data:image/svg+xml")) return tag; - try { - const b64 = src.slice(src.indexOf(",") + 1); - const svgText = Buffer.from(b64, "base64").toString("utf8"); - const png = tab.call("__rasterize", svgText, targetPx); + const svgText = Buffer.from(src.slice(src.indexOf(",") + 1), "base64").toString("utf8"); + return enqueue( + svgText, // Function replacement: data URIs can contain $-patterns. - return tag.replace(SRC_RE, () => `src="${png}"`); - } catch (err: any) { - warn(`docx: svg image rasterization failed (${firstLine(err?.message ?? String(err))})`); - return tag; - } + (png) => tag.replace(SRC_RE, () => `src="${png}"`), + (reason) => { + warn(`docx: svg image rasterization failed (${reason})`); + return tag; + }, + ); }); + if (calls.length === 0) return out; + const results = await run(calls); + pending.forEach((p, i) => { + const r = results[i]; + // split/join, not replace(): the replacement carries user content. + out = out.split(p.token).join(r.ok ? p.onOk(r.value) : p.onErr(firstLine(r.error))); + }); return out; } @@ -581,14 +546,21 @@ const SRC_RE = /\bsrc\s*=\s*("([^"]*)"|'([^']*)')/i; * tab. Missing files become visible placeholders (or throw under --strict); * remote URLs warn (offline posture) unless --allow-network. */ -export function inlineLocalImages(html: string, opts: PrepassImageOptions): string { +export async function inlineLocalImages(html: string, opts: PrepassImageOptions): Promise { const maxPx = Math.round(opts.contentWidthIn * PRINT_DPI * DOWNSCALE_FACTOR); const targetPx = Math.round(opts.contentWidthIn * PRINT_DPI); // An image referenced N times is read/probed/downscaled once; the same data // URI string is reused (also dedupes memory until the final join). const memo = new Map(); + // Oversized rasters get a token src in this pass and their downscaled bytes + // in the second — one bundle batch for the whole document. + const runId = crypto.randomBytes(4).toString("hex"); + const downscales: Array<{ + token: string; src: string; name: string; buf: Buffer; mime: string; + dims: { width: number; height: number }; + }> = []; - return html.replace(IMG_TAG_RE, (tag) => { + const out = html.replace(IMG_TAG_RE, (tag) => { const srcMatch = tag.match(SRC_RE); if (!srcMatch) return tag; const src = srcMatch[2] ?? srcMatch[3] ?? ""; @@ -675,38 +647,54 @@ export function inlineLocalImages(html: string, opts: PrepassImageOptions): stri return buildMissingImagePlaceholder(src); } - let buf = fs.readFileSync(filePath); - let dims = imageDims(buf); - let mime = dims?.mime ?? mimeFromExtension(filePath); + const buf = fs.readFileSync(filePath); + const dims = imageDims(buf); + const mime = dims?.mime ?? mimeFromExtension(filePath); // Print-resolution normalization (D4): rasters only — SVG scales free. - if (dims && mime !== "image/svg+xml" && dims.width > maxPx) { - const tab = opts.getTab(); - if (tab) { - try { - const dataUri = `data:${mime};base64,${buf.toString("base64")}`; - const scaled = tab.call("__downscaleRaster", dataUri, targetPx, mime); - const scaledB64 = scaled.replace(/^data:[^,]*,/, ""); - opts.warn( - `downscaled ${path.basename(filePath)} ${dims.width}px → ${targetPx}px ` + - `(print is ${PRINT_DPI}dpi; original exceeds ${maxPx}px content-box ceiling)`, - ); - buf = Buffer.from(scaledB64, "base64"); - mime = scaled.slice(5, scaled.indexOf(";")); - dims = { ...dims, height: Math.round((dims.height * targetPx) / dims.width), width: targetPx }; - } catch (err: any) { - opts.warn(`downscale failed for ${src}, inlining at full size: ${firstLine(err?.message ?? String(err))}`); - } - } + if (dims && mime !== "image/svg+xml" && dims.width > maxPx && opts.run) { + const token = `gstack-downscale-slot-${runId}-${downscales.length}`; + downscales.push({ token, src, name: path.basename(filePath), buf, mime, dims }); + memo.set(filePath, { dataUri: token, attrs: "" }); + return rewriteImgTag(tag, memo.get(filePath)!); } - const dataUri = `data:${mime};base64,${buf.toString("base64")}`; - const attrs = dims - ? ` data-gstack-px-width="${Math.round(dims.width)}" data-gstack-px-height="${Math.round(dims.height)}"` - : ""; - memo.set(filePath, { dataUri, attrs }); + memo.set(filePath, inlineEntry(buf, mime, dims)); return rewriteImgTag(tag, memo.get(filePath)!); }); + + if (downscales.length === 0) return out; + const results = await opts.run!(downscales.map((d) => ({ + fn: "__downscaleRaster", + args: [`data:${d.mime};base64,${d.buf.toString("base64")}`, targetPx, d.mime], + }))); + const byToken = new Map(); + downscales.forEach((d, i) => { + const r = results[i]; + if (r.ok) { + opts.warn( + `downscaled ${d.name} ${d.dims.width}px → ${targetPx}px ` + + `(print is ${PRINT_DPI}dpi; original exceeds ${maxPx}px content-box ceiling)`, + ); + const height = Math.round((d.dims.height * targetPx) / d.dims.width); + byToken.set(d.token, { dataUri: r.value, attrs: dimAttrs({ width: targetPx, height }) }); + } else { + opts.warn(`downscale failed for ${d.src}, inlining at full size: ${firstLine(r.error)}`); + byToken.set(d.token, inlineEntry(d.buf, d.mime, d.dims)); + } + }); + return out.replace(IMG_TAG_RE, (tag) => { + const entry = byToken.get(tag.match(SRC_RE)?.[2] ?? ""); + return entry ? rewriteImgTag(tag, entry) : tag; + }); +} + +function inlineEntry(buf: Buffer, mime: string, dims: { width: number; height: number } | null): { dataUri: string; attrs: string } { + return { dataUri: `data:${mime};base64,${buf.toString("base64")}`, attrs: dims ? dimAttrs(dims) : "" }; +} + +function dimAttrs(dims: { width: number; height: number }): string { + return ` data-gstack-px-width="${Math.round(dims.width)}" data-gstack-px-height="${Math.round(dims.height)}"`; } /** Apply a memoized inline result to an img tag. */ diff --git a/make-pdf/src/orchestrator.ts b/make-pdf/src/orchestrator.ts index 9fb940849..cb017eaa8 100644 --- a/make-pdf/src/orchestrator.ts +++ b/make-pdf/src/orchestrator.ts @@ -1,5 +1,6 @@ /** - * Orchestrator — ties render, browseClient, and filesystem together. + * Orchestrator — ties render, the diagram pre-pass, asideClient, and the + * filesystem together. * * generate(opts): markdown → PDF on disk. Returns output path. * preview(opts): markdown → HTML, opens it in a browser. @@ -9,23 +10,26 @@ * - stderr: spinner + per-stage status lines, unless opts.quiet. * - --verbose: stage timings. * - * Tab lifecycle: every generate opens a dedicated tab via $B newtab --json, - * runs load-html/js/pdf against --tab-id , and closes the tab in a - * try/finally. Parallel $P generate calls never race on the active tab. + * Every browser step is its own lib/aside-render `render()` call (an Aside + * script when Aside is running, otherwise a tab in gstack's own headless + * browser; nothing persists between them): one batch for diagram fences, one + * for oversized-image downscales, one for DOCX rasters, one print. Parallel + * $P generate calls never share state. */ import * as fs from "node:fs"; +import * as os from "node:os"; import * as path from "node:path"; -import * as crypto from "node:crypto"; import { spawn } from "node:child_process"; import { render } from "./render"; import { screenCss } from "./print-css"; import type { GenerateOptions, PreviewOptions } from "./types"; import { ExitCode } from "./types"; -import * as browseClient from "./browseClient"; +import { pickEngine } from "../../lib/aside-render"; +import { renderPdf } from "./asideClient"; import { - RenderTab, + bundleRunner, contentWidthInches, convertDiagnosticsForDocx, extractDiagramFences, @@ -37,6 +41,9 @@ import { } from "./diagram-prepass"; import { applyImagePolicy } from "./image-policy"; +/** Default output location (`$P generate letter.md` → /tmp/letter.pdf). */ +export const OUTPUT_TMP_DIR = process.platform === "win32" ? os.tmpdir() : "/tmp"; + class ProgressReporter { private readonly quiet: boolean; private readonly verbose: boolean; @@ -85,7 +92,7 @@ export async function generate(opts: GenerateOptions): Promise { const to = opts.to ?? "pdf"; const outputPath = path.resolve( - opts.output ?? path.join(browseClient.PAYLOAD_TMP_DIR, `${deriveSlug(input)}.${to}`), + opts.output ?? path.join(OUTPUT_TMP_DIR, `${deriveSlug(input)}.${to}`), ); // Stage 1: read markdown @@ -94,7 +101,7 @@ export async function generate(opts: GenerateOptions): Promise { progress.end("Reading markdown"); // Stage 1.5: diagram pre-pass — extract ```mermaid/```excalidraw fences and - // swap in placeholder tokens. Rendering happens after the tab opens below. + // swap in placeholder tokens. Rendering happens in Stage 2.5 below. const extraction = extractDiagramFences(markdown); // Stage 2: render HTML @@ -120,87 +127,52 @@ export async function generate(opts: GenerateOptions): Promise { }); progress.end("Rendering HTML", `${rendered.meta.wordCount} words`); - // Stage 2.5: render diagram fences in a dedicated bundle tab, substitute - // slots, then inline + probe + (if oversized) downscale local images. - // The bundle tab is lazy: image-only documents open it only when a raster - // actually needs print-resolution downscaling (eng-review D4). + // Stage 2.5: render diagram fences through the bundle, substitute slots, + // then inline + probe + (if oversized) downscale local images. The runner + // resolves the bundle lazily, so image-only documents never touch it; a + // missing bundle or missing browser surfaces per fence as a diagnostic block. const warn = (msg: string) => { if (!opts.quiet) process.stderr.write(`\r\x1b[K[make-pdf] warning: ${msg}\n`); }; - let renderTab: RenderTab | null = null; + const run = bundleRunner(); let hasLandscape = false; - const getRenderTab = (): RenderTab | null => { - if (renderTab) return renderTab; - try { - renderTab = RenderTab.open(); - } catch (err: any) { - warn(`diagram-render tab unavailable: ${String(err?.message ?? err).split("\n")[0]}`); - return null; - } - return renderTab; - }; let finalHtml = rendered.html; - try { - if (extraction.fences.length > 0) { - progress.begin(`Rendering ${extraction.fences.length} diagram(s)`); - const tab = getRenderTab(); - if (tab) { - const slots = renderFenceSlots(extraction.fences, tab, warn); - finalHtml = substituteSlots(finalHtml, slots); - } else { - // No bundle/tab: visible diagnostic beats silent raw tokens. - const slots = new Map( - extraction.fences.map((f) => [ - f.token, - ``, - ]), - ); - finalHtml = substituteSlots(finalHtml, slots); - } - progress.end(`Rendering ${extraction.fences.length} diagram(s)`); + if (extraction.fences.length > 0) { + progress.begin(`Rendering ${extraction.fences.length} diagram(s)`); + finalHtml = substituteSlots(finalHtml, await renderFenceSlots(extraction.fences, run, warn)); + progress.end(`Rendering ${extraction.fences.length} diagram(s)`); + } + + progress.begin("Inlining images"); + const contentWidthIn = contentWidthInches(opts); + finalHtml = await inlineLocalImages(finalHtml, { + inputDir: path.dirname(input), + strict: opts.strict === true, + allowNetwork: opts.allowNetwork === true, + contentWidthIn, + warn, + run, + }); + progress.end("Inlining images"); + + // Width directives + conservative auto-landscape (image-policy). + const policy = applyImagePolicy(finalHtml, { + contentWidthIn, + landscape: landscapeContentBox(opts), + warn, + }); + finalHtml = policy.html; + hasLandscape = policy.hasLandscape; + + // DOCX needs rasters, not inline SVG (Word's SVG support is unreliable). + if (to === "docx") { + if (/
{ return outputPath; } - // Stage 3: write HTML to a tmp file browse can read - // (We don't actually write it; we pass inline via --from-file JSON.) - // But for preview mode and debugging, we still write to tmp. - const htmlTmp = tmpFile("html"); - fs.writeFileSync(htmlTmp, finalHtml, "utf8"); - - // Stage 4: spin up a dedicated tab, load HTML, (wait for Paged.js if TOC), - // then emit PDF. Always close the tab. - progress.begin("Opening tab"); - const tabId = browseClient.newtab(); - progress.end("Opening tab", `tabId=${tabId}`); - - try { - progress.begin("Loading HTML into Chromium"); - browseClient.loadHtml({ - html: finalHtml, - waitUntil: "domcontentloaded", - tabId, - }); - progress.end("Loading HTML into Chromium"); - - if (opts.toc) { - progress.begin("Paginating with Paged.js"); - // Browse's $B pdf already waits internally when --toc is passed. - // We pass toc=true to browseClient.pdf() below. - progress.end("Paginating with Paged.js", "Paged.js after"); - } - - progress.begin("Generating PDF"); - browseClient.pdf({ - output: outputPath, - tabId, - format: opts.pageSize ?? "letter", - marginTop: opts.marginTop ?? opts.margins ?? "1in", - marginRight: opts.marginRight ?? opts.margins ?? "1in", - marginBottom: opts.marginBottom ?? opts.margins ?? "1in", - marginLeft: opts.marginLeft ?? opts.margins ?? "1in", - headerTemplate: opts.headerTemplate, - footerTemplate: opts.footerTemplate, - // CSS is the single source of truth for page numbers (see print-css.ts - // @bottom-center). Chromium's native numbering always off to avoid double - // footers. The CSS layer honors pageNumbers + footerTemplate via render(). - pageNumbers: false, - tagged: opts.tagged !== false, - outline: opts.outline !== false, - printBackground: !!opts.watermark, - // Named landscape pages only take effect when Chromium honors CSS page - // sizes. Flip it ONLY when a promotion exists — minimal behavior change - // for every other document. - preferCSSPageSize: hasLandscape ? true : undefined, - toc: opts.toc, - }); - progress.end("Generating PDF"); - - const stat = fs.statSync(outputPath); - const kb = Math.round(stat.size / 1024); - progress.done(`${rendered.meta.wordCount} words · ${kb}KB · ${outputPath}`); - } finally { - // Always clean up the tab — even on crash, timeout, or Chromium hang. - try { - browseClient.closetab(tabId); - } catch { - // best-effort; we already exited the main path - } - // Cleanup tmp HTML - try { fs.unlinkSync(htmlTmp); } catch { /* best-effort */ } + // Stage 3: print — one render: serve the staged HTML over loopback, (wait + // ≤3s for Paged.js if --toc), print through whichever browser is up. + const engine = pickEngine().engine; + const via = engine === "aside" ? "Aside" : engine === "browse" ? "gstack's browser" : "a browser"; + progress.begin(`Rendering PDF through ${via}`); + const used = await renderPdf(finalHtml, { + output: outputPath, + format: opts.pageSize ?? "letter", + marginTop: opts.marginTop ?? opts.margins ?? "1in", + marginRight: opts.marginRight ?? opts.margins ?? "1in", + marginBottom: opts.marginBottom ?? opts.margins ?? "1in", + marginLeft: opts.marginLeft ?? opts.margins ?? "1in", + headerTemplate: opts.headerTemplate, + footerTemplate: opts.footerTemplate, + // CSS is the single source of truth for page numbers (see print-css.ts + // @bottom-center). Chromium's native numbering always off to avoid double + // footers. The CSS layer honors pageNumbers + footerTemplate via render(). + pageNumbers: false, + tagged: opts.tagged !== false, + outline: opts.outline !== false, + printBackground: !!opts.watermark, + // Named landscape pages only take effect when Chromium honors CSS page + // sizes. Flip it ONLY when a promotion exists — minimal behavior change + // for every other document. + preferCSSPageSize: hasLandscape ? true : undefined, + toc: opts.toc, + }); + progress.end(`Rendering PDF through ${via}`); + if (used && used !== engine) { + // render() fell back mid-run (Aside quit or its CLI could not start): say + // which browser actually produced the file, since the label above was + // decided before the render. + process.stderr.write(" Aside was unavailable mid-run; the PDF was rendered through gstack's own browser.\n"); } + const kb = Math.round(fs.statSync(outputPath).size / 1024); + progress.done(`${rendered.meta.wordCount} words · ${kb}KB · ${outputPath}`); + return outputPath; } @@ -327,7 +269,7 @@ export async function preview(opts: PreviewOptions): Promise { progress.begin("Rendering HTML"); const markdown = fs.readFileSync(input, "utf8"); - // Preview deliberately skips the diagram/image pre-pass (no browse daemon + // Preview deliberately skips the diagram/image pre-pass (no browser // round-trip — preview is the fast loop). Be loud about the divergence so // nobody signs off on a preview that lacks what the PDF will have. if (!opts.quiet) { @@ -357,7 +299,7 @@ export async function preview(opts: PreviewOptions): Promise { progress.end("Rendering HTML", `${rendered.meta.wordCount} words`); // Write to a stable path under /tmp so the user can reload in the same tab. - const previewPath = path.join(browseClient.PAYLOAD_TMP_DIR, `make-pdf-preview-${deriveSlug(input)}.html`); + const previewPath = path.join(OUTPUT_TMP_DIR, `make-pdf-preview-${deriveSlug(input)}.html`); fs.writeFileSync(previewPath, rendered.html, "utf8"); progress.begin("Opening preview"); @@ -375,11 +317,6 @@ function deriveSlug(p: string): string { return base.replace(/[^a-zA-Z0-9-_]+/g, "-").slice(0, 64) || "document"; } -function tmpFile(ext: string): string { - const hash = crypto.randomBytes(6).toString("hex"); - return path.join(browseClient.PAYLOAD_TMP_DIR, `make-pdf-${process.pid}-${hash}.${ext}`); -} - function tryOpen(pathOrUrl: string): void { const platform = process.platform; const cmd = platform === "darwin" ? "open" : diff --git a/make-pdf/src/pdftotext.ts b/make-pdf/src/pdftotext.ts index df6d05335..6ebbf0ee7 100644 --- a/make-pdf/src/pdftotext.ts +++ b/make-pdf/src/pdftotext.ts @@ -46,8 +46,6 @@ export interface PdftotextInfo { /** * Probe a base path for executability, honoring Windows extension suffixes. - * Matches browseClient.ts:findExecutable — duplicated rather than shared - * because the two modules already duplicate isExecutable for compile-isolation. */ export function findExecutable(base: string): string | null { if (isExecutable(base)) return base; @@ -144,6 +142,8 @@ export function resolvePopplerTool( function isExecutable(p: string): boolean { try { + // access(X_OK) is true for directories (the traverse bit); only regular files count. + if (!fs.statSync(p).isFile()) return false; fs.accessSync(p, fs.constants.X_OK); return true; } catch { diff --git a/make-pdf/src/print-css.ts b/make-pdf/src/print-css.ts index e097d257d..02137a11e 100644 --- a/make-pdf/src/print-css.ts +++ b/make-pdf/src/print-css.ts @@ -7,8 +7,8 @@ * * - Helvetica first, with Liberation Sans as a metric-compatible Linux * fallback (Helvetica and Arial aren't installed on most Linux distros; - * Liberation Sans ships via the fonts-liberation package and Playwright's - * install-deps). No bundled webfonts — dodges the per-glyph Tj bug that + * Liberation Sans ships via the fonts-liberation package). No bundled + * webfonts — dodges the per-glyph Tj bug that * breaks copy-paste extraction. * - All paragraphs flush-left. No first-line indent, no justify, no * p+p indent. text-align: left everywhere. 12pt margin-bottom. diff --git a/make-pdf/src/render.ts b/make-pdf/src/render.ts index 609c63e0a..754809acc 100644 --- a/make-pdf/src/render.ts +++ b/make-pdf/src/render.ts @@ -1,5 +1,5 @@ /** - * Markdown → HTML renderer. Pure function, no I/O, no Playwright. + * Markdown → HTML renderer. Pure function, no I/O, no browser. * * Pipeline: * 1. marked parses markdown → HTML @@ -51,7 +51,7 @@ export interface RenderOptions { } export interface RenderResult { - html: string; // full HTML document, ready for $B load-html + html: string; // full HTML document, staged and printed through the browser printCss: string; // for debugging / preview bodyHtml: string; // just the rendered body (tests, snapshots) meta: { diff --git a/make-pdf/src/setup.ts b/make-pdf/src/setup.ts index 8135edc66..af249284e 100644 --- a/make-pdf/src/setup.ts +++ b/make-pdf/src/setup.ts @@ -1,52 +1,56 @@ /** * `$P setup` — guided smoke test. * - * Flow (per the CEO plan CLI UX spec): - * 1. Verify browse binary exists and responds - * 2. Verify Chromium launches via $B goto about:blank + * Flow: + * 1. Find a browser: Aside (primary) or gstack's own headless browser (fallback) + * 2. Render a tiny HTML page through it * 3. Verify pdftotext is installed (warn, don't fail) * 4. Generate a smoke-test PDF from an inline 2-paragraph fixture - * 5. Open it - * 6. Print a 3-command cheatsheet + * 5. Print a 3-command cheatsheet */ import * as path from "node:path"; import * as fs from "node:fs"; -import * as browseClient from "./browseClient"; +import { NO_BROWSER_HELP, pickEngine, render, renderTmpDir } from "../../lib/aside-render"; +import { ExitCode } from "./types"; import { resolvePdftotext, PdftotextUnavailableError } from "./pdftotext"; -import { generate } from "./orchestrator"; +import { OUTPUT_TMP_DIR, generate } from "./orchestrator"; export async function runSetup(): Promise { process.stderr.write("make-pdf setup — verifying install\n\n"); - // 1. Resolve browse binary - process.stderr.write(" [1/5] Checking browse binary..."); - try { - const bin = browseClient.resolveBrowseBin(); - process.stderr.write(` OK (${bin})\n`); - } catch (err: any) { + // 1. A browser: Aside when it answers, else gstack's own + process.stderr.write(" [1/5] Checking for a browser..."); + const engine = pickEngine(); + if (!engine.engine) { process.stderr.write(" FAIL\n"); - process.stderr.write(`\n${err.message}\n`); - process.exit(4); + process.stderr.write(`\n${engine.error}\n`); + process.exit(ExitCode.BrowserUnavailable); } + const via = engine.engine === "aside" ? `Aside ${engine.version}` : "gstack browser"; + process.stderr.write(engine.engine === "aside" + ? ` Aside OK (${engine.version})\n` + : ` gstack browser OK (fallback: ${engine.bin}; Aside is not running)\n`); - // 2. Chromium smoke (navigate a dedicated tab to about:blank) - process.stderr.write(" [2/5] Launching Chromium..."); - let chromiumTab: number | null = null; + // 2. Render smoke: open a tiny page and read it back + process.stderr.write(` [2/5] Rendering through ${via}...`); + const smokeDir = fs.mkdtempSync(path.join(renderTmpDir(), "make-pdf-setup-")); try { - chromiumTab = browseClient.newtab("about:blank"); - process.stderr.write(` OK (tab ${chromiumTab})\n`); + const file = path.join(smokeDir, "smoke.html"); + fs.writeFileSync(file, "make-pdf smoke

browser-ok

", "utf8"); + const r = await render({ file, steps: [{ kind: "eval", expression: "document.getElementById('t').textContent" }] }); + if (!r.ok || r.evals[0] !== "browser-ok") { + throw new Error(r.error ?? `unexpected page text: ${r.evals[0]}`); + } + process.stderr.write(" OK\n"); } catch (err: any) { process.stderr.write(" FAIL\n"); - process.stderr.write(`\nChromium failed to launch: ${err.message}\n`); - process.stderr.write("\nTo fix: run gstack setup from the gstack repo:\n"); - process.stderr.write(" cd ~/.claude/skills/gstack && ./setup\n"); - process.exit(4); + process.stderr.write(`\n${via} could not render a page: ${err.message}\n`); + process.stderr.write(`To fix: ${NO_BROWSER_HELP}\n`); + process.exit(ExitCode.BrowserUnavailable); } finally { - if (chromiumTab !== null) { - try { browseClient.closetab(chromiumTab); } catch { /* ignore */ } - } + fs.rmSync(smokeDir, { recursive: true, force: true }); } // 3. pdftotext (optional — CI gate only) @@ -76,8 +80,8 @@ export async function runSetup(): Promise { "The second paragraph contains curly quotes (\"hello\"), an em dash -- like this, and an ellipsis... all of which should render correctly.", "", ].join("\n"); - const fixturePath = path.join(browseClient.PAYLOAD_TMP_DIR, `make-pdf-smoke-${process.pid}.md`); - const outPath = path.join(browseClient.PAYLOAD_TMP_DIR, `make-pdf-smoke-${process.pid}.pdf`); + const fixturePath = path.join(OUTPUT_TMP_DIR, `make-pdf-smoke-${process.pid}.md`); + const outPath = path.join(OUTPUT_TMP_DIR, `make-pdf-smoke-${process.pid}.pdf`); fs.writeFileSync(fixturePath, fixture, "utf8"); try { diff --git a/make-pdf/src/types.ts b/make-pdf/src/types.ts index 6ff2d40cb..a0b9758b3 100644 --- a/make-pdf/src/types.ts +++ b/make-pdf/src/types.ts @@ -18,7 +18,7 @@ export interface GenerateOptions { output?: string; // output path (default: /tmp/.) // Output format (NOT --format, which is a --page-size alias): - // pdf — print-quality PDF via Chromium (default) + // pdf — print-quality PDF through the browser: Aside, else gstack's own (default) // html — single self-contained file, zero network references // docx — content-fidelity Word document (diagrams embedded as PNG) to?: OutputFormat; @@ -82,32 +82,6 @@ export interface PreviewOptions { date?: string; } -/** - * Parsed page.pdf() options passed to browse. - */ -export interface BrowsePdfOptions { - output: string; - tabId: number; - format?: PageSize; - width?: string; - height?: string; - margins?: { - top: string; - right: string; - bottom: string; - left: string; - }; - headerTemplate?: string; - footerTemplate?: string; - pageNumbers?: boolean; - displayHeaderFooter?: boolean; - tagged?: boolean; - outline?: boolean; - printBackground?: boolean; - preferCSSPageSize?: boolean; - toc?: boolean; // signals browse to wait for Paged.js -} - /** * Exit codes for $P generate. * Mirror these in orchestrator error paths. @@ -117,20 +91,19 @@ export const ExitCode = { BadArgs: 1, RenderError: 2, PagedJsTimeout: 3, - BrowseUnavailable: 4, + BrowserUnavailable: 4, } as const; export type ExitCode = typeof ExitCode[keyof typeof ExitCode]; /** - * Structured error for browse CLI shell-out failures. + * No browser at all: Aside is not installed or not open AND gstack's own + * headless browser is not built (exit 4). The message (lib/aside-render's + * NO_BROWSER text) names both remedies. A render that fails while a browser + * IS available is a plain Error (exit 2). */ -export class BrowseClientError extends Error { - constructor( - public readonly exitCode: number, - public readonly command: string, - public readonly stderr: string, - ) { - super(`browse ${command} exited ${exitCode}: ${stderr.trim()}`); - this.name = "BrowseClientError"; +export class BrowserUnavailableError extends Error { + constructor(message: string) { + super(message); + this.name = "BrowserUnavailableError"; } } diff --git a/make-pdf/test/asideClient.test.ts b/make-pdf/test/asideClient.test.ts new file mode 100644 index 000000000..7f041ecdc --- /dev/null +++ b/make-pdf/test/asideClient.test.ts @@ -0,0 +1,151 @@ +/** + * asideClient unit tests — PdfOptions → CDP Page.printToPDF mapping, the + * staging/failure shape of renderPdf (render function injected), and the + * no-browser classification (BrowserUnavailableError, exit 4). No live + * browser needed. + */ + +import { describe, expect, test } from "bun:test"; +import * as fs from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import { pdfStepOptions, renderFailure, renderPdf } from "../src/asideClient"; +import { BrowserUnavailableError, ExitCode } from "../src/types"; +import { NO_BROWSER, NO_BROWSER_HELP, type RenderResult, type RenderSpec } from "../../lib/aside-render"; + +describe("pdfStepOptions", () => { + test("defaults: Letter paper, zero margins, no header/footer, nothing else set", () => { + const o = pdfStepOptions({ output: "/tmp/x.pdf" }); + expect(o.paperWidth).toBe(8.5); + expect(o.paperHeight).toBe(11); + expect([o.marginTop, o.marginRight, o.marginBottom, o.marginLeft]).toEqual([0, 0, 0, 0]); + expect(o.displayHeaderFooter).toBeUndefined(); + expect(o.generateTaggedPDF).toBeUndefined(); + expect(o.generateDocumentOutline).toBeUndefined(); + expect(o.printBackground).toBeUndefined(); + expect(o.preferCSSPageSize).toBeUndefined(); + expect(o.waitForPagedJs).toBeUndefined(); + }); + + test("named formats map to paper inches, case-insensitively", () => { + expect(pdfStepOptions({ output: "o", format: "a4" }).paperWidth).toBeCloseTo(8.27); + expect(pdfStepOptions({ output: "o", format: "A4" }).paperHeight).toBeCloseTo(11.7); + expect(pdfStepOptions({ output: "o", format: "legal" }).paperHeight).toBe(14); + expect(() => pdfStepOptions({ output: "o", format: "napkin" })).toThrow(/unknown page size/); + }); + + test("explicit width/height lengths win only when no format is given", () => { + const o = pdfStepOptions({ output: "o", width: "10in", height: "254mm" }); + expect(o.paperWidth).toBe(10); + expect(o.paperHeight).toBeCloseTo(10); + const withFormat = pdfStepOptions({ output: "o", format: "letter", width: "10in", height: "10in" }); + expect(withFormat.paperWidth).toBe(8.5); + }); + + test("margins convert per side (in/pt/cm/mm/px)", () => { + const o = pdfStepOptions({ output: "o", marginTop: "1in", marginRight: "72pt", marginBottom: "2.54cm", marginLeft: "96px" }); + expect(o.marginTop).toBe(1); + expect(o.marginRight).toBeCloseTo(1); + expect(o.marginBottom).toBeCloseTo(1); + expect(o.marginLeft).toBeCloseTo(1); + }); + + test("header only: footer gets the empty
so Chromium prints no default URL/date", () => { + const o = pdfStepOptions({ output: "o", headerTemplate: "H" }); + expect(o.displayHeaderFooter).toBe(true); + expect(o.headerTemplate).toBe("H"); + expect(o.footerTemplate).toBe("
"); + }); + + test("footer only: header gets the empty
", () => { + const o = pdfStepOptions({ output: "o", footerTemplate: "F" }); + expect(o.headerTemplate).toBe("
"); + expect(o.footerTemplate).toBe("F"); + }); + + test("pageNumbers builds the 'N of M' footer and overrides a custom footer", () => { + const o = pdfStepOptions({ output: "o", pageNumbers: true, footerTemplate: "ignored" }); + expect(o.displayHeaderFooter).toBe(true); + expect(o.headerTemplate).toBe("
"); + expect(o.footerTemplate).toContain('class="pageNumber"'); + expect(o.footerTemplate).toContain('class="totalPages"'); + expect(o.footerTemplate).not.toContain("ignored"); + }); + + test("pageNumbers:false alone does not turn on header/footer", () => { + expect(pdfStepOptions({ output: "o", pageNumbers: false }).displayHeaderFooter).toBeUndefined(); + }); + + test("tagged/outline/printBackground/preferCSSPageSize/toc map to their CDP names", () => { + const o = pdfStepOptions({ output: "o", tagged: true, outline: true, printBackground: true, preferCSSPageSize: true, toc: true }); + expect(o.generateTaggedPDF).toBe(true); + expect(o.generateDocumentOutline).toBe(true); + expect(o.printBackground).toBe(true); + expect(o.preferCSSPageSize).toBe(true); + expect(o.waitForPagedJs).toBe(true); + // false never emits the key (CDP defaults apply) + expect(pdfStepOptions({ output: "o", tagged: false, outline: false }).generateTaggedPDF).toBeUndefined(); + }); +}); + +describe("renderPdf", () => { + test("stages the HTML into a private dir, asks for one pdf step, and cleans up", async () => { + const seen: RenderSpec[] = []; + const fakeRender = async (spec: RenderSpec): Promise => { + seen.push(spec); + expect(fs.readFileSync(spec.file, "utf8")).toBe("

hi

"); + return { ok: true, outputs: [], evals: {}, stdout: "" }; + }; + const out = path.join(os.tmpdir(), `aside-client-${process.pid}.pdf`); + await renderPdf("

hi

", { output: out, format: "a4", tagged: true }, fakeRender); + expect(seen).toHaveLength(1); + expect(seen[0].steps).toHaveLength(1); + const step = seen[0].steps[0]; + expect(step.kind).toBe("pdf"); + if (step.kind === "pdf") { + expect(step.out).toBe(out); + expect(step.options?.generateTaggedPDF).toBe(true); + expect(step.options?.paperWidth).toBeCloseTo(8.27); + } + // Staging dir is gone after the render. + expect(fs.existsSync(path.dirname(seen[0].file))).toBe(false); + }); + + test("a failed render with a browser up is a plain render error (exit 2 class), never silent", async () => { + const failing = async (): Promise => ({ ok: false, engine: "aside", outputs: [], evals: {}, stdout: "", error: "render script did not finish" }); + const err = await renderPdf("

", { output: "/tmp/never.pdf" }, failing).catch((e: Error) => e); + expect(err).toBeInstanceOf(Error); + expect(err).not.toBeInstanceOf(BrowserUnavailableError); + expect((err as Error).message).toMatch(/PDF render failed: render script did not finish/); + }); + + test("no browser at all (render() found neither Aside nor the browse binary) is BrowserUnavailableError", async () => { + const none = async (): Promise => ({ ok: false, outputs: [], evals: {}, stdout: "", error: `${NO_BROWSER}: ${NO_BROWSER_HELP} (NEEDS_ASIDE: aside not on PATH)` }); + const err = await renderPdf("

", { output: "/tmp/never.pdf" }, none).catch((e: Error) => e); + expect(err).toBeInstanceOf(BrowserUnavailableError); + expect((err as Error).message).toContain("aside.com"); + expect((err as Error).message).toContain("./setup"); + expect((err as Error).message).toContain("GSTACK_BROWSE_BIN"); + }); + + test("the fallback engine's failures are render errors too (engine picked ≠ engine missing)", async () => { + const browseFail = async (): Promise => ({ ok: false, engine: "browse", outputs: [], evals: {}, stdout: "", error: "browse pdf failed: boom" }); + await expect(renderPdf("

", { output: "/tmp/never.pdf" }, browseFail)).rejects.toThrow(/PDF render failed: browse pdf failed: boom/); + }); +}); + +describe("BrowserUnavailableError", () => { + test("renderFailure classifies on the NO_BROWSER prefix only", () => { + expect(renderFailure(`${NO_BROWSER}: x`)).toBeInstanceOf(BrowserUnavailableError); + expect(renderFailure("no browser available")).toBeInstanceOf(BrowserUnavailableError); + expect(renderFailure("Aside closed mid-run")).not.toBeInstanceOf(BrowserUnavailableError); + expect(new BrowserUnavailableError("m").name).toBe("BrowserUnavailableError"); + }); + + test("exit code 4 is no-browser (the old Aside/browse slot, same value)", () => { + expect(ExitCode.BrowserUnavailable).toBe(4); + expect((ExitCode as Record).AsideUnavailable).toBeUndefined(); + expect((ExitCode as Record).BrowseUnavailable).toBeUndefined(); + }); +}); diff --git a/make-pdf/test/browseClient.test.ts b/make-pdf/test/browseClient.test.ts deleted file mode 100644 index 4bf6f1687..000000000 --- a/make-pdf/test/browseClient.test.ts +++ /dev/null @@ -1,218 +0,0 @@ -/** - * browseClient unit tests — binary resolution and error mapping. - * - * These are pure unit tests; they do NOT require a running browse daemon. - * Cross-platform: assertions that pin POSIX behavior early-return on win32 - * and vice versa, so both lanes only exercise their own branch. - */ - -import { describe, expect, test } from "bun:test"; -import * as fs from "node:fs"; -import * as os from "node:os"; -import * as path from "node:path"; - -import { BrowseClientError } from "../src/types"; -import { resolveBrowseBin, findExecutable } from "../src/browseClient"; - -// A real, always-present executable for the test platform — `cmd.exe` on -// Windows (System32 is on every install) and `/bin/sh` on POSIX. Lets the -// "honors override when it points at a real executable" test work in both -// lanes without writing a temp script. -const REAL_EXE: string = - process.platform === "win32" - ? path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "cmd.exe") - : "/bin/sh"; - -function withEnv(overrides: Record, fn: () => T): T { - const saved: Record = {}; - for (const k of Object.keys(overrides)) saved[k] = process.env[k]; - for (const [k, v] of Object.entries(overrides)) { - if (v === undefined) delete process.env[k]; - else process.env[k] = v; - } - try { - return fn(); - } finally { - for (const [k, v] of Object.entries(saved)) { - if (v === undefined) delete process.env[k]; - else process.env[k] = v; - } - } -} - -describe("findExecutable", () => { - test("returns the bare path on POSIX when it's executable", () => { - if (process.platform === "win32") return; - const found = findExecutable("/bin/sh"); - expect(found).toBe("/bin/sh"); - }); - - test("on win32, probes .exe / .cmd / .bat after the bare-path miss", () => { - if (process.platform !== "win32") return; - // cmd.exe lives at System32\cmd.exe — probe with the bare base. - const base = path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "cmd"); - const found = findExecutable(base); - expect(found).toBe(base + ".exe"); - }); - - test("returns null when no extension matches", () => { - const found = findExecutable("/nonexistent/path/to/nothing"); - expect(found).toBeNull(); - }); - - // access(X_OK) is TRUE for directories — they carry the execute/traverse bit — so a - // bare X_OK test returned ~/.claude/skills/browse, the skill's docs folder, as "the - // browse binary". Every browse call then failed with an empty error, which surfaced - // as make-pdf reporting "Chromium failed to launch". - test("rejects a DIRECTORY even though it passes access(X_OK)", () => { - const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-dir-")); - try { - // Prove the precondition: the directory really does pass the old test. - let passesXok = true; - try { - fs.accessSync(dir, fs.constants.X_OK); - } catch { - passesXok = false; - } - expect(passesXok).toBe(true); - - expect(findExecutable(dir)).toBeNull(); - } finally { - fs.rmSync(dir, { recursive: true, force: true }); - } - }); - - test("rejects a directory that shadows a real binary name", () => { - // The exact shape of the bug: a directory named like the thing being looked for. - const base = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-shadow-")); - const shadow = path.join(base, "browse"); - fs.mkdirSync(shadow); - fs.writeFileSync(path.join(shadow, "SKILL.md"), "# not a binary\n"); - try { - expect(findExecutable(shadow)).toBeNull(); - } finally { - fs.rmSync(base, { recursive: true, force: true }); - } - }); -}); - -describe("resolveBrowseBin", () => { - test("throws BrowseClientError with setup hint when nothing is found", () => { - // Point overrides at non-existent paths and clear PATH so Bun.which finds - // nothing. Sibling/global probes go through findExecutable on real paths, - // but the test asserts on the error shape rather than depending on whether - // a real browse install exists on the box. - let thrown: unknown = null; - try { - withEnv( - { - GSTACK_BROWSE_BIN: "/nonexistent/gstack-browse-bin", - BROWSE_BIN: "/nonexistent/browse-bin", - PATH: "", - Path: "", - }, - () => resolveBrowseBin(), - ); - } catch (err) { - thrown = err; - } - - if (thrown) { - expect(thrown).toBeInstanceOf(BrowseClientError); - expect((thrown as BrowseClientError).message).toContain("browse binary not found"); - expect((thrown as BrowseClientError).message).toContain("./setup"); - expect((thrown as BrowseClientError).message).toContain("GSTACK_BROWSE_BIN"); - // Back-compat alias still surfaces in the diagnostic. - expect((thrown as BrowseClientError).message).toContain("BROWSE_BIN"); - } - // If the test box has a real browse install on disk, sibling/global may - // resolve and the helper won't throw — that's fine; the assertion is - // gated on whether it threw at all. - }); - - test("honors GSTACK_BROWSE_BIN when it points at a real executable", () => { - const resolved = withEnv({ GSTACK_BROWSE_BIN: REAL_EXE }, () => resolveBrowseBin()); - expect(resolved).toBe(REAL_EXE); - }); - - test("honors BROWSE_BIN as a back-compat alias", () => { - const resolved = withEnv( - { GSTACK_BROWSE_BIN: undefined, BROWSE_BIN: REAL_EXE }, - () => resolveBrowseBin(), - ); - expect(resolved).toBe(REAL_EXE); - }); - - test("GSTACK_BROWSE_BIN takes precedence over BROWSE_BIN", () => { - const resolved = withEnv( - { GSTACK_BROWSE_BIN: REAL_EXE, BROWSE_BIN: "/nonexistent/legacy" }, - () => resolveBrowseBin(), - ); - expect(resolved).toBe(REAL_EXE); - }); - - test("strips wrapping double quotes from override values", () => { - const resolved = withEnv({ GSTACK_BROWSE_BIN: `"${REAL_EXE}"` }, () => resolveBrowseBin()); - expect(resolved).toBe(REAL_EXE); - }); -}); - -describe("BrowseClientError", () => { - test("captures exit code, command, and stderr", () => { - const err = new BrowseClientError(127, "pdf", "Chromium not found"); - expect(err.exitCode).toBe(127); - expect(err.command).toBe("pdf"); - expect(err.stderr).toBe("Chromium not found"); - expect(err.message).toContain("browse pdf exited 127"); - expect(err.message).toContain("Chromium not found"); - expect(err.name).toBe("BrowseClientError"); - }); -}); - -describe("resolveBrowseBin — sibling resolution from execPath (#2156)", () => { - // In a bun-compiled binary argv[0] is the raw invocation string (often - // relative), so the old dirname(argv[0]) built sibling candidates against - // the CWD. Under `bun test` the process path is the bun runtime, so these - // shapes are only reachable through the selfPath seam. - - test("sibling browse next to the install dir is found via selfPath", () => { - const base = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-sib-")); - try { - const distDir = path.join(base, "browse", "dist"); - fs.mkdirSync(distDir, { recursive: true }); - const sibling = path.join(distDir, "browse"); - fs.writeFileSync(sibling, "#!/bin/sh\nexit 0\n", { mode: 0o755 }); - const selfPath = path.join(base, "make-pdf", "dist", "pdf"); - // Receipts: pre-fix code ignores the selfPath seam entirely, so it can - // never produce this sibling — it either finds a global install (wrong - // value) or throws (PATH is empty). Red on v1.68.3.0 either way. - const resolved = resolveBrowseBin({ PATH: "" }, selfPath); - expect(resolved).toBe(path.resolve(path.join(base, "make-pdf"), "../browse/dist/browse")); - } finally { - fs.rmSync(base, { recursive: true, force: true }); - } - }); - - test("a decoy browse DIRECTORY near selfPath never shadows a real PATH binary", () => { - const base = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-decoy-")); - try { - // The ~/.claude/skills/browse alias-directory shape from #2156: a - // directory named exactly like the third sibling candidate. - fs.mkdirSync(path.join(base, "browse"), { recursive: true }); - const pathDir = path.join(base, "pathbin"); - fs.mkdirSync(pathDir, { recursive: true }); - const onPath = path.join(pathDir, "browse"); - fs.writeFileSync(onPath, "#!/bin/sh\nexit 0\n", { mode: 0o755 }); - const selfPath = path.join(base, "tools", "pdf"); - // os.homedir() ignores a $HOME override under bun, so the global-install - // probe may legitimately win on boxes with a real ~/.claude install. The - // invariant under test is narrower: the decoy DIRECTORY never wins, and - // whatever wins is a regular file. - const resolved = resolveBrowseBin({ PATH: pathDir }, selfPath); - expect(resolved).not.toBe(path.join(base, "browse")); - expect(fs.statSync(resolved).isFile()).toBe(true); - } finally { - fs.rmSync(base, { recursive: true, force: true }); - } - }); -}); diff --git a/make-pdf/test/cli-exit-codes.test.ts b/make-pdf/test/cli-exit-codes.test.ts new file mode 100644 index 000000000..97aae07a8 --- /dev/null +++ b/make-pdf/test/cli-exit-codes.test.ts @@ -0,0 +1,329 @@ +/** + * cli.ts error → exit code mapping, pinned through the REAL CLI process. + * + * exit 0 success / 1 bad args / 2 render error / 3 Paged.js timeout / 4 no browser + * + * `main()` is not exported and runs only under `import.meta.main`, so the + * catch block cannot be driven in-process. Each case spawns `bun cli.ts` + * instead, two ways: + * + * 1. Stubbed orchestrator. A `--preload` file registers a Bun runtime plugin + * whose onLoad swaps make-pdf/src/orchestrator.ts for a module whose + * generate()/preview() throw a chosen error class. The stub imports + * BrowserUnavailableError from the same types.ts cli.ts uses, so the + * `instanceof` check in the catch block is exercised for real. + * 2. No stubs. Filesystem errors that need no browser (missing input, output + * dir that does not exist), bad args, and fake `aside` / `browse` shell + * scripts reached via GSTACK_BROWSE_BIN and a scrubbed PATH. The children + * never see the real PATH, so no real browser is ever probed or launched. + * + * Exit 4 through an UNSTUBBED process is not forceable from inside this + * checkout: resolveBrowseBin() always finds /browse/dist/browse (a + * BROWSE_ROOTS entry computed from import.meta.dir), so the stubbed case (1) + * is the exit-4 pin here; make-pdf/test/asideClient.test.ts covers the + * renderFailure() classification that produces the error in the first place. + */ + +import { afterAll, beforeAll, describe, expect, test } from "bun:test"; +import * as fs from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; + +import { ExitCode } from "../src/types"; +import { NO_BROWSER, NO_BROWSER_HELP } from "../../lib/aside-render"; + +const ROOT = path.resolve(import.meta.dir, "..", ".."); +const CLI = path.join(ROOT, "make-pdf", "src", "cli.ts"); +const TYPES = path.join(ROOT, "make-pdf", "src", "types.ts"); +const isWin = process.platform === "win32"; + +let tmp: string; +/** PATH for children: nothing on it (no `aside`, no `browse`, no `pdftotext`). */ +let emptyBin: string; +/** PATH for children: only a fake `aside` that answers the probe but cannot run a script. */ +let fakeAsideBin: string; +/** Fake browse daemon CLIs (reached via GSTACK_BROWSE_BIN, never PATH). */ +let browseOk: string; +let browseRefusesNewtab: string; +let inputMd: string; + +beforeAll(() => { + tmp = fs.mkdtempSync(path.join(os.tmpdir(), "make-pdf-cli-exit-")); + emptyBin = path.join(tmp, "empty-bin"); + fs.mkdirSync(emptyBin); + fakeAsideBin = path.join(tmp, "fake-aside-bin"); + fs.mkdirSync(fakeAsideBin); + inputMd = path.join(tmp, "in.md"); + fs.writeFileSync(inputMd, "# Smoke\n\nOne paragraph is enough.\n", "utf8"); + + if (!isWin) { + // Answers `aside --version` and the ASIDE_READY probe like a live app, then + // fails every render script the way an Aside release that renamed its + // private CDP bridge would — the exact shape render() retries on browse. + writeScript(path.join(fakeAsideBin, "aside"), [ + 'case "$1" in', + ' --version) echo "aside 1.26.0-fake" ;;', + " repl)", + ' case "$2" in', + ' *ASIDE_READY*) echo "ASIDE_READY /fake/aside/session" ;;', + ' *) echo "ReferenceError: openTab is not defined" ;;', + " esac ;;", + "esac", + "exit 0", + ]); + browseOk = writeFakeBrowse("browse-ok", { pdf: true }); + browseRefusesNewtab = writeFakeBrowse("browse-refuses-newtab", { newtabFails: true }); + } +}); + +afterAll(() => { + fs.rmSync(tmp, { recursive: true, force: true }); +}); + +// ─── helpers ────────────────────────────────────────────────────────────────── + +function writeScript(file: string, body: string[]): string { + // Builtins only (case/echo/read/printf): the children run with PATH scrubbed. + fs.writeFileSync(file, ["#!/bin/sh", ...body, ""].join("\n"), { mode: 0o755 }); + return file; +} + +/** + * A stand-in for gstack's browse daemon CLI: `newtab --json` hands out a tab, + * `js` answers with `pageText`, and `pdf --from-file ` writes a fake + * PDF at the payload's `output` path (JSON parsed with parameter expansion). + */ +function writeFakeBrowse(name: string, opts: { pageText?: string; pdf?: boolean; newtabFails?: boolean }): string { + const body = ['case "$1" in']; + body.push(opts.newtabFails + ? ' newtab) echo "daemon refused: boom" >&2; exit 1 ;;' + : ` newtab) echo '{"tabId":7}' ;;`); + body.push(` js) echo '${opts.pageText ?? "browser-ok"}' ;;`); + if (opts.pdf) { + body.push( + " pdf)", + ' read -r payload < "$3"', + ' out="${payload#*\\"output\\":\\"}"', + ' out="${out%%\\"*}"', + " printf '%%PDF-1.4 fake\\n' > \"$out\"", + " ;;", + ); + } + body.push("esac", "exit 0"); + return writeScript(path.join(tmp, name), body); +} + +/** Hermetic child env: no real PATH, Aside skipped unless a test opts back in. */ +function childEnv(extra: Record = {}): Record { + const env: Record = { + PATH: emptyBin, + HOME: process.env.HOME ?? tmp, + TMPDIR: os.tmpdir(), + GSTACK_SKIP_ASIDE: "1", + NO_COLOR: "1", + }; + for (const [k, v] of Object.entries(extra)) { + if (v === undefined) delete env[k]; + else env[k] = v; + } + return env; +} + +function runCli(args: string[], opts: { preload?: string; env?: Record } = {}) { + const argv = [process.execPath, ...(opts.preload ? ["--preload", opts.preload] : []), CLI, ...args]; + const r = Bun.spawnSync(argv, { cwd: ROOT, env: opts.env ?? childEnv(), stdout: "pipe", stderr: "pipe", stdin: "ignore", timeout: 120_000 }); + return { code: r.exitCode, stdout: r.stdout.toString(), stderr: r.stderr.toString() }; +} + +const ORCHESTRATOR_FILTER = String.raw`make-pdf[/\\]src[/\\]orchestrator\.ts$`; + +/** + * Write a --preload file whose Bun plugin replaces the orchestrator module with + * one whose generate()/preview() `throw `. `throwExpr` may reference + * BrowserUnavailableError (imported from the real types.ts, so instanceof holds). + */ +function stubOrchestrator(name: string, throwExpr: string): string { + const module = [ + `import { BrowserUnavailableError } from ${JSON.stringify(TYPES)};`, + `export const OUTPUT_TMP_DIR = ${JSON.stringify(os.tmpdir())};`, + `export async function generate() { throw ${throwExpr}; }`, + `export async function preview() { throw ${throwExpr}; }`, + "", + ].join("\n"); + const preload = [ + "// Generated by make-pdf/test/cli-exit-codes.test.ts", + "Bun.plugin({", + ' name: "make-pdf-test-stub-orchestrator",', + " setup(build) {", + ` build.onLoad({ filter: new RegExp(${JSON.stringify(ORCHESTRATOR_FILTER)}) }, () => ({ loader: "ts", contents: ${JSON.stringify(module)} }));`, + " },", + "});", + "", + ].join("\n"); + const file = path.join(tmp, `stub-${name}.preload.ts`); + fs.writeFileSync(file, preload, "utf8"); + return file; +} + +// ─── 1. error class → exit code (orchestrator stubbed) ──────────────────────── + +describe("cli.ts maps the thrown error class to the exit code (orchestrator stubbed)", () => { + test("BrowserUnavailableError → exit 4, stderr is `$P: `, stdout stays empty", () => { + const msg = `${NO_BROWSER}: ${NO_BROWSER_HELP} (NEEDS_ASIDE: stubbed)`; + const r = runCli(["generate", inputMd], { + preload: stubOrchestrator("no-browser", `new BrowserUnavailableError(${JSON.stringify(msg)})`), + }); + expect(r.code).toBe(ExitCode.BrowserUnavailable); + expect(r.code).toBe(4); + expect(r.stderr.trim()).toBe(`$P: ${msg}`); + expect(r.stdout).toBe(""); + }); + + test("a plain Error → exit 2 (render error): message only, the stack only with --verbose", () => { + const preload = stubOrchestrator("render-error", `new Error("PDF render failed: render script did not finish")`); + const quiet = runCli(["generate", inputMd], { preload }); + expect(quiet.code).toBe(ExitCode.RenderError); + expect(quiet.code).toBe(2); + expect(quiet.stderr.trim()).toBe("$P: PDF render failed: render script did not finish"); + expect(quiet.stdout).toBe(""); + + const verbose = runCli(["generate", inputMd, "--verbose"], { preload }); + expect(verbose.code).toBe(ExitCode.RenderError); + const lines = verbose.stderr.trim().split("\n"); + expect(lines[0]).toBe("$P: PDF render failed: render script did not finish"); + expect(lines.length).toBeGreaterThan(1); // err.stack follows + expect(verbose.stderr).toMatch(/\bat\b/); + expect(verbose.stdout).toBe(""); + }); + + test("an ENOENT-coded error → exit 1 (bad args) with `file not found: `", () => { + const withPath = runCli(["generate", inputMd], { + preload: stubOrchestrator("enoent-path", + `Object.assign(new Error("ENOENT: no such file or directory, open '/x/in.md'"), { code: "ENOENT", errno: -2, syscall: "open", path: "/x/in.md" })`), + }); + expect(withPath.code).toBe(ExitCode.BadArgs); + expect(withPath.code).toBe(1); + expect(withPath.stderr.trim()).toBe("$P: file not found: /x/in.md"); + expect(withPath.stdout).toBe(""); + + // No `path` on the error: the message stands in. + const noPath = runCli(["generate", inputMd], { + preload: stubOrchestrator("enoent-nopath", `Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })`), + }); + expect(noPath.code).toBe(ExitCode.BadArgs); + expect(noPath.stderr.trim()).toBe("$P: file not found: ENOENT: no such file or directory"); + }); + + test("an error named PagedJsTimeout → exit 3", () => { + const r = runCli(["generate", inputMd], { + preload: stubOrchestrator("pagedjs", `Object.assign(new Error("Paged.js did not finish within 3000ms"), { name: "PagedJsTimeout" })`), + }); + expect(r.code).toBe(ExitCode.PagedJsTimeout); + expect(r.code).toBe(3); + expect(r.stderr.trim()).toBe("$P: Paged.js did not finish within 3000ms"); + expect(r.stdout).toBe(""); + }); + + test("a non-Error throw is still reported (String(err)) and exits 2", () => { + const r = runCli(["generate", inputMd], { preload: stubOrchestrator("string-throw", `"boom"`) }); + expect(r.code).toBe(ExitCode.RenderError); + expect(r.stderr.trim()).toBe("$P: boom"); + expect(r.stdout).toBe(""); + }); + + test("preview shares the same catch block: BrowserUnavailableError → exit 4", () => { + const r = runCli(["preview", inputMd], { + preload: stubOrchestrator("preview-no-browser", `new BrowserUnavailableError("${NO_BROWSER}: stubbed")`), + }); + expect(r.code).toBe(ExitCode.BrowserUnavailable); + expect(r.stderr.trim()).toBe(`$P: ${NO_BROWSER}: stubbed`); + expect(r.stdout).toBe(""); + }); +}); + +// ─── 2. real error paths that need no browser (no stubs) ────────────────────── + +describe("cli.ts exit codes end to end (no stubs, no browser touched)", () => { + test("a missing input is the orchestrator's own guard: exit 2 `input file not found` — NOT the ENOENT branch", () => { + // generate() checks existsSync before any fs call can throw ENOENT, so a + // typo'd input reads as a render error (2), not bad args (1). Pinned as-is. + const missing = path.join(tmp, "does-not-exist.md"); + const r = runCli(["generate", missing, "--quiet"]); + expect(r.code).toBe(ExitCode.RenderError); + expect(r.stderr.trim()).toBe(`$P: input file not found: ${missing}`); + expect(r.stdout).toBe(""); + }); + + test("a real ENOENT (output directory does not exist; --to html needs no browser) → exit 1 `file not found`", () => { + const out = path.join(tmp, "no-such-dir", "out.html"); + const r = runCli(["generate", inputMd, out, "--to", "html", "--quiet"]); + expect(r.code).toBe(ExitCode.BadArgs); + expect(r.stderr.trim()).toBe(`$P: file not found: ${out}`); + expect(r.stdout).toBe(""); + expect(fs.existsSync(out)).toBe(false); + }); + + test("bad args → exit 1: no input, unknown command (with usage), invalid --to", () => { + const noInput = runCli(["generate"]); + expect(noInput.code).toBe(ExitCode.BadArgs); + expect(noInput.stderr).toContain("$P generate: missing "); + expect(noInput.stdout).toBe(""); + + const unknown = runCli(["frobnicate"]); + expect(unknown.code).toBe(ExitCode.BadArgs); + expect(unknown.stderr).toContain("$P: unknown command: frobnicate"); + expect(unknown.stderr).toContain("Usage:"); + expect(unknown.stdout).toBe(""); + + const badTo = runCli(["generate", inputMd, "--to", "xml"]); + expect(badTo.code).toBe(ExitCode.BadArgs); + expect(badTo.stderr).toContain("invalid --to 'xml'"); + expect(badTo.stdout).toBe(""); + }); + + test("exit 0 paths: no arguments prints usage (stderr); version prints VERSION on stdout only", () => { + const usage = runCli([]); + expect(usage.code).toBe(ExitCode.Success); + expect(usage.stderr).toContain("Usage:"); + expect(usage.stdout).toBe(""); + + const version = runCli(["version"]); + expect(version.code).toBe(ExitCode.Success); + expect(version.stdout.trim()).toBe(fs.readFileSync(path.join(ROOT, "VERSION"), "utf8").trim()); + expect(version.stderr).toBe(""); + }); +}); + +// ─── 3. fake browsers: success contract, render error vs no browser, mid-run note ─ + +describe.skipIf(isWin)("cli.ts through fake browsers (GSTACK_BROWSE_BIN + a scrubbed PATH)", () => { + test("gstack's own browser renders: exit 0, stdout is the output path and nothing else, --quiet keeps stderr empty", () => { + const out = path.join(tmp, "steady", "out.pdf"); + const r = runCli(["generate", inputMd, out, "--quiet"], { env: childEnv({ GSTACK_BROWSE_BIN: browseOk }) }); + expect(r.code).toBe(ExitCode.Success); + expect(r.stdout).toBe(`${out}\n`); + expect(r.stderr).toBe(""); + expect(fs.readFileSync(out, "utf8")).toBe("%PDF-1.4 fake\n"); + }); + + test("a browser that is up but cannot render is a render error (exit 2), never `no browser` (exit 4)", () => { + const out = path.join(tmp, "refused", "out.pdf"); + const r = runCli(["generate", inputMd, out, "--quiet"], { env: childEnv({ GSTACK_BROWSE_BIN: browseRefusesNewtab }) }); + expect(r.code).toBe(ExitCode.RenderError); + expect(r.stderr.trim()).toBe("$P: PDF render failed: browse newtab failed: daemon refused: boom"); + expect(r.stderr).not.toContain(NO_BROWSER); + expect(r.stdout).toBe(""); + expect(fs.existsSync(out)).toBe(false); + }); + + test("Aside answers the probe but cannot run the script: the PDF comes from gstack's browser, stderr says so, exit 0", () => { + const out = path.join(tmp, "mid-run", "out.pdf"); + const r = runCli(["generate", inputMd, out, "--quiet"], { + env: childEnv({ PATH: fakeAsideBin, GSTACK_SKIP_ASIDE: undefined, GSTACK_BROWSE_BIN: browseOk }), + }); + expect(r.code).toBe(ExitCode.Success); + expect(r.stdout).toBe(`${out}\n`); + expect(r.stderr).toContain("Aside was unavailable mid-run; the PDF was rendered through gstack's own browser."); + expect(fs.readFileSync(out, "utf8")).toBe("%PDF-1.4 fake\n"); + }); +}); diff --git a/make-pdf/test/coverage-gaps.test.ts b/make-pdf/test/coverage-gaps.test.ts index 26586e8e5..78f220744 100644 --- a/make-pdf/test/coverage-gaps.test.ts +++ b/make-pdf/test/coverage-gaps.test.ts @@ -1,6 +1,6 @@ /** * Coverage-gap fills from the v1.58.0.0 ship audit — the branches the main - * suites couldn't reach without a live browse tab (mock-tab here), plus the + * suites couldn't reach without a live bundle page (mock runner here), plus the * pure-function stragglers (WebP probing, landscape geometry, bundle path * resolution, screen CSS). */ @@ -10,8 +10,8 @@ import * as os from "node:os"; import * as path from "node:path"; import { - RenderCallError, - type RenderTab, + type BundleCall, + type BundleResult, landscapeContentBox, rasterizeDiagramFigures, renderFenceSlots, @@ -21,19 +21,22 @@ import { import { imageDims } from "../src/image-size"; import { screenCss } from "../src/print-css"; -/** Duck-typed RenderTab: scripted call results + a loadBundle counter. */ -function mockTab(script: (fn: string, ...args: Array) => string) { +/** Scripted BundleRun: a throwing script call becomes an ERR result, plus counters. */ +function mockRun(script: (fn: string, ...args: unknown[]) => string) { const calls: string[] = []; - let reloads = 0; - const tab = { - call: (fn: string, ...args: Array) => { - calls.push(fn); - return script(fn, ...args); - }, - loadBundle: () => { reloads++; }, - close: () => {}, - } as unknown as RenderTab; - return { tab, calls, reloadCount: () => reloads }; + let batches = 0; + const run = async (batch: BundleCall[]): Promise => { + batches++; + return batch.map((c) => { + calls.push(c.fn); + try { + return { ok: true, value: script(c.fn, ...c.args) }; + } catch (e: any) { + return { ok: false, error: e.message }; + } + }); + }; + return { run, calls, batchCount: () => batches }; } const fence = (over: Partial<{ lang: string; source: string; ordinal: number }>) => ({ @@ -49,88 +52,99 @@ const fence = (over: Partial<{ lang: string; source: string; ordinal: number }>) // ─── renderFenceSlots: reset contract + excalidraw branches ─────────── -describe("renderFenceSlots (mock tab)", () => { - test("reset contract: a failure reloads the bundle and the NEXT fence still renders", () => { - const { tab, reloadCount } = mockTab((fn, ...args) => { - if (String(args[1] ?? "").includes("BROKEN")) throw new RenderCallError("Parse error on line 1"); +describe("renderFenceSlots (mock runner)", () => { + test("one batch for all fences: a failure is a diagnostic block and the NEXT fence still renders", async () => { + const { run, batchCount } = mockRun((fn, ...args) => { + if (String(args[1] ?? "").includes("BROKEN")) throw new Error("Parse error on line 1"); return ""; }); const warnings: string[] = []; - const slots = renderFenceSlots( + const slots = await renderFenceSlots( [ fence({ ordinal: 1 }), fence({ ordinal: 2, source: "BROKEN" }), fence({ ordinal: 3 }), ], - tab, + run, (m) => warnings.push(m), ); expect(slots.get("tok-1")).toContain(""); expect(slots.get("tok-2")).toContain("diagram-error"); + expect(slots.get("tok-2")).toContain("Parse error on line 1"); expect(slots.get("tok-3")).toContain(""); // post-failure fence rendered - expect(reloadCount()).toBe(1); // exactly one reset reload + expect(batchCount()).toBe(1); // one script for the whole document expect(warnings[0]).toContain("failed to render"); }); - test("excalidraw fence renders via __excalidrawToSvg", () => { - const { tab, calls } = mockTab(() => ""); - const slots = renderFenceSlots( + test("excalidraw fence renders via __excalidrawToSvg", async () => { + const { run, calls } = mockRun(() => ""); + const slots = await renderFenceSlots( [fence({ lang: "excalidraw", source: '{"type":"excalidraw","elements":[]}' })], - tab, + run, () => {}, ); expect(calls).toEqual(["__excalidrawToSvg"]); expect(slots.get("tok-1")).toContain(" { - const { tab, calls, reloadCount } = mockTab(() => ""); + test("invalid excalidraw JSON fails fast into a diagnostic WITHOUT a bundle call", async () => { + const { run, calls } = mockRun(() => ""); const warnings: string[] = []; - const slots = renderFenceSlots( + const slots = await renderFenceSlots( [fence({ lang: "excalidraw", source: "{not json" })], - tab, + run, (m) => warnings.push(m), ); expect(calls).toEqual([]); // JSON.parse threw before any bundle call expect(slots.get("tok-1")).toContain("diagram-error"); - expect(reloadCount()).toBe(1); expect(warnings).toHaveLength(1); }); }); // ─── rasterizeDiagramFigures: svg-data-URI + error fallbacks ────────── -describe("rasterizeDiagramFigures (mock tab)", () => { +describe("rasterizeDiagramFigures (mock runner)", () => { const figure = ``; - test("svg data-URI images rasterize to PNG", () => { + test("figures and svg data-URI images rasterize to PNG in ONE batch", async () => { const svgUri = `data:image/svg+xml;base64,${Buffer.from("").toString("base64")}`; - const { tab } = mockTab(() => "data:image/png;base64,AAAA"); - const out = rasterizeDiagramFigures(`v`, tab, 6.5, () => {}); - expect(out).toContain('src="data:image/png;base64,AAAA"'); + const { run, calls, batchCount } = mockRun((_fn, svg) => `data:image/png;base64,${String(svg).includes("viewBox") ? "FIG" : "IMG"}`); + const out = await rasterizeDiagramFigures(`${figure}v`, run, 6.5, () => {}); + expect(calls).toEqual(["__rasterize", "__rasterize"]); + expect(batchCount()).toBe(1); + expect(out).toContain('

flow

'); + expect(out).toContain('src="data:image/png;base64,IMG" alt="v"'); + expect(out).not.toContain("gstack-raster-slot"); }); - test("figure rasterization failure surfaces the SOURCE as text (never silent loss)", () => { + test("no rasterizable content → no bundle call at all", async () => { + const { run, batchCount } = mockRun(() => "x"); + const html = `

plain

`; + expect(await rasterizeDiagramFigures(html, run, 6.5, () => {})).toBe(html); + expect(batchCount()).toBe(0); + }); + + test("figure rasterization failure surfaces the SOURCE as text (never silent loss)", async () => { // Returning the figure unchanged would make the diagram vanish in DOCX // (the converter drops
/) — the failure must be visible. - const { tab } = mockTab(() => { throw new RenderCallError("tainted"); }); + const { run } = mockRun(() => { throw new Error("tainted"); }); const warnings: string[] = []; const srcFigure = figure.replace( '
B").toString("base64")}"`, ); - const out = rasterizeDiagramFigures(srcFigure, tab, 6.5, (m) => warnings.push(m)); + const out = await rasterizeDiagramFigures(srcFigure, run, 6.5, (m) => warnings.push(m)); expect(out).toContain("could not be rasterized"); expect(out).toContain("A --> B"); // source visible (escaped), not dropped expect(out).not.toContain(" { + test("svg data-URI rasterization failure keeps the original tag", async () => { const svgUri = `data:image/svg+xml;base64,${Buffer.from("").toString("base64")}`; - const { tab } = mockTab(() => { throw new RenderCallError("decode failed"); }); + const { run } = mockRun(() => { throw new Error("decode failed"); }); const tagIn = `
`; - const out = rasterizeDiagramFigures(tagIn, tab, 6.5, () => {}); + const out = await rasterizeDiagramFigures(tagIn, run, 6.5, () => {}); expect(out).toBe(tagIn); }); }); diff --git a/make-pdf/test/diagram-prepass.test.ts b/make-pdf/test/diagram-prepass.test.ts index eac3e645d..621173d1d 100644 --- a/make-pdf/test/diagram-prepass.test.ts +++ b/make-pdf/test/diagram-prepass.test.ts @@ -1,8 +1,9 @@ /** * Unit tests for the diagram pre-pass: fence extraction, info-string parsing, * slot substitution, diagnostic blocks, image inlining policy, and the - * byte-level image dimension prober. No browse daemon required — the tab - * factory returns null so downscale paths are exercised as no-ops. + * byte-level image dimension prober, and the bundle runner's script shape + * (render function injected). No live Aside required — `run: null` makes + * downscale paths no-ops. */ import { afterAll, describe, expect, test } from "bun:test"; import * as fs from "node:fs"; @@ -13,6 +14,7 @@ import zlib from "node:zlib"; import { StrictModeError, buildDiagnosticBlock, + bundleRunner, buildDiagramFigure, contentWidthInches, dimToInches, @@ -23,6 +25,7 @@ import { decodeFigureSource, } from "../src/diagram-prepass"; import { imageDims } from "../src/image-size"; +import type { RenderResult, RenderSpec } from "../../lib/aside-render"; // ─── fence extraction ───────────────────────────────────────────────── @@ -251,51 +254,51 @@ describe("inlineLocalImages", () => { strict: false, allowNetwork: false, contentWidthIn: 6.5, - getTab: () => null, + run: null, }; - test("local image becomes a data URI with probed dimensions", () => { + test("local image becomes a data URI with probed dimensions", async () => { const warnings: string[] = []; - const out = inlineLocalImages(`x`, { ...base, warn: (m) => warnings.push(m) }); + const out = await inlineLocalImages(`x`, { ...base, warn: (m) => warnings.push(m) }); expect(out).toContain("data:image/png;base64,"); expect(out).toContain('data-gstack-px-width="40"'); expect(out).toContain('data-gstack-px-height="20"'); expect(warnings).toHaveLength(0); }); - test("missing image → visible placeholder + warning", () => { + test("missing image → visible placeholder + warning", async () => { const warnings: string[] = []; - const out = inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); + const out = await inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); expect(out).toContain("image-missing"); expect(out).toContain("nope.png"); expect(warnings.length).toBe(1); }); - test("missing image + --strict → StrictModeError", () => { - expect(() => + test("missing image + --strict → StrictModeError", async () => { + await expect( inlineLocalImages(``, { ...base, strict: true, warn: () => {} }), - ).toThrow(StrictModeError); + ).rejects.toThrow(StrictModeError); }); - test("remote image is BLOCKED with a visible placeholder (offline posture)", () => { + test("remote image is BLOCKED with a visible placeholder (offline posture)", async () => { // Leaving the tag would make Chromium fetch it at print time anyway — // the offline posture must remove the src, not just warn about it. const warnings: string[] = []; const tag = ``; - const out = inlineLocalImages(tag, { ...base, warn: (m) => warnings.push(m) }); + const out = await inlineLocalImages(tag, { ...base, warn: (m) => warnings.push(m) }); expect(out).not.toContain("https://example.com/x.png\""); expect(out).toContain("remote image blocked"); expect(warnings[0]).toContain("offline"); }); - test("symlink escaping the input dir is caught by the realpath check", () => { + test("symlink escaping the input dir is caught by the realpath check", async () => { const outside = fs.mkdtempSync(path.join(os.tmpdir(), "prepass-symlink-")); fs.writeFileSync(path.join(outside, "secret.png"), tinyPng(5, 5)); const link = path.join(dir, "innocent.png"); try { fs.symlinkSync(path.join(outside, "secret.png"), link); const warnings: string[] = []; - inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); + await inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); expect(warnings.some((w) => w.includes("OUTSIDE the input directory"))).toBe(true); } finally { try { fs.unlinkSync(link); } catch { /* ignore */ } @@ -303,48 +306,48 @@ describe("inlineLocalImages", () => { } }); - test("special files and oversized images degrade to placeholders, never hang", () => { + test("special files and oversized images degrade to placeholders, never hang", async () => { // Directory masquerading as an image — not a regular file. fs.mkdirSync(path.join(dir, "dir.png"), { recursive: true }); const warnings: string[] = []; - const out = inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); + const out = await inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); expect(out).toContain("image-missing"); expect(warnings.some((w) => w.includes("not a regular file"))).toBe(true); }); - test("malformed percent-encoding degrades to missing-image, never throws", () => { + test("malformed percent-encoding degrades to missing-image, never throws", async () => { const warnings: string[] = []; - const out = inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); + const out = await inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); expect(out).toContain("image-missing"); }); - test("remote image + --allow-network passes silently", () => { + test("remote image + --allow-network passes silently", async () => { const warnings: string[] = []; const tag = ``; - const out = inlineLocalImages(tag, { ...base, allowNetwork: true, warn: (m) => warnings.push(m) }); + const out = await inlineLocalImages(tag, { ...base, allowNetwork: true, warn: (m) => warnings.push(m) }); expect(out).toBe(tag); expect(warnings).toHaveLength(0); }); - test("remote image + --strict → StrictModeError", () => { - expect(() => + test("remote image + --strict → StrictModeError", async () => { + await expect( inlineLocalImages(``, { ...base, strict: true, warn: () => {} }), - ).toThrow(StrictModeError); + ).rejects.toThrow(StrictModeError); }); - test("existing data URI gets dimension annotations only", () => { + test("existing data URI gets dimension annotations only", async () => { const uri = `data:image/png;base64,${tinyPng(33, 44).toString("base64")}`; - const out = inlineLocalImages(``, { ...base, warn: () => {} }); + const out = await inlineLocalImages(``, { ...base, warn: () => {} }); expect(out).toContain('data-gstack-px-width="33"'); expect(out).toContain('data-gstack-px-height="44"'); }); - test("out-of-tree image reads warn (never silent) and still inline", () => { + test("out-of-tree image reads warn (never silent) and still inline", async () => { const outside = fs.mkdtempSync(path.join(os.tmpdir(), "prepass-outside-")); fs.writeFileSync(path.join(outside, "ext.png"), tinyPng(10, 10)); try { const warnings: string[] = []; - const out = inlineLocalImages(``, { + const out = await inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m), }); expect(out).toContain("data:image/png;base64,"); @@ -354,26 +357,26 @@ describe("inlineLocalImages", () => { } }); - test("out-of-tree image + --strict → StrictModeError", () => { + test("out-of-tree image + --strict → StrictModeError", async () => { const outside = fs.mkdtempSync(path.join(os.tmpdir(), "prepass-outside-")); fs.writeFileSync(path.join(outside, "ext.png"), tinyPng(10, 10)); try { - expect(() => + await expect( inlineLocalImages(``, { ...base, strict: true, warn: () => {}, }), - ).toThrow(StrictModeError); + ).rejects.toThrow(StrictModeError); } finally { fs.rmSync(outside, { recursive: true, force: true }); } }); - test("Windows drive-letter src is treated as a local path, not a URL scheme", () => { + test("Windows drive-letter src is treated as a local path, not a URL scheme", async () => { // C:/x.png matches the single-letter-scheme regex — it must reach the // local-path branch (and the missing-file placeholder), never silently // pass through as an unknown URL. const warnings: string[] = []; - const out = inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); + const out = await inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); expect(out).toContain("image-missing"); // Two warnings: it's out-of-tree (resolved outside inputDir) AND missing. expect(warnings.some((w) => w.includes("image not found"))).toBe(true); @@ -393,11 +396,137 @@ describe("inlineLocalImages", () => { expect(markdown).toBe(md); }); - test("oversized raster without a tab inlines at full size with no downscale", () => { + test("oversized raster without a tab inlines at full size with no downscale", async () => { // 6000px-wide PNG header (body irrelevant for probing; file must exist) fs.writeFileSync(path.join(dir, "wide.png"), tinyPng(6000, 100)); const warnings: string[] = []; - const out = inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); + const out = await inlineLocalImages(``, { ...base, warn: (m) => warnings.push(m) }); expect(out).toContain('data-gstack-px-width="6000"'); }); + + test("oversized raster WITH a runner: one __downscaleRaster batch, token swapped for the scaled bytes", async () => { + fs.writeFileSync(path.join(dir, "wide2.png"), tinyPng(6000, 100)); + const calls: Array<{ fn: string; args: unknown[] }> = []; + const run = async (batch: Array<{ fn: string; args: unknown[] }>) => { + calls.push(...batch); + return batch.map(() => ({ ok: true as const, value: "data:image/png;base64,U0NBTEVE" })); + }; + const warnings: string[] = []; + // Same image twice: read/downscaled once, both tags rewritten. + const out = await inlineLocalImages(` b`, { ...base, run, warn: (m) => warnings.push(m) }); + expect(calls).toHaveLength(1); + expect(calls[0].fn).toBe("__downscaleRaster"); + expect(String(calls[0].args[0])).toStartWith("data:image/png;base64,"); + expect(calls[0].args[1]).toBe(1950); // 6.5in × 300dpi + expect(out.match(/data:image\/png;base64,U0NBTEVE/g)).toHaveLength(2); + expect(out).toContain('data-gstack-px-width="1950"'); + expect(out).not.toContain("gstack-downscale-slot"); + expect(warnings.some((w) => w.includes("downscaled wide2.png 6000px"))).toBe(true); + }); + + test("a failed downscale falls back to the full-size bytes with a warning", async () => { + fs.writeFileSync(path.join(dir, "wide3.png"), tinyPng(6000, 100)); + const run = async (batch: unknown[]) => batch.map(() => ({ ok: false as const, error: "image decode failed" })); + const warnings: string[] = []; + const out = await inlineLocalImages(``, { ...base, run, warn: (m) => warnings.push(m) }); + expect(out).toContain('data-gstack-px-width="6000"'); + expect(out).toContain("data:image/png;base64,"); + expect(out).not.toContain("gstack-downscale-slot"); + expect(warnings.some((w) => w.includes("downscale failed"))).toBe(true); + }); +}); + +// ─── bundle runner (script shape, injected render) ──────────────────── + +describe("bundleRunner", () => { + const bundle = path.join(os.tmpdir(), `fake-bundle-${process.pid}.html`); + fs.writeFileSync(bundle, "
ready
"); + afterAll(() => { try { fs.unlinkSync(bundle); } catch { /* best-effort */ } }); + + /** Fake Aside: asserts the spec shape and writes OK:/ERR: result files. */ + function fakeRender(script: (fn: string, args: unknown[]) => string) { + const specs: RenderSpec[] = []; + const render = async (spec: RenderSpec): Promise => { + specs.push(spec); + for (const step of spec.steps) { + if (step.kind !== "eval" || !step.out) throw new Error("expected eval steps with out files"); + const i = Number(step.expression.match(/call-(\d+)\.json/)![1]); + const fn = step.expression.match(/window\["(__\w+)"\]/)![1]; + const args = JSON.parse(fs.readFileSync(path.join(spec.serveRoot!, `call-${i}.json`), "utf8")); + let text: string; + try { text = "OK:" + script(fn, args); } catch (e: any) { text = "ERR:" + e.message; } + fs.writeFileSync(step.out, text); + } + return { ok: true, outputs: [], evals: {}, stdout: "" }; + }; + return { render, specs }; + } + + test("stages the bundle + one JSON args file per call in a served dir, waits for #done, reads results back", async () => { + const { render, specs } = fakeRender((fn, args) => `${fn}(${args.join(",")})`); + const run = bundleRunner({ bundlePath: bundle, render }); + const results = await run([ + { fn: "__renderMermaid", args: ["mermaid-fence-1", "graph LR"] }, + { fn: "__excalidrawToSvg", args: ["{}"] }, + ]); + expect(results).toEqual([ + { ok: true, value: "__renderMermaid(mermaid-fence-1,graph LR)" }, + { ok: true, value: "__excalidrawToSvg({})" }, + ]); + expect(specs).toHaveLength(1); + const spec = specs[0]; + expect(spec.waitFor).toEqual({ selector: "#done", timeoutMs: 20_000 }); + expect(path.dirname(spec.file)).toBe(spec.serveRoot); + expect(spec.steps).toHaveLength(2); + // Payload rides the served dir, not argv: the expression stays tiny. + for (const step of spec.steps) expect(step.kind === "eval" && step.expression.length < 300).toBe(true); + // Private per-script dir is cleaned up. + expect(fs.existsSync(spec.serveRoot!)).toBe(false); + }); + + test("a throwing call is an ERR result; the other calls in the script still succeed", async () => { + const { render } = fakeRender((_fn, args) => { + if (String(args[1]).includes("BROKEN")) throw new Error("Parse error on line 1"); + return ""; + }); + const run = bundleRunner({ bundlePath: bundle, render }); + const results = await run([ + { fn: "__renderMermaid", args: ["a", "ok"] }, + { fn: "__renderMermaid", args: ["b", "BROKEN"] }, + { fn: "__renderMermaid", args: ["c", "ok"] }, + ]); + expect(results.map((r) => r.ok)).toEqual([true, false, true]); + expect(results[1]).toEqual({ ok: false, error: "Parse error on line 1" }); + }); + + test("chunks at 40 calls per script (Aside's 120s script cap)", async () => { + const { render, specs } = fakeRender(() => "x"); + const run = bundleRunner({ bundlePath: bundle, render }); + const results = await run(Array.from({ length: 85 }, (_, i) => ({ fn: "__renderMermaid", args: [`m${i}`, "g"] }))); + expect(results).toHaveLength(85); + expect(specs.map((s) => s.steps.length)).toEqual([40, 40, 5]); + }); + + test("a whole-script failure fails every call in it with the renderer's message", async () => { + const render = async (): Promise => ({ ok: false, outputs: [], evals: {}, stdout: "", error: "aside repl did not run: spawn aside ENOENT" }); + const run = bundleRunner({ bundlePath: bundle, render }); + const results = await run([{ fn: "__renderMermaid", args: ["a", "g"] }, { fn: "__renderMermaid", args: ["b", "g"] }]); + expect(results).toHaveLength(2); + for (const r of results) { + expect(r.ok).toBe(false); + if (!r.ok) expect(r.error).toContain("diagram renderer: aside repl did not run"); + } + }); + + test("an unreadable bundle fails every call without touching Aside; zero calls run nothing", async () => { + let rendered = 0; + const render = async (): Promise => { rendered++; return { ok: true, outputs: [], evals: {}, stdout: "" }; }; + const run = bundleRunner({ bundlePath: "/nonexistent/diagram-render.html", render }); + expect(await run([])).toEqual([]); + const results = await run([{ fn: "__renderMermaid", args: ["a", "g"] }, { fn: "__renderMermaid", args: ["b", "g"] }]); + expect(results.map((r) => r.ok)).toEqual([false, false]); + if (!results[0].ok) expect(results[0].error).toContain("ENOENT"); + expect(rendered).toBe(0); + }); + }); diff --git a/make-pdf/test/e2e/browser-available.ts b/make-pdf/test/e2e/browser-available.ts new file mode 100644 index 000000000..4d28962c6 --- /dev/null +++ b/make-pdf/test/e2e/browser-available.ts @@ -0,0 +1,15 @@ +/** + * Gate prerequisite shared by the make-pdf e2e gates: SOME browser the + * compiled binary can print through — the Aside app (macOS dev machines) or + * gstack's own browse binary (what the Linux free-tests lane builds via + * build:gates). Mirrors lib/aside-render's pickEngine() order. + */ +import { resolveBrowseBin } from "../../../lib/aside-render"; +import { asideAvailable } from "../../../test/helpers/aside-available"; + +export const NO_BROWSER_REASON = + "no browser available (open the Aside app, or build gstack's own browser with `bun run build:gates`; GSTACK_SKIP_ASIDE=1 skips Aside)."; + +export function browserAvailable(): boolean { + return asideAvailable() || resolveBrowseBin() !== null; +} diff --git a/make-pdf/test/e2e/ci-prereqs.test.ts b/make-pdf/test/e2e/ci-prereqs.test.ts index e5618c8ff..69eef97ec 100644 --- a/make-pdf/test/e2e/ci-prereqs.test.ts +++ b/make-pdf/test/e2e/ci-prereqs.test.ts @@ -25,6 +25,10 @@ const EXPECT_BINARIES = process.env.GSTACK_EXPECT_BINARIES === "1"; describe("gate prerequisites (CI tripwire)", () => { test.skipIf(!EXPECT_BINARIES)("gate artifacts and tools exist when the lane promises them", () => { const missing: string[] = []; + // Aside itself is deliberately NOT asserted: CI runners have no Aside. The + // gates print through gstack's own browse binary there (the fallback in + // lib/aside-render), so THAT build artifact is promised alongside the + // make-pdf binary, the diagram bundle, and poppler. for (const rel of [ "make-pdf/dist/pdf", "browse/dist/browse", diff --git a/make-pdf/test/e2e/combined-gate.test.ts b/make-pdf/test/e2e/combined-gate.test.ts index fcaff4265..7f50aeb33 100644 --- a/make-pdf/test/e2e/combined-gate.test.ts +++ b/make-pdf/test/e2e/combined-gate.test.ts @@ -11,8 +11,8 @@ * user actually cares about — features interact, and the combined * extraction is what predicts production quality. * - * Gating: only runs when the compiled binary + browse + pdftotext are all - * available. Skipped cleanly otherwise (local dev without full install). + * Gating: only runs when the compiled binary + a browser (Aside or browse) + pdftotext + * are all available. Skipped cleanly otherwise (local dev, CI runners). */ import { describe, expect, test } from "bun:test"; @@ -22,16 +22,17 @@ import * as os from "node:os"; import * as path from "node:path"; import { copyPasteGate, resolvePdftotext } from "../../src/pdftotext"; +import { browserAvailable, NO_BROWSER_REASON } from "./browser-available"; const FIXTURE = path.resolve(__dirname, "../fixtures/combined-gate.md"); const EXPECTED = path.resolve(__dirname, "../fixtures/combined-gate.expected.txt"); const ROOT = path.resolve(__dirname, "../../.."); const PDF_BIN = path.join(ROOT, "make-pdf/dist/pdf"); -const BROWSE_BIN = path.join(ROOT, "browse/dist/browse"); function prerequisitesAvailable(): { ok: true } | { ok: false; reason: string } { if (!fs.existsSync(PDF_BIN)) return { ok: false, reason: `make-pdf binary missing (${PDF_BIN}). Run bun run build.` }; - if (!fs.existsSync(BROWSE_BIN)) return { ok: false, reason: `browse binary missing (${BROWSE_BIN}).` }; + // Aside (macOS) or gstack's own browse binary (what CI builds) — a skip only when neither exists. + if (!browserAvailable()) return { ok: false, reason: NO_BROWSER_REASON }; if (!fs.existsSync(FIXTURE)) return { ok: false, reason: `fixture missing (${FIXTURE}).` }; if (!fs.existsSync(EXPECTED)) return { ok: false, reason: `expected.txt missing (${EXPECTED}).` }; try { resolvePdftotext(); } catch (err: any) { return { ok: false, reason: err.message }; } @@ -43,15 +44,11 @@ describe("combined-features copy-paste gate", () => { test.skipIf(!avail.ok)("fixture PDF extracts cleanly through pdftotext", () => { if (!avail.ok) return; // satisfies the type checker - // Use /tmp directly (browse's validateOutputPath allows /private/tmp, - // which macOS resolves /tmp to). os.tmpdir() returns /var/folders/... - // which is outside the safe-dirs allowlist. - const outputPdf = `/tmp/make-pdf-combined-gate-${process.pid}.pdf`; + const outputPdf = path.join(os.tmpdir(), `make-pdf-combined-gate-${process.pid}.pdf`); try { execFileSync(PDF_BIN, ["generate", FIXTURE, outputPdf, "--quiet"], { encoding: "utf8", - timeout: 30_000, - env: { ...process.env, BROWSE_BIN }, + timeout: 60_000, stdio: ["ignore", "pipe", "pipe"], }); expect(fs.existsSync(outputPdf)).toBe(true); @@ -67,7 +64,7 @@ describe("combined-features copy-paste gate", () => { } finally { try { fs.unlinkSync(outputPdf); } catch { /* ignore */ } } - }, 30000); + }, 60000); if (!avail.ok) { test("prerequisites check", () => { diff --git a/make-pdf/test/e2e/diagram-gate.test.ts b/make-pdf/test/e2e/diagram-gate.test.ts index 37d7ffdf0..cf2426382 100644 --- a/make-pdf/test/e2e/diagram-gate.test.ts +++ b/make-pdf/test/e2e/diagram-gate.test.ts @@ -14,7 +14,8 @@ * colored pixels — text extraction can't fake that. * * Free-tier deterministic gate: runs under plain `bun test` when the compiled - * binaries + poppler are available; hard-fails in CI when missing. + * binary, a browser (Aside or the browse binary), and poppler are available; self-skips otherwise (ci-prereqs.test.ts + * is the CI tripwire for the build artifacts). */ import { describe, expect, test } from "bun:test"; @@ -23,11 +24,11 @@ import * as fs from "node:fs"; import * as path from "node:path"; import { resolvePopplerTool } from "../../src/pdftotext"; +import { browserAvailable, NO_BROWSER_REASON } from "./browser-available"; const FIXTURE = path.resolve(__dirname, "../fixtures/diagram-gate.md"); const ROOT = path.resolve(__dirname, "../../.."); const PDF_BIN = path.join(ROOT, "make-pdf/dist/pdf"); -const BROWSE_BIN = path.join(ROOT, "browse/dist/browse"); const BUNDLE = path.join(ROOT, "lib/diagram-render/dist/diagram-render.html"); const CHILD_TIMEOUT_MS = 60_000; @@ -38,7 +39,8 @@ const SATURATION_DELTA = 60; function prerequisitesAvailable(): { ok: true } | { ok: false; reason: string } { if (!fs.existsSync(PDF_BIN)) return { ok: false, reason: `make-pdf binary missing (${PDF_BIN}). Run bun run build.` }; - if (!fs.existsSync(BROWSE_BIN)) return { ok: false, reason: `browse binary missing (${BROWSE_BIN}).` }; + // Aside (macOS) or gstack's own browse binary (what CI builds) — a skip only when neither exists. + if (!browserAvailable()) return { ok: false, reason: NO_BROWSER_REASON }; if (!fs.existsSync(BUNDLE)) return { ok: false, reason: `diagram-render bundle missing (${BUNDLE}). Run bun run build:diagram-render.` }; if (!fs.existsSync(FIXTURE)) return { ok: false, reason: `fixture missing (${FIXTURE}).` }; if (!resolvePopplerTool("pdftotext")) return { ok: false, reason: "pdftotext not found (install poppler-utils)." }; @@ -80,7 +82,6 @@ describe("diagram render gate", () => { try { // No --quiet: stderr carries the downscale warning asserted below. const run = Bun.spawnSync([PDF_BIN, "generate", FIXTURE, outputPdf], { - env: { ...process.env, BROWSE_BIN }, stdout: "pipe", stderr: "pipe", timeout: 120_000, @@ -92,8 +93,8 @@ describe("diagram render gate", () => { expect(fs.existsSync(outputPdf)).toBe(true); // 0. Print-resolution downscale fired on the 4200px noise photo — this - // is the only live coverage of __downscaleRaster AND the chunked - // jsViaBuffer transport (the data URI exceeds the 100KB argv path). + // is the only live coverage of __downscaleRaster AND the served-dir + // payload transport (the data URI is far too big for argv). expect(stderr).toMatch(/downscaled huge-noise\.png 4200px → \d+px/); const pdftotext = resolvePopplerTool("pdftotext")!; @@ -101,8 +102,8 @@ describe("diagram render gate", () => { // 1. Vector text from BOTH diagrams (multi-fence + id-collision check). // The broken fence sits BETWEEN them in the fixture, so the second - // diagram rendering at all proves the reset contract (D6.2): the - // bundle page reloaded after the failure and kept working. + // diagram rendering at all proves a failed fence never poisons the + // batch (D6.2): the script kept going and the next render succeeded. for (const label of ["gatealphanode", "gatebetanode", "gategammanode", "gatedeltanode", "gateepsilonnode"]) { expect(text).toContain(label); } @@ -148,8 +149,7 @@ describe("diagram render gate", () => { try { execFileSync(PDF_BIN, ["generate", md, path.join(workDir, "out.pdf"), "--quiet", "--strict"], { encoding: "utf8", - env: { ...process.env, BROWSE_BIN }, - stdio: ["ignore", "pipe", "pipe"], + stdio: ["ignore", "pipe", "pipe"], timeout: CHILD_TIMEOUT_MS, }); } catch (err: any) { @@ -164,13 +164,9 @@ describe("diagram render gate", () => { }, 120000); if (!avail.ok) { - test("diagram gate prerequisites are present (hard-required in CI)", () => { - // Hard-require only where the binary is expected: the make-pdf gate - // workflow is macOS-only (path-filtered) and builds dist/pdf first. - // The Linux free lane deliberately doesn't build it — warn-skip there. - if (process.env.CI && process.platform === 'darwin') { - throw new Error(`diagram gate prerequisites missing in CI: ${avail.reason}`); - } + // A visible skip, never a failure: ci-prereqs.test.ts is the CI tripwire for + // the build artifacts + poppler this gate needs; CI prints through the browse binary it builds. + test("diagram gate prerequisites are present", () => { console.warn(`[skip] ${avail.reason}`); }); } diff --git a/make-pdf/test/e2e/emoji-gate.test.ts b/make-pdf/test/e2e/emoji-gate.test.ts index 794d25f8b..1dd546f13 100644 --- a/make-pdf/test/e2e/emoji-gate.test.ts +++ b/make-pdf/test/e2e/emoji-gate.test.ts @@ -22,8 +22,8 @@ * Note: pdfimages -list is intentionally NOT used — macOS embeds color emoji as * Type 3 fonts, so pdfimages lists nothing even on a correct render. * - * Gating: runs only when the compiled binary + browse + pdffonts + pdftoppm are - * available AND a color-emoji font is installed for Chromium to fall back to. + * Gating: runs only when the compiled binary + a browser (Aside or browse) + pdffonts + + * pdftoppm are available AND a color-emoji font is installed to fall back to. * In CI (process.env.CI set) missing prerequisites are a HARD FAILURE, not a * skip — CI is expected to install poppler-utils + fonts-noto-color-emoji, so a * silent skip there would let the tofu regression ship behind a green build. @@ -36,11 +36,11 @@ import * as fs from "node:fs"; import * as path from "node:path"; import { resolvePopplerTool } from "../../src/pdftotext"; +import { browserAvailable, NO_BROWSER_REASON } from "./browser-available"; const FIXTURE = path.resolve(__dirname, "../fixtures/emoji-gate.md"); const ROOT = path.resolve(__dirname, "../../.."); const PDF_BIN = path.join(ROOT, "make-pdf/dist/pdf"); -const BROWSE_BIN = path.join(ROOT, "browse/dist/browse"); // Saturated-pixel floor. Measured ~1650 at 100dpi for the fixture's color // emoji; a tofu render yields ~0. 200 sits well clear of both. @@ -50,9 +50,9 @@ const SATURATED_PIXEL_FLOOR = 200; const SATURATION_DELTA = 40; // Per-child wall-clock bound. Bun's test timeout doesn't reliably interrupt a // synchronous execFileSync, so each child gets its own ceiling — a wedged -// browser/poppler binary (or a hostile GSTACK_*_BIN override) fails instead of -// hanging the whole job. -const CHILD_TIMEOUT_MS = 25_000; +// browser session or poppler binary (or a hostile GSTACK_PDF*_BIN poppler override) +// fails instead of hanging the whole job. +const CHILD_TIMEOUT_MS = 60_000; /** Is a color-emoji font available for Chromium to fall back to? */ function emojiFontAvailable(): boolean { @@ -78,7 +78,8 @@ function emojiFontAvailable(): boolean { function prerequisitesAvailable(): { ok: true } | { ok: false; reason: string } { if (!fs.existsSync(PDF_BIN)) return { ok: false, reason: `make-pdf binary missing (${PDF_BIN}). Run bun run build.` }; - if (!fs.existsSync(BROWSE_BIN)) return { ok: false, reason: `browse binary missing (${BROWSE_BIN}).` }; + // Aside (macOS) or gstack's own browse binary (what CI builds) — a skip only when neither exists. + if (!browserAvailable()) return { ok: false, reason: NO_BROWSER_REASON }; if (!fs.existsSync(FIXTURE)) return { ok: false, reason: `fixture missing (${FIXTURE}).` }; if (!resolvePopplerTool("pdffonts")) return { ok: false, reason: "pdffonts not found (install poppler-utils)." }; if (!resolvePopplerTool("pdftoppm")) return { ok: false, reason: "pdftoppm not found (install poppler-utils)." }; @@ -142,9 +143,6 @@ describe("emoji render gate", () => { test.skipIf(!avail.ok)("emoji render as color glyphs, not tofu", () => { if (!avail.ok) return; // type narrowing - // Private temp dir under /tmp: browse's validateOutputPath only allows - // /tmp and /private/tmp (not os.tmpdir()'s /var/folders), and mkdtemp - // dodges the predictable-path symlink/collision risk. const workDir = fs.mkdtempSync("/tmp/make-pdf-emoji-gate-"); const outputPdf = path.join(workDir, "out.pdf"); const ppmPrefix = path.join(workDir, "page"); @@ -152,7 +150,6 @@ describe("emoji render gate", () => { try { execFileSync(PDF_BIN, ["generate", FIXTURE, outputPdf, "--quiet"], { encoding: "utf8", - env: { ...process.env, BROWSE_BIN }, stdio: ["ignore", "pipe", "pipe"], timeout: CHILD_TIMEOUT_MS, }); @@ -185,15 +182,9 @@ describe("emoji render gate", () => { }, 60000); if (!avail.ok) { - // In CI, missing prerequisites are a hard failure — a silent skip would let - // the Linux tofu regression ship behind a green build. Locally, just warn. - test("emoji gate prerequisites are present (hard-required in CI)", () => { - // Hard-require only where the binary is expected: the make-pdf gate - // workflow is macOS-only (path-filtered) and builds dist/pdf first. - // The Linux free lane deliberately doesn't build it — warn-skip there. - if (process.env.CI && process.platform === 'darwin') { - throw new Error(`emoji gate prerequisites missing in CI: ${avail.reason}`); - } + // A visible skip, never a failure: ci-prereqs.test.ts is the CI tripwire for + // the build artifacts + poppler this gate needs; CI prints through the browse binary it builds. + test("emoji gate prerequisites are present", () => { console.warn(`[skip] ${avail.reason}`); }); } diff --git a/make-pdf/test/e2e/format-gate.test.ts b/make-pdf/test/e2e/format-gate.test.ts index 37e41837b..82a2742fe 100644 --- a/make-pdf/test/e2e/format-gate.test.ts +++ b/make-pdf/test/e2e/format-gate.test.ts @@ -16,17 +16,19 @@ import { execFileSync } from "node:child_process"; import * as fs from "node:fs"; import * as path from "node:path"; +import { browserAvailable, NO_BROWSER_REASON } from "./browser-available"; + const FIXTURE = path.resolve(__dirname, "../fixtures/diagram-gate.md"); const ROOT = path.resolve(__dirname, "../../.."); const PDF_BIN = path.join(ROOT, "make-pdf/dist/pdf"); -const BROWSE_BIN = path.join(ROOT, "browse/dist/browse"); const BUNDLE = path.join(ROOT, "lib/diagram-render/dist/diagram-render.html"); const CHILD_TIMEOUT_MS = 60_000; function prerequisitesAvailable(): { ok: true } | { ok: false; reason: string } { if (!fs.existsSync(PDF_BIN)) return { ok: false, reason: `make-pdf binary missing (${PDF_BIN}). Run bun run build.` }; - if (!fs.existsSync(BROWSE_BIN)) return { ok: false, reason: `browse binary missing (${BROWSE_BIN}).` }; + // Aside (macOS) or gstack's own browse binary (what CI builds) — a skip only when neither exists. + if (!browserAvailable()) return { ok: false, reason: NO_BROWSER_REASON }; if (!fs.existsSync(BUNDLE)) return { ok: false, reason: `diagram-render bundle missing (${BUNDLE}).` }; if (!fs.existsSync(FIXTURE)) return { ok: false, reason: `fixture missing (${FIXTURE}).` }; if (!Bun.which("unzip")) return { ok: false, reason: "unzip not found (needed for docx zip checks)." }; @@ -36,7 +38,6 @@ function prerequisitesAvailable(): { ok: true } | { ok: false; reason: string } function generate(to: string, outputPath: string): void { execFileSync(PDF_BIN, ["generate", FIXTURE, outputPath, "--quiet", "--to", to], { encoding: "utf8", - env: { ...process.env, BROWSE_BIN }, stdio: ["ignore", "pipe", "pipe"], timeout: CHILD_TIMEOUT_MS, }); @@ -109,7 +110,6 @@ describe("output format gate", () => { try { execFileSync(PDF_BIN, ["generate", FIXTURE, "--to", "epub"], { encoding: "utf8", - env: { ...process.env, BROWSE_BIN }, stdio: ["ignore", "pipe", "pipe"], timeout: CHILD_TIMEOUT_MS, }); @@ -121,13 +121,9 @@ describe("output format gate", () => { }, 60000); if (!avail.ok) { - test("format gate prerequisites are present (hard-required in CI)", () => { - // Hard-require only where the binary is expected: the make-pdf gate - // workflow is macOS-only (path-filtered) and builds dist/pdf first. - // The Linux free lane deliberately doesn't build it — warn-skip there. - if (process.env.CI && process.platform === 'darwin') { - throw new Error(`format gate prerequisites missing in CI: ${avail.reason}`); - } + // A visible skip, never a failure: ci-prereqs.test.ts is the CI tripwire for + // the build artifacts + poppler this gate needs; CI prints through the browse binary it builds. + test("format gate prerequisites are present", () => { console.warn(`[skip] ${avail.reason}`); }); } diff --git a/make-pdf/test/e2e/landscape-gate.test.ts b/make-pdf/test/e2e/landscape-gate.test.ts index 7cc23c45a..b71fd2b4e 100644 --- a/make-pdf/test/e2e/landscape-gate.test.ts +++ b/make-pdf/test/e2e/landscape-gate.test.ts @@ -11,7 +11,7 @@ * - wide mermaid with page=portrait fence → MUST stay portrait (veto) * * Also runs the --toc combo: Paged.js isn't shipped in v1 (TOC renders - * without page numbers, browse falls through after 3s), so named-page + * without page numbers, the print falls through after 3s), so named-page * landscape must survive a --toc run unchanged. If Paged.js ever lands and * re-paginates, this is the test that catches the interaction. */ @@ -22,18 +22,19 @@ import * as fs from "node:fs"; import * as path from "node:path"; import { resolvePopplerTool } from "../../src/pdftotext"; +import { browserAvailable, NO_BROWSER_REASON } from "./browser-available"; const FIXTURE = path.resolve(__dirname, "../fixtures/landscape-gate.md"); const ROOT = path.resolve(__dirname, "../../.."); const PDF_BIN = path.join(ROOT, "make-pdf/dist/pdf"); -const BROWSE_BIN = path.join(ROOT, "browse/dist/browse"); const BUNDLE = path.join(ROOT, "lib/diagram-render/dist/diagram-render.html"); const CHILD_TIMEOUT_MS = 60_000; function prerequisitesAvailable(): { ok: true } | { ok: false; reason: string } { if (!fs.existsSync(PDF_BIN)) return { ok: false, reason: `make-pdf binary missing (${PDF_BIN}). Run bun run build.` }; - if (!fs.existsSync(BROWSE_BIN)) return { ok: false, reason: `browse binary missing (${BROWSE_BIN}).` }; + // Aside (macOS) or gstack's own browse binary (what CI builds) — a skip only when neither exists. + if (!browserAvailable()) return { ok: false, reason: NO_BROWSER_REASON }; if (!fs.existsSync(BUNDLE)) return { ok: false, reason: `diagram-render bundle missing (${BUNDLE}).` }; if (!fs.existsSync(FIXTURE)) return { ok: false, reason: `fixture missing (${FIXTURE}).` }; if (!resolvePopplerTool("pdfinfo")) return { ok: false, reason: "pdfinfo not found (install poppler-utils)." }; @@ -66,7 +67,6 @@ const isLandscape = (b: PageBox) => b.width > b.height; function generate(args: string[], outputPdf: string): void { execFileSync(PDF_BIN, ["generate", FIXTURE, outputPdf, "--quiet", ...args], { encoding: "utf8", - env: { ...process.env, BROWSE_BIN }, stdio: ["ignore", "pipe", "pipe"], timeout: CHILD_TIMEOUT_MS, }); @@ -141,13 +141,9 @@ describe("landscape promotion gate", () => { }, 120000); if (!avail.ok) { - test("landscape gate prerequisites are present (hard-required in CI)", () => { - // Hard-require only where the binary is expected: the make-pdf gate - // workflow is macOS-only (path-filtered) and builds dist/pdf first. - // The Linux free lane deliberately doesn't build it — warn-skip there. - if (process.env.CI && process.platform === 'darwin') { - throw new Error(`landscape gate prerequisites missing in CI: ${avail.reason}`); - } + // A visible skip, never a failure: ci-prereqs.test.ts is the CI tripwire for + // the build artifacts + poppler this gate needs; CI prints through the browse binary it builds. + test("landscape gate prerequisites are present", () => { console.warn(`[skip] ${avail.reason}`); }); } diff --git a/make-pdf/test/image-policy.test.ts b/make-pdf/test/image-policy.test.ts index 24881b8e4..869a6a0af 100644 --- a/make-pdf/test/image-policy.test.ts +++ b/make-pdf/test/image-policy.test.ts @@ -1,6 +1,6 @@ /** * Unit tests for the image width policy + conservative auto-landscape - * (image-policy.ts). Pure HTML-in/HTML-out — no browse daemon. + * (image-policy.ts). Pure HTML-in/HTML-out, no browser. * * The promotion heuristic is deliberately conservative (eng-review P4): * false negatives are cheap (add {page=landscape}), false positives feel diff --git a/make-pdf/test/pdftotext.test.ts b/make-pdf/test/pdftotext.test.ts index 259de001b..fdd20b803 100644 --- a/make-pdf/test/pdftotext.test.ts +++ b/make-pdf/test/pdftotext.test.ts @@ -147,6 +147,30 @@ describe("findExecutable (pdftotext.ts)", () => { test("returns null when no extension matches", () => { expect(findExecutable("/nonexistent/path/to/nothing")).toBeNull(); }); + + // access(X_OK) is TRUE for directories (they carry the traverse bit), so a bare + // X_OK probe once resolved a docs folder as "the binary". Only regular files count. + test("rejects a DIRECTORY even though it passes access(X_OK)", () => { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-dir-")); + try { + fs.accessSync(dir, fs.constants.X_OK); // precondition: the bare probe passes + expect(findExecutable(dir)).toBeNull(); + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } + }); + + test("rejects a directory that shadows the binary name", () => { + const base = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-shadow-")); + const shadow = path.join(base, "pdftotext"); + fs.mkdirSync(shadow); + fs.writeFileSync(path.join(shadow, "README.md"), "# not a binary\n"); + try { + expect(findExecutable(shadow)).toBeNull(); + } finally { + fs.rmSync(base, { recursive: true, force: true }); + } + }); }); describe("resolvePdftotext (override resolution, v1.24-aligned)", () => { diff --git a/make-pdf/test/render-offline-sanitize.test.ts b/make-pdf/test/render-offline-sanitize.test.ts index 609ac02a7..06524f7dc 100644 --- a/make-pdf/test/render-offline-sanitize.test.ts +++ b/make-pdf/test/render-offline-sanitize.test.ts @@ -1,6 +1,6 @@ /** * Offline-posture sanitizer tests — raw-HTML fetch vectors beyond - * (which the image inliner owns). No Playwright, no PDF generation. + * (which the image inliner owns). No browser, no PDF generation. * * Regression for: