feat(knowledge): preview a web app version before it is live (1.13.0)

[selcuk-lua]

What

Plugin side of Lua Apps D — preview (lua-core-services ADR 0019; CLI #5674/#5694/#5699, docs lua-dev-docs #200/#201). 1.13.0.

• lib/knowledge/web-apps.md §7a — lua apps preview (⏳ lua-cli 3.51.0+). The Workspace link on the preview's own origin <slug>--p-<id> under a Preview banner; any pushed version, disabled/unpublished apps too, reuse of an open preview. What it isolates, as verified in the runtime: Data writes go to a copy (copy-on-write, deleted at the end); emails and messages are recorded (--effects, logs:read); fetch fails with TEST_EGRESS_BLOCKED and is not recorded (session pool: egress record forced, no fixtures, no recorder); env() works; Products/Baskets/Orders/Templates/CDN/Jobs → test_session_tier_unsupported; Workflows.viewer → viewer_unavailable. Who (edit access, shared copy), --ttl (24 h, max 168 h), --close, PREVIEW_ENDED, WEB_APP_PREVIEW_NEEDS_AGENT_VERSION, exit codes. §9 gains "works in lua test webapp, errors in a preview".
• /lua-push webapp: on 3.51.0+ the success message offers the preview and runs it only if the user wants the link.
• /lua-deploy: mentions the preview for a version the user is unsure about — never reported as a deploy.
• scripts/lint-knowledge-commands.mjs: apps gains preview (and the existing delete).
• Version 1.13.0 everywhere the release lint checks (plugin + MCP metadata, X-Lua-Client, dist/server.js rebuilt — only the three version strings change), CHANGELOG, README, USER_GUIDE.

lua apps preview is in no permission list: Claude Code asks once before it runs (it opens a link others with edit access can use). PINNED_MIN_LUA_CLI unchanged; the section is marked 3.51.0+, like 1.11.0's 3.49.0 sections.

Checks

npm run lint ✓ (every step; knowledge lint run with LUA_CLI_SRC at lua-cli main + #5699, 1094 references). npm test 2072 passed; MCP npm test 149 passed.

Merge timing

Every merge cuts a release. The new text is version-gated (⏳ 3.51.0+), so it is safe before lua-cli 3.51.0 ships; merging after the release avoids a window where the knowledge names a command no published CLI has.

🤖 Generated with Claude Code

[richard-lua]

Code review — LOW risk

Documentation-and-metadata release (1.13.0): adds a new web-apps.md §7a describing lua apps preview, threads mentions into /lua-push and /lua-deploy, bumps every version string the release lint checks, and extends the command lint allowlist. No executable logic changes beyond version-string edits in the MCP server and api-client; the rebuilt dist/server.js only alters version strings. The change is version-gated (⏳ 3.51.0+) and PINNED_MIN_LUA_CLI is unchanged, so nothing breaks on older CLIs.

One minor advisory below; otherwise the change is consistent and low blast radius.

Minor

• plugins/lua-agent-builder/scripts/lint-knowledge-commands.mjs:104 — apps now lists preview and delete, but preview is also in neither RESERVED_TOKENS nor otherwise special, so the lint will only recognize lua apps preview once this allowlist entry ships; confirm the CLI's command-definitions.ts actually exposes apps preview/apps delete at the referenced versions, since this lint only passes because the allowlist was hand-edited (it does not verify these against CLI source when apps subcommands are mined from help text). If a published CLI in CI lacks them, the cross-repo check could diverge. No action needed if the CLI PRs (#5699) are confirmed merged before release.

Nothing else of concern. The security-sensitive files (command/permission markdown, MCP client) change only version strings and advisory prose; lua apps preview is correctly described as read-only/non-live and in no permission allowlist, so Claude Code prompts once before running it.

---

_{PR Risk Reviewer — automated senior review of f627ac3 · risk: low · confidence: 0.82}

[selcuk-lua]

On the minor note (apps allowlist in lint-knowledge-commands.mjs): confirmed, no change needed.

• The CLI exposes both on main: packages/lua-cli/src/cli/command-definitions.ts has appsGroup.command('preview [name]') (line 2153; lua-core-services #5674, #5694, #5699, all merged — last one c6fc9c13d) and appsGroup.command('delete <name>') (line 2183; #5103, released in 3.48.0).
• The allowlist only names sub-actions: the lint parses command-definitions.ts itself, and only SUB is hand-kept, the same way deploy gained webapp in 1.11.0. Locally it ran against lua-cli main (LUA_CLI_SRC): 1094 references check out.
• CI cannot diverge: this repo's CI has no lua-cli checkout, so the step exits 0 there ("Skipping knowledge-commands check: … not reachable"). It never compares against a published CLI. The ⏳ 3.51.0+ marks in §7a carry the version boundary for users.