From 886d8de20759ecccee8a0d2b9d3bb4769fddd2e2 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 4 Sep 2026 04:26:56 +0000 Subject: [PATCH 1/6] fix(preview): say that previews need a preview URL and a simulator URL Agents asked to set up previews for a deployed website added the production preview URL and stopped. The root help did not mention the slice simulator URL, so the agent did not know a second setting exists or that a deploy changes it. The root help has a PREVIEWS section with both commands. The preview row and the set-simulator row name the simulator URL. The set-simulator argument says a website URL is accepted, which the command already appends /slice-simulator to. The production preview eval now sets a local simulator URL in its fixture, the same as prismic init does. The eval measured "set the simulator URL" instead of "update" it, and preview list showed no stale value for the agent to notice. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01CgKyNmSz1frkfF8TqfL47F --- evals/configure-repositories.eval.ts | 2 ++ src/commands/index.ts | 10 +++++++++- src/commands/preview-set-simulator.ts | 2 +- src/commands/preview.ts | 2 +- test/index.test.ts | 1 + 5 files changed, 14 insertions(+), 3 deletions(-) diff --git a/evals/configure-repositories.eval.ts b/evals/configure-repositories.eval.ts index e7389067..7feda9ed 100644 --- a/evals/configure-repositories.eval.ts +++ b/evals/configure-repositories.eval.ts @@ -5,6 +5,7 @@ import { getPreviews, getRepository, getWebhooks, + setSimulatorUrl, } from "../test/prismic"; import { it, trials } from "./it"; @@ -22,6 +23,7 @@ it.for(trials)( "updates previews for production after a deploy", async (_, { agent, expect, repo, token, host }) => { await addPreview("http://localhost:3000/api/preview", "Development", { repo, token, host }); + await setSimulatorUrl("http://localhost:3000/slice-simulator", { repo, token, host }); const result = await agent( `We just deployed the site to https://example.com. Set up content previews for production.`, diff --git a/src/commands/index.ts b/src/commands/index.ts index 6b9548e4..e9156273 100644 --- a/src/commands/index.ts +++ b/src/commands/index.ts @@ -34,6 +34,14 @@ export default createCommandRouter({ it directly. There is no route command. Run \`prismic docs view routes\` for path keywords and route properties. `, + PREVIEWS: ` + Previews need two settings. After a deploy, set both: + prismic preview add https://example.com/api/preview + prismic preview set-simulator https://example.com + A repository can hold multiple preview URLs but only one simulator URL, + which the Page Builder loads live slice previews from. + Run \`prismic docs view previews\` for details. + `, }, commands: { init: { @@ -91,7 +99,7 @@ export default createCommandRouter({ }, preview: { handler: preview, - description: "Manage preview configurations", + description: "Manage preview and simulator URLs", }, token: { handler: token, diff --git a/src/commands/preview-set-simulator.ts b/src/commands/preview-set-simulator.ts index b5f1843d..0ec43de3 100644 --- a/src/commands/preview-set-simulator.ts +++ b/src/commands/preview-set-simulator.ts @@ -16,7 +16,7 @@ const config = { `, positionals: { url: { - description: "Simulator URL (e.g. https://example.com/slice-simulator)", + description: "Website or simulator URL (e.g. https://example.com)", required: true, }, }, diff --git a/src/commands/preview.ts b/src/commands/preview.ts index 56809928..52596663 100644 --- a/src/commands/preview.ts +++ b/src/commands/preview.ts @@ -22,7 +22,7 @@ export default createCommandRouter({ }, "set-simulator": { handler: previewSetSimulator, - description: "Set the slice simulator URL", + description: "Set the slice simulator URL for live previews", }, }, }); diff --git a/test/index.test.ts b/test/index.test.ts index 37c9bb88..fb843e7a 100644 --- a/test/index.test.ts +++ b/test/index.test.ts @@ -8,6 +8,7 @@ it("supports --help", async ({ expect, prismic }) => { expect(exitCode, stderr).toBe(0); expect(stdout).toContain("prismic [options]"); expect(stdout).toContain("ROUTES"); + expect(stdout).toContain("PREVIEWS"); expect(stdout).not.toContain("starter"); }); From 5ba866ad2a54ed90f82bc18e1f6f42bdbb917ef3 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 4 Sep 2026 04:44:51 +0000 Subject: [PATCH 2/6] refactor(preview): keep the two preview settings in one place The set-simulator command row said "for live previews", and the url argument said "Website or simulator URL". The root help now states both facts, and the set-simulator description already says that the command appends /slice-simulator to a website URL. The two command strings are back to their earlier text. The three evals that this branch affects still pass 5/5 each. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01CgKyNmSz1frkfF8TqfL47F --- src/commands/preview-set-simulator.ts | 2 +- src/commands/preview.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/commands/preview-set-simulator.ts b/src/commands/preview-set-simulator.ts index 0ec43de3..b5f1843d 100644 --- a/src/commands/preview-set-simulator.ts +++ b/src/commands/preview-set-simulator.ts @@ -16,7 +16,7 @@ const config = { `, positionals: { url: { - description: "Website or simulator URL (e.g. https://example.com)", + description: "Simulator URL (e.g. https://example.com/slice-simulator)", required: true, }, }, diff --git a/src/commands/preview.ts b/src/commands/preview.ts index 52596663..56809928 100644 --- a/src/commands/preview.ts +++ b/src/commands/preview.ts @@ -22,7 +22,7 @@ export default createCommandRouter({ }, "set-simulator": { handler: previewSetSimulator, - description: "Set the slice simulator URL for live previews", + description: "Set the slice simulator URL", }, }, }); From 4b1bd9029b778a2285063b60220ce0c7cb76205c Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 5 Sep 2026 00:41:53 +0000 Subject: [PATCH 3/6] refactor(preview): point to the docs instead of repeating them The PREVIEWS help held the commands, the purpose of the simulator URL, the count of each setting, and the deploy step. The previews docs page holds all of it too, so the same facts lived in two places and could drift apart. The help now names the two settings and sends the reader to the docs. Agents read the page: one of five trials read it when the help was long, and five of five read it now. This makes the CLI depend on the docs page. Merge and deploy prismicio/prismic-docs-v4#3951 before this branch, because the evals workflow reads the docs at prismic.io. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01CgKyNmSz1frkfF8TqfL47F --- src/commands/index.ts | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/commands/index.ts b/src/commands/index.ts index e9156273..73f74469 100644 --- a/src/commands/index.ts +++ b/src/commands/index.ts @@ -35,12 +35,8 @@ export default createCommandRouter({ Run \`prismic docs view routes\` for path keywords and route properties. `, PREVIEWS: ` - Previews need two settings. After a deploy, set both: - prismic preview add https://example.com/api/preview - prismic preview set-simulator https://example.com - A repository can hold multiple preview URLs but only one simulator URL, - which the Page Builder loads live slice previews from. - Run \`prismic docs view previews\` for details. + A website needs two settings, a preview URL and a slice simulator URL. + Run \`prismic docs view previews\` to learn how to set both. `, }, commands: { From 8d84aa5370ed88a968d5f95898f5bbc423f7d805 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 5 Sep 2026 00:45:28 +0000 Subject: [PATCH 4/6] Revert "refactor(preview): point to the docs instead of repeating them" This reverts commit 4b1bd9029b778a2285063b60220ce0c7cb76205c. --- src/commands/index.ts | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/commands/index.ts b/src/commands/index.ts index 73f74469..e9156273 100644 --- a/src/commands/index.ts +++ b/src/commands/index.ts @@ -35,8 +35,12 @@ export default createCommandRouter({ Run \`prismic docs view routes\` for path keywords and route properties. `, PREVIEWS: ` - A website needs two settings, a preview URL and a slice simulator URL. - Run \`prismic docs view previews\` to learn how to set both. + Previews need two settings. After a deploy, set both: + prismic preview add https://example.com/api/preview + prismic preview set-simulator https://example.com + A repository can hold multiple preview URLs but only one simulator URL, + which the Page Builder loads live slice previews from. + Run \`prismic docs view previews\` for details. `, }, commands: { From 814b6fb1357fe0af7b847cee2c8aaec5c0da365a Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 5 Sep 2026 02:04:19 +0000 Subject: [PATCH 5/6] fix(preview): name preview URLs in the preview command help The preview help called both settings "preview configurations". That name matches neither kind of preview that the docs describe, and it did not say that a repository holds preview URLs and a simulator URL. The command list now names the preview URL and the simulator URL. An EXAMPLES section shows both commands, in the form that other commands in this CLI use. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01CgKyNmSz1frkfF8TqfL47F --- src/commands/preview.ts | 15 +++++++++++---- test/preview.test.ts | 7 +++++++ 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/src/commands/preview.ts b/src/commands/preview.ts index 56809928..4d03508f 100644 --- a/src/commands/preview.ts +++ b/src/commands/preview.ts @@ -6,19 +6,26 @@ import previewSetSimulator from "./preview-set-simulator"; export default createCommandRouter({ name: "prismic preview", - description: "Manage preview configurations in a Prismic repository.", + description: "Manage previews in a Prismic repository.", + sections: { + EXAMPLES: ` + Set up previews after a deploy, using both settings: + prismic preview add https://example.com/api/preview + prismic preview set-simulator https://example.com + `, + }, commands: { add: { handler: previewAdd, - description: "Add a preview configuration", + description: "Add a preview URL", }, list: { handler: previewList, - description: "List preview configurations", + description: "List preview URLs and the simulator URL", }, remove: { handler: previewRemove, - description: "Remove a preview configuration", + description: "Remove a preview URL", }, "set-simulator": { handler: previewSetSimulator, diff --git a/test/preview.test.ts b/test/preview.test.ts index f5c03494..ba06d58d 100644 --- a/test/preview.test.ts +++ b/test/preview.test.ts @@ -11,3 +11,10 @@ it("supports --help", async ({ expect, prismic }) => { expect(exitCode, stderr).toBe(0); expect(stdout).toContain("prismic preview [options]"); }); + +it("shows how to set up both preview settings", async ({ expect, prismic }) => { + const { stdout, stderr, exitCode } = await prismic("preview", ["--help"]); + expect(exitCode, stderr).toBe(0); + expect(stdout).toContain("EXAMPLES"); + expect(stdout).toContain("prismic preview set-simulator"); +}); From a8e8d8c332798004d9fb0575ae8a7bb93d031480 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 5 Sep 2026 02:27:38 +0000 Subject: [PATCH 6/6] docs(help): say what previews are before how to set them up The PREVIEWS section started with the two settings. A reader who does not know what a preview is got instructions with no context. One sentence now says what previews do. The rest of the section is unchanged. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01CgKyNmSz1frkfF8TqfL47F --- src/commands/index.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/commands/index.ts b/src/commands/index.ts index e9156273..0cdee218 100644 --- a/src/commands/index.ts +++ b/src/commands/index.ts @@ -35,6 +35,7 @@ export default createCommandRouter({ Run \`prismic docs view routes\` for path keywords and route properties. `, PREVIEWS: ` + Writers use previews to see draft content before it is published. Previews need two settings. After a deploy, set both: prismic preview add https://example.com/api/preview prismic preview set-simulator https://example.com