refactor: simplify Prismic client and error handling internals by angeloashmore · Pull Request #225 · prismicio/cli

angeloashmore · 2026-07-14T23:27:31Z

Resolves:

Description

Internal cleanup of the CLI. No user-facing behavior change is intended.

Reorganizes the Prismic client internals, collapses the auth token/host accessors into one, and moves per-command error wrapping to a single request-level option so error messages live next to the endpoints that produce them.

Checklist

A comprehensive Linear ticket, providing sufficient context and details to facilitate the review of the PR, is linked to the PR.
If my changes require tests, I added them.
If my changes affect backward compatibility, it has been discussed.
If my changes require an update to the CONTRIBUTING.md guide, I updated it.

Preview

How to QA

Note

Medium Risk
Large import-path and error-handling refactor across most commands and API clients; mistakes could change CLI error text or break endpoints, though behavior is intended to stay the same.

Overview
Internal refactor of the Prismic CLI with no intended user-facing behavior change. HTTP clients move from src/clients/* to src/lib/prismic/clients/*, with shared helpers per service and request options like notFoundMessage / unknownErrorMessage so commands no longer wrap every API call in UnknownRequestError handlers.

Auth replaces separate getToken() / getHost() with getCredentials() returning both values; adapters and commands are updated accordingly.

Field and model logic moves out of src/models into src/fields.ts (CLI targets/sources, getNewFieldTarget, reorder helpers) and src/lib/prismic/models (addField, reorderField, typed errors). The CLI entrypoint maps those model errors to user messages. Field add commands drop post-add hint output; field-reorder uses exactlyOneOption for --before / --after.

Smaller cleanups: environments under lib/prismic, push inlines dashboard URL helpers removed from wroom, type-remove / slice-remove delete by id without re-fetching the model, and the old amplitude client file is removed from this tree.

^{Reviewed by Cursor Bugbot for commit 5ae52a8. Bugbot is set up for automated code reviews on this repo. Configure here.}

cursor

Cursor Bugbot has reviewed your changes using high effort and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit ff6c53c. Configure here.}

cursor · 2026-07-14T23:46:33Z

-	targetFields[fieldId] = field;
-	await saveModel();
+	addField(fields, fieldId, field);
+	await save();


Field add hints removed

Low Severity

Every prismic field add command now logs only Field added: … and no longer prints the follow-up guidance that getPostFieldAddMessage used to emit after a successful add, despite the PR stating no intended user-facing behavior change.

Additional Locations (1)

src/commands/field-add-text.ts#L35-L39

^{Reviewed by Cursor Bugbot for commit ff6c53c. Configure here.}

It's fine. It wasn't really useful.

Vaguely related, but have you considered adding evals for the CLI (in future work)? Since it's partly (majoritarily?) intended to be used by AI, it might be nice to catch potential regressions related to messaging/API usage programmatically.

I like @vercel/agent-eval DX in that regard (I think I already shared: https://github.com/vercel-labs/agent-eval), maybe you'll prefer something smaller/not remote sandboxed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Read response bodies once, add explicit json/body request options, and move not-found messaging into request(). Standardize every client on bare-base get*ServiceUrl builders and *ServiceRequest transport helpers, with repository scoping handled in the helpers. Remove the unused amplitude client and pass-through request helpers. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add an endpoint-level `unknownErrorMessage` request option so client functions declare their failure message once, instead of each command wrapping calls in a try/catch that converts `UnknownRequestError` into a `CommandError`. Removes 35 duplicated try/catch blocks across 26 command files. The message now lives on the endpoint, so it applies to every caller (including previously bare calls to shared endpoints like getProfile and the preview endpoints). The server response body is no longer appended. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

getToken() and getHost() were never called apart — 34 command, adapter, and index.ts sites called them as a pair — and each independently read credentials.json, so every command read the file from disk twice. Replace both with one getCredentials() that reads the file once and applies the same env-var precedence and default-host fallback. Call sites collapse from two awaited lines to one. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Drop the unused issues field and custom constructors from the config Invalid* error classes; nothing ever read them, so the read functions' catch blocks lose their ZodError branching. - updateRoute delegates straight to addRoute/removeRoute (the page branch duplicated the read and hasRoute check addRoute already does). - checkIsTypeScriptProject returns exists() directly. - Unexport symbols only referenced inside the module (findConfigPath, findSuggestedConfigPath, findLegacySliceMachineConfigPath, MissingLegacySliceMachineConfigError, the Route type). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

removeLocale inherited the client-level "Repository not found" default, so removing a non-existent locale reported the repository as missing. Override with "Locale not found: <code>", matching the resource-specific messages getCustomType/getSlice already use. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

deleteSlice/deleteCustomType already look up the resource by id and throw the same not-found error, so the explicit get before delete did no extra work. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Field add, edit, and reorder now surface duplicate and missing-field errors using the full dotted path the user passed instead of only the leaf segment. Update and remove requests for a specific type or slice now report a model-not-found message on 404 instead of the generic repository-not- found message. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

lihbr

LGTM, super rework!

Commands are much cleaner to read without try..catch or error throwing. I also like the new API used to manipulate models.

lihbr · 2026-07-15T07:06:54Z

-	targetFields[fieldId] = field;
-	await saveModel();
+	addField(fields, fieldId, field);
+	await save();


Vaguely related, but have you considered adding evals for the CLI (in future work)? Since it's partly (majoritarily?) intended to be used by AI, it might be nice to catch potential regressions related to messaging/API usage programmatically.

I like @vercel/agent-eval DX in that regard (I think I already shared: https://github.com/vercel-labs/agent-eval), maybe you'll prefer something smaller/not remote sandboxed.

lihbr · 2026-07-15T07:59:02Z

 			if (!UNTRACKED_COMMANDS.includes(command)) {
 				trackCommandEnd(command);
 			}


💡 #idea: This bit is repeated on every case (some also track the error itself), maybe there's a way to abstract it before/after all the cases?

angeloashmore marked this pull request as ready for review July 14, 2026 23:40

cursor Bot reviewed Jul 14, 2026

View reviewed changes

angeloashmore and others added 10 commits July 15, 2026 01:30

refactor: move Prismic clients under src/lib/prismic

91e2a9d

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

refactor: reorganize Prismic internals

3c0d1cb

style: apply formatter

0759d1a

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

refactor: drop redundant fetch in slice/type remove commands

2d70049

deleteSlice/deleteCustomType already look up the resource by id and throw the same not-found error, so the explicit get before delete did no extra work. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

angeloashmore force-pushed the aa/refactor branch from 64a6f2c to 5ae52a8 Compare July 15, 2026 01:37

lihbr reviewed Jul 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor: simplify Prismic client and error handling internals#225

refactor: simplify Prismic client and error handling internals#225
angeloashmore wants to merge 10 commits into
mainfrom
aa/refactor

angeloashmore commented Jul 14, 2026 •

edited by cursor Bot

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

cursor Bot Jul 14, 2026

Uh oh!

angeloashmore Jul 14, 2026

Uh oh!

lihbr Jul 15, 2026

Uh oh!

Uh oh!

lihbr left a comment

Uh oh!

lihbr Jul 15, 2026

Uh oh!

lihbr Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

angeloashmore commented Jul 14, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Preview

How to QA

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot Jul 14, 2026

Choose a reason for hiding this comment

Field add hints removed

Uh oh!

angeloashmore Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

lihbr Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lihbr left a comment

Choose a reason for hiding this comment

Uh oh!

lihbr Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

lihbr Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

angeloashmore commented Jul 14, 2026 •

edited by cursor Bot

Loading