feat: introduce pages v1

Merged
SA
3mo ago
+14557-60

Supersedes #6731, which cannot be merged from its fork: pushing the CI fix to harshithmullapudi/superset needs LFS upload rights we don't have, and main's ruleset only allows an admin bypass through a pull request, so the fix can't go straight to main either.

Same commits, same authorship — all the Pages work here is @harshithmullapudi's, cherry-picked verbatim from feat/pages at def4637e6. One commit added on top to get CI green.

What's on top

fix(skills): give the page skill Codex metadata and drop em dashes

bundled-skills.test.ts enforces two rules on every bundled skill, and the page skill met neither, which was the sole cause of the red Test job on #6731:

  • has Codex interface metadata — every skill needs agents/openai.yaml; the page skill shipped without one. Added, matching the ten existing files.
  • avoids em dashes (repo prose rule) — SKILL.md had 16. Rewritten in house style with semicolons, colons and sentence splits; no other bundled skill substitutes a hyphen, so neither does this one.

One of those em dashes sat inside a blockquote reproducing the publish command's unlinked-workspace notice, so packages/cli/src/commands/pages/publish/command.ts moves with it and the quote stays true to the output.

Verification

  • bun test packages/agent-setup/src/bundled-skills.test.ts — 78 pass, 0 fail
  • bun run lint — clean across 6299 files
  • Full bun run test — green apart from two known-unrelated items: the 5 node-pty spawn-helper tests, which fail identically on origin/main in a worktree without install:deps, and one workspace-fs watcher test that timed out under parallel load and passes 101/101 on re-run

Note

The review threads on #6731 are still the substantive record and several remain open, in particular the forgeable author_kind on pageComment.reply, the unused agent_activated_at columns, and the (workspace_id, entry_path) collision that silently mints orphan pages. Those are tracked as follow-ups, not blockers.

Summary by cubic

Introduce Pages v1: publish and view self-contained HTML pages with versions and inline comments across web, desktop, CLI, and MCP, gated by the pages feature flag. Previously there was no page concept; now users can publish HTML to a shareable URL, control visibility, and hand off comment threads to agents.

  • Desktop: Pages tab and a page pane (flag-gated); Electron superset-page:// protocol with strict CSP to render ephemeral HTML registered via a new pageContent TRPC router; unavailable panes are dropped when the flag is off.

  • Web: route /page/[slug] renders the current version with comments and visibility controls; loading/error/not-found and wrong-organization experiences; server-side PostHog client for flag checks; content downloads are timed-out and logged.

  • CLI: pages commands (list, get, versions, pull, publish) and pages comments (list, reply, resolve); path resolution is canonicalized to prevent symlink escapes; pull streams HTML to stdout with a timeout.

  • MCP: tools pages_list|get|versions|pull|publish and pages_comments_list|reply|resolve; defineTool accepts a z.object for cross-field rules; optionalish normalizes nulls; calls carry agentCaller metadata to gate agent-only actions.

  • Backend/schema: page, version, and comment tables and enums; relations wired; TRPC roots page and pageComment; shared adds FEATURE_FLAGS.PAGES, slug utilities, and content-type constants; docs updated to cover Pages in MCP.

  • Security: desktop rendering runs in a sandboxed scheme with default-src 'none', inline-only scripts/styles, no storage access; asset paths are canonicalized to avoid symlink bypass.

  • Misc: extracted a server-side PostHog client (posthog-node) for flag checks; 404 screens updated on web and desktop; dev seed creates the superset-cli OAuth client and redirect URIs; CLI help improves alias formatting; tests move page-comment helpers out of the TRPC router to avoid the DB import graph (no behavior change).

  • Rollout and migration

    • Run DB migration 0092.
    • Leave the feature off by default; enable with the PostHog flag pages (FEATURE_FLAGS.PAGES) per org.
    • For local dev, re-run the dev seed to create the superset-cli OAuth client and redirect URIs; restart desktop to register the superset-page:// protocol.

Summary by CodeRabbit

  • New Features
    • Added Pages for publishing, viewing, versioning, and managing self-contained HTML content.
    • Added workspace sidebar and pane support for opening published pages.
    • Added visibility controls and interactive comments, including replies, editing, resolution, and agent handoff.
    • Added CLI and MCP capabilities for page publishing, retrieval, version history, content pulling, and comment management.
    • Added loading, error, not-found, and cross-workspace access experiences.
  • Documentation
    • Added Pages guidance for MCP and Superset skills.
  • Style
    • Improved not-found experiences with branded 404 graphics and navigation.