Skip to content

Zed extension: Export Markdown to PDF via LSP code actions - #1

Merged
lecstor merged 5 commits into
mainfrom
clanker/4b01a1f7-zed-extension-export-markdown-to-pdf-via
Sep 30, 2026
Merged

lecstor merged 5 commits into
mainfrom
clanker/4b01a1f7-zed-extension-export-markdown-to-pdf-via

Conversation

@lecstor

@lecstor lecstor commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

What

The makesPDF extension for Zed: a WASM coordinator (src/lib.rs) that registers a Markdown language server, plus the @makespdf/zed-language-server sidecar (server/) whose code actions do the work. Zed has no command palette for extensions, so — like stemper-dev/zed-markdown-pdf — the user surface is the code-actions menu (cmd-. / ctrl-.).

Behaviour

  • Export to PDF (file:// docs only): POSTs the current buffer to /api/v1/md, writes <same dir>/<name>.pdf (overwriting), and shows the path plus page/render stats. The X-MakesPDF-Tip upsell is surfaced once per session.
  • Validate accessibility: POSTs to /api/v1/md/validate, shows No accessibility issues found. or N errors, M warnings plus the first issues, and logs each issue via window/logMessage.
  • Report problem: on any export error a window/showMessageRequest offers it; picking it POSTs the VS Code feedback.ts payload builder's fingerprints to /api/v1/feedback, including its 401-retry-without-auth rule. The message is built from the failure shape — the server's error text is never forwarded (a 500 body can quote document content).
  • Every request sends X-MakesPDF-Client: zed-extension/<package version> (recognised by MAK-136's inferClient → kind zed); Authorization: Bearer only when apiToken is set.
  • Settings: lsp.makespdf.settings with the same names/enums/defaults as the VS Code plugin (serviceUrl, apiToken, pageSize, fontFamily, fontSize, margins), forwarded via language_server_workspace_configuration and merged field-by-field over the defaults.

Repo layout

  • extension.toml / Cargo.toml / src/lib.rs: registers makespdf for Markdown, installs/updates the npm package with npm_install_package and runs it with node_binary_path.
  • server/: TypeScript, vscode-languageserver, bundled by esbuild to dist/server.js.
  • .github/workflows/ci.yml: cargo build --target wasm32-wasip2 --release --locked + server typecheck/unit/integration.
  • .github/workflows/release.yml: tag-triggered npm trusted publishing with provenance (first publish is MAK-138, human; nothing was published here).

Tests

cd server && npm test:

  • typecheck (tsc) clean
  • 29 unit tests: feedback payload rules, settings merge/coercion, API URL/headers/error classification, validate summary formatting, code actions, PDF path resolution
  • 4 stdio LSP integration tests against a local mock HTTP server (built dist/server.js, spawned over stdio):
    • codeAction on a file:// .md returns Export/Validate; executing Export writes <name>.pdf with the mock's bytes and sends X-MakesPDF-Client: zed-extension/<version>
    • no Authorization without a token, Bearer with one
    • Validate shows the summary and logs each issue (Error/Warning types)
    • a 500 export offers Report problem; picking it POSTs /api/v1/feedback with the fingerprints and none of the document text

cargo build --target wasm32-wasip2 --release --locked succeeds locally.

Adversarial review pass (commit 2644ecc)

  • Fix (high): the sidecar entry was returned as a relative path. The language server process runs with the worktree root as its working directory (lsp_store.rs → LanguageServer::new → current_dir), and Zed resolves only command.command against the extension directory — never arguments — so node could never find the npm package for a real user. The entry is now absolute (env::current_dir() join, the pattern the official html extension uses), with a clear error when the installed package lacks it, plus a MAKESPDF_ZED_SERVER_JS dev override so a local build can run before the package is published (the README's previous npm install ./server put the package where the extension's WASI preopen never looks).
  • Fix: fontSize accepts any finite number in 6..24 like the VS Code plugin and the server schema (a fractional size was silently reset to the default).
  • Fix: api.ts reuses feedback.ts's asErrorCode instead of keeping a second copy of the code-shaped rule.
  • Docs: README documents that local relative images are not embedded in v1 (the service fetches only http(s)/data: URLs) — deferred to MAK-144; CHANGELOG wording fixed.
  • Declined: offering "Report problem" for local writeFile failures — the synthesized feedback message is built from the failure shape, and a local disk error has no HTTP status (the report would read "(no response)" for a render that succeeded).

CI on 2644ecc: WASM extension ✅, Language server ✅.

Closes MAK-134 (implementation; review follows the task flow).

…roject root

The language server process runs with the worktree root as its working
directory (lsp_store.rs passes the worktree path to LanguageServer::new,
which sets current_dir), and Zed resolves only command.command against
the extension directory, never arguments. The relative npm entry path
therefore resolved inside the user's project for every user; join it with
the extension's WASI cwd (env::current_dir), as the official html
extension does, and fail clearly when the installed package lacks it.

Also from the adversarial pass:
- dev override MAKESPDF_ZED_SERVER_JS: the README's 'npm install ./server'
  at the repo root never reached the extension work dir Zed preopens, so
  a dev could not run the sidecar before it is published.
- fontSize accepts any finite number in 6..24, matching the VS Code
  plugin and the server schema (a fractional size was silently reset).
- api.ts reuses feedback.ts's asErrorCode instead of a duplicate rule.
- README documents that local relative images are not embedded in v1;
  CHANGELOG says every request sends the client header.
…etached commands

- apiToken is sent only when serviceUrl is makespdf.com, staging.makespdf.com
  or a loopback address. Zed deep-merges project settings, so a repo's
  .zed/settings.json that set only serviceUrl would otherwise receive the
  user's global token on the next export. A withheld token is reported once.
- Validate accessibility is offered only when a token can be sent:
  /api/v1/md/validate has no anonymous access, so without one it could only
  fail.
- workspace/executeCommand is answered at once and the command runs
  detached, so a slow render or an open "Report problem" prompt cannot run
  into Zed's 120 s request timeout. Each command logs "<command> finished",
  which the integration tests wait on.
- Failed validate calls are no longer worded as failed exports.
- lib.rs: a failed npm update falls back to the installed sidecar, and the
  registry is checked once per session instead of on every server start.
- Ignore the extension.wasm Zed builds for a dev install.
Official clients send their plain kind (vscode, obsidian, zed, cli,
gh-action) rather than a -plugin/-extension suffix, so the header value
matches the kind the server records.
@lecstor

lecstor commented Sep 30, 2026

Copy link
Copy Markdown
Member Author

by @lecstor's coding agent

Two commits after an independent review and a manual smoke test in Zed (the PR description predates them):

b854e3c

  • apiToken is only sent when serviceUrl is makespdf.com, staging.makespdf.com or a loopback address. Zed deep-merges project settings, so a repo's .zed/settings.json that set only serviceUrl would otherwise receive the user's global token. A withheld token is reported once.
  • Validate accessibility is offered only when a token can be sent (/api/v1/md/validate has no anonymous access).
  • workspace/executeCommand is answered at once and the command runs detached, so a slow render or an open Report problem prompt cannot hit Zed's 120 s request timeout.
  • Validate failures no longer say "export failed".
  • lib.rs: a failed npm update falls back to the installed sidecar, and the registry is checked once per session.

a7ea0ca

  • The client header is now X-MakesPDF-Client: zed/<version> (was zed-extension/<version>). Official clients are moving to plain kinds (vscode, obsidian, zed, cli, gh-action), with the server matching them exactly.

Smoke test in Zed (dev extension, local sidecar via MAKESPDF_ZED_SERVER_JS):

  • Code actions appear.
  • Anonymous Export writes a tagged one-page PDF and shows "PDF saved to ...".
  • Without a token, only Export is offered.
  • With a token in project settings, Validate appears live.
  • With serviceUrl pointed elsewhere, the token is withheld with a warning, and the failed export offers Report problem.

Not tested: Report problem submission (it would write a real feedback row), and the npm install path (the package is unpublished; see MAK-138).

@lecstor
lecstor merged commit dc31efd into main Sep 30, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant