@camox/cli 0.44.0 → 0.46.0

package/README.md

@@ -2,8 +2,8 @@
 
 ## Runtime lookup and monorepos
 
-Runtime-backed commands (`status`, `pages`, `blocks`, `layouts`, `env`, `files`,
-`preview`, and `logout`) accept `--cwd PATH`:
+Runtime-backed commands (`status`, `pages`, `blocks`, `layouts`, `locales`, `files`,
+`publish`, `discard`, `preview`, and `logout`) accept `--cwd PATH`:
 
 ```sh
 camox pages list --cwd apps/site
@@ -19,12 +19,51 @@ build once to generate its runtime file.
 Relative `--cwd` paths resolve against the shell's current directory. This option
 only affects runtime lookup: other paths, such as `--file ./hero.webp`, still
 resolve against the shell's current directory. Missing or non-directory paths fail
-instead of falling back to the shell's directory. Environment selection is unchanged:
-your development environment by default, with explicit `--production` where supported.
+instead of falling back to the shell's directory.
 
-## Authenticated local draft preview
+## Your development draft
 
-CLI login does not sign in a fresh browser. To verify draft writes without publishing:
+Every command reads and writes your development draft: it shows Live wherever
+it changes nothing, and publishing it lands on Live. No command takes a draft
+flag. Dev mode creates the draft on its first sync after `camox login`, so run
+your site locally once (e.g. `pnpm dev`) before using the CLI; until then,
+commands fail with `NO_DEVELOPMENT_DRAFT`.
+
+Agents in parallel worktrees share their developer's development draft, and
+publish or discard it together.
+
+## Publishing and discarding
+
+```sh
+camox status                    # whether your development draft exists, and how many changes it holds
+camox publish                   # what publishing would do, with a token
+camox publish --confirm TOKEN   # publish to Live
+camox discard                   # empty your development draft (asks first; --yes skips the question)
+```
+
+`camox publish` lists, in order:
+
+- **Blockers**, which prevent publishing until they're fixed in the draft. They
+  include definitions that differ from Live's: your local code changed a block,
+  layout or collection, and only a release (`camox release`) can ship it to Live.
+- **Conflicts**: content Live changed or deleted since your draft changed it,
+  with who published it and when. Publishing overwrites Live's version.
+- **Lost changes**, which publishing drops because what they belong to is gone.
+- **Warnings**: the same problems already on Live, which don't block.
+- **Changes**: everything your draft creates, changes or deletes.
+
+The token records the conflicts the list showed. `camox publish --confirm TOKEN`
+publishes the whole draft, which then stays open, emptied. If Live changed since
+the list was printed, nothing is published: the command prints the new list and
+token, fails with `CONFLICTS_CHANGED`, and you review it before confirming again.
+
+`camox discard` empties your development draft without touching Live. It asks
+for confirmation in a terminal; elsewhere it fails with `CONFIRMATION_REQUIRED`
+unless you pass `--yes`.
+
+## Authenticated local preview
+
+CLI login does not sign in a fresh browser. To verify writes in your development draft:
 
 ```sh
 camox preview --url http://localhost:3000/about --json
@@ -32,46 +71,87 @@ camox preview --cwd apps/site --url http://localhost:3000/about --json
 ```
 
 Open the returned `url` in the browser you use for verification. Wait for
-`[data-camox-preview="ready"]`, which identifies the project and developer
-environment after authenticated draft rendering. Errors appear as
+`[data-camox-preview="ready"]`, which identifies the project and your
+development draft after authenticated rendering. Errors appear as
 `[data-camox-preview="error"]`; expired or consumed links require a fresh command.
 The CLI and SDK must both support the preview handoff.
 
 The URL transfers your signed-in session: treat it as a credential, do not share
 or commit it, and use it within three minutes. Only HTTP(S) loopback URLs are
-accepted. The destination must match the CLI's project, backend, and developer
-environment. There is no production mode or automatic default-browser opening.
+accepted. The destination must match the CLI's project and backend. There is no
+automatic default-browser opening.
 The local dev server must already be running.
 
 ## Page SEO
 
-Use `pages get` to read metadata and `pages update` to edit it:
+Use `pages get` to read metadata and `pages set-seo` to edit it:
 
 ```sh
 camox pages get --path /about --json
-camox pages update --path /about --meta-title "About us" --meta-description "Meet the team."
-camox pages update --id 42 --meta-description ""
-camox pages update --id 42 --ai-seo on
-camox pages update --id 42 --ai-seo off
-camox pages get --path /about --live
-camox pages publish --path /about
+camox pages set-seo --path /about --meta-title "About us" --meta-description "Meet the team."
+# Page and block IDs are UUIDv7s; anything else is rejected.
+PAGE_ID=0199f1c2-7b3e-7a10-9c4d-5e6f7a8b9c0a
+camox pages set-seo --id "$PAGE_ID" --meta-description ""
+camox pages set-seo --id "$PAGE_ID" --ai-seo on
+camox pages set-seo --id "$PAGE_ID" --ai-seo off
 ```
 
-- Updates require exactly one of `--id` or `--path` and at least one update field.
-  Omitted fields are preserved; empty strings clear metadata.
-- Setting either metadata field disables automatic SEO for **both** fields.
-  Manual metadata cannot be combined with `--ai-seo on`.
-- `--ai-seo off` preserves current metadata. `--ai-seo on` schedules asynchronous
+- `set-seo` requires exactly one of `--id` or `--path` and at least one of
+  `--meta-title`, `--meta-description` or `--ai-seo`. An empty meta title blocks
+  publishing.
+- The meta title and description are one group: both generated or both manual.
+  Writing either field makes **both** manual, keeping the current value of the
+  other. Manual metadata cannot be combined with `--ai-seo on`.
+- `--ai-seo off` keeps current metadata as manual. `--ai-seo on` schedules asynchronous
   generation; the returned page contains current values, not necessarily generated
   values. Use `pages get` to inspect them later.
-- Changes affect the draft only. Publish separately to update live metadata.
-  `pages get --live` reads the published snapshot; without it, reads use the draft.
-- Commands support `--project SLUG`, `--production`, and `--json`, with the usual
-  development-environment default and structured JSON output/errors. `--production`
-  selects the environment; it does not publish the draft.
+- Changes are visible in your development draft right away, and reach Live
+  when you publish it.
+- Commands support `--project PROJECT` (a Project ID or Project Slug) and
+  `--json`, with structured JSON output/errors.
 
 See `camox pages update --help` for options and examples.
 
+## Shared navigation and footer content
+
+`pages get` shows page-owned blocks. To find layout-owned blocks:
+
+```sh
+camox layouts list
+camox layouts get --layout-id default --json
+BLOCK_ID=0199f1c2-7b3e-7a10-9c4d-5e6f7a8b9c0b
+camox blocks get --id "$BLOCK_ID"
+camox blocks edit --id "$BLOCK_ID" --content '{"title": "Updated title"}'
+```
+
+A layout is identified by the name its code gives it: the `layoutId` from
+`layouts list`, which is also a page's `layoutId`. `layouts get` returns
+`blocks` with IDs, types, layout slot, and content, along with ordered
+`layout.beforeBlockIds` and `layout.afterBlockIds`. Use a returned block `id`
+with `blocks get` and `blocks edit`, inspecting its schema and current content
+before editing.
+
+Commands accept `--cwd`, `--project`, and `--json`.
+Keep the project consistent when using discovered IDs.
+Editing a shared layout block changes it for all pages using that layout.
+
+## Locales
+
+```sh
+camox locales list
+camox locales add --tag de
+camox pages get --path /pricing --locale de
+camox locales remove --tag de
+camox locales set-default-tag --tag en-GB
+```
+
+Locales are added and removed in your development draft, like content. Camox
+translates the default locale into every other locale of the draft, when a
+locale is added and after every change to the default locale. Content commands
+(`pages`, `blocks`, `layouts get`) take `--locale <TAG>` and act on the default
+locale without it. Correcting the default locale's tag applies at once
+and is only possible while it's the only locale.
+
 ## Media
 
 Run `camox login` and start your project's dev server (or build once) so the CLI
@@ -88,24 +168,27 @@ camox files upload --url https://example.com/hero.webp --alt "Product screenshot
 camox files upload --url https://example.com/download --filename hero.webp --ai-metadata off
 
 # Inspect the returned ID and URL; use the ID in your block's media field.
+# File IDs are UUIDv7s; anything else is rejected.
 camox files list
-camox files get --id 123
+FILE_ID=0199f1c2-7b3e-7a10-9c4d-5e6f7a8b9c0d
+camox files get --id "$FILE_ID"
 
-camox files update --id 123 --filename hero.webp
-camox files update --id 123 --alt "Updated description"
-camox files update --id 123 --alt ""
-camox files update --id 123 --ai-metadata on
+camox files update --id "$FILE_ID" --filename hero.webp
+camox files update --id "$FILE_ID" --alt "Updated description"
+camox files update --id "$FILE_ID" --alt ""
+camox files update --id "$FILE_ID" --ai-metadata on
 
 # Replace the underlying file everywhere it is referenced, preserving its ID.
-camox files update --id 123 --file ./new-hero.webp
-camox files update --id 123 --url https://example.com/new-hero.webp
+camox files update --id "$FILE_ID" --file ./new-hero.webp
+camox files update --id "$FILE_ID" --url https://example.com/new-hero.webp
 
 # Replace content and override metadata together.
-camox files update --id 123 --file ./new-hero.webp --filename hero.webp --alt "New screenshot"
+camox files update --id "$FILE_ID" --file ./new-hero.webp --filename hero.webp --alt "New screenshot"
 ```
 
 - Upload requires exactly one of `--file` or `--url`. URLs are copied, not linked.
-- `--alt` disables AI metadata, including when its value is an empty string.
+- Alt text and filename are one group: both generated or both manual. `--alt`
+  (even an empty string) makes both manual, keeping the current filename.
   It cannot be combined with `--ai-metadata on`. Manual edits are protected from
   already-running AI jobs.
 - Without metadata flags, raster-image uploads use automatic metadata. Other
@@ -114,26 +197,26 @@ camox files update --id 123 --file ./new-hero.webp --filename hero.webp --alt "N
   generation has completed. Use `files get` to inspect the current record.
 - Update requires at least one of `--file`, `--url`, `--filename`, `--alt` or
   `--ai-metadata`. `--file` and `--url` are mutually exclusive; without either,
-  only metadata changes. Renaming alone preserves the file ID, URL and AI setting.
-- Replacing content preserves the file ID and all `_fileId` references in the
-  selected environment. The URL changes to avoid stale caches. Direct URLs in
-  stored block/repeatable-item content are migrated within that environment;
+  only metadata changes. Renaming alone preserves the file ID and URL and makes
+  both alt text and filename manual.
+- Replacing content preserves the file ID and all `_fileId` references in your
+  development draft. The URL changes to avoid stale caches. Direct URLs in
+  stored block/repeatable-item content are migrated within that draft;
   URLs hardcoded outside Camox cannot be rewritten.
 - Replacements preserve omitted alt text and AI settings. The filename defaults
   to the new source filename; `--filename` overrides it. Binary metadata and
   explicit metadata changes are saved together. If AI remains enabled, raster
   replacements schedule generation on the original file ID; other types skip
   generation. Disable AI to prevent future automatic renaming or alt changes.
-- Files are shared assets, not page drafts: replacing one affects every reference
-  to it in the selected environment. No page publish step is required.
+- Files are shared assets: replacing one affects every reference
+  to it in your development draft.
 - Failed replacements leave the original file unchanged and remove the unused
   uploaded binary. After a network timeout, use `files get --id ID` before retrying
   because the server may already have completed the operation.
-- All commands support `--project SLUG`, `--production`, and `--json`. The default
-  environment is `dev:<your-email>`, not production. IDs are scoped to the selected
-  project and environment.
+- All commands support `--project PROJECT` (a Project ID or Project Slug) and
+  `--json`. IDs are scoped to the selected project.
 - Uploads return the stored file record, including `id`, `url`, `mimeType`, `alt`,
-  and `aiMetadataEnabled`. Output is JSON; errors are structured JSON on stderr.
+  and `aiMetadata`. Output is JSON; errors are structured JSON on stderr.
 - Files are limited to 100 MiB. URL downloads allow at most five redirects and
   have a two-minute timeout; uploads have a separate two-minute timeout.
   Downloads stream through a temporary file that is removed afterward.

package/dist/api-DNIQC1ea.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { t as installLocalhostDns } from "./local-dns-DQIT1ucr.mjs";
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+//#region ../api-contract/src/drafts.ts
+/** Request header naming the draft a request reads and writes (ADR 0011). Absent means Live. */
+const DRAFT_HEADER = "x-camox-draft";
+/**
+* The `x-camox-draft` value naming the caller's own development draft in the project a request
+* acts on (ADR 0006, ADR 0011). Dev mode and the CLI always send it.
+*/
+const DEVELOPMENT_DRAFT = "development";
+/**
+* oRPC error code for a request naming the development draft before dev mode created it: the
+* first dev-mode sync after login does, so the site has to run locally once first.
+*/
+const NO_DEVELOPMENT_DRAFT_ERROR = "NO_DEVELOPMENT_DRAFT";
+/**
+* The oRPC error code a request naming an ended draft fails with. Its `data` is an `EndedDraft`,
+* so a page can render Live and say who published or discarded the draft.
+*/
+const DRAFT_ENDED_ERROR_CODE = "DRAFT_ENDED";
+/**
+* Why the publish tool published nothing of a draft with changes, and returned a fresh preview to
+* review again, by the error code of each: Live changed since the preview, the draft has blockers,
+* or translations are still running.
+*/
+const NOT_PUBLISHED_CODES = {
+	conflictsChanged: "CONFLICTS_CHANGED",
+	blocked: "PUBLISH_BLOCKED",
+	translating: "TRANSLATIONS_PENDING"
+};
+//#endregion
+//#region src/lib/api.ts
+const CAMOX_API_URL = process.env.CAMOX_API_URL || "https://api.camox.dev";
+installLocalhostDns(new URL(CAMOX_API_URL).hostname);
+function authHeaders(token) {
+	return {
+		Authorization: `Bearer ${token}`,
+		"Content-Type": "application/json"
+	};
+}
+/**
+* Headers of every request a command sends about a project: the CLI works only in the
+* caller's development draft (ADR 0010).
+*/
+function developmentDraftHeaders(token, disableTelemetry) {
+	const headers = {
+		Authorization: `Bearer ${token}`,
+		"x-camox-client": "cli",
+		[DRAFT_HEADER]: DEVELOPMENT_DRAFT
+	};
+	if (disableTelemetry) headers["x-camox-telemetry-disabled"] = "1";
+	return headers;
+}
+function createRpcClient(token, apiUrl = CAMOX_API_URL, options = {}) {
+	installLocalhostDns(new URL(apiUrl).hostname);
+	const headers = options.developmentDraft ? developmentDraftHeaders(token, options.disableTelemetry) : {
+		Authorization: `Bearer ${token}`,
+		"x-camox-client": "cli"
+	};
+	const link = new RPCLink({
+		url: `${apiUrl}/rpc`,
+		headers
+	});
+	return createORPCClient(link);
+}
+async function verifySession(token) {
+	return (await fetch(`${CAMOX_API_URL}/api/auth/get-session`, {
+		method: "GET",
+		headers: authHeaders(token)
+	})).ok;
+}
+const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+* Load a project named by its Project ID or its Project Slug. A UUID-shaped name is a
+* Project ID, which the API validates; anything else is a slug.
+*/
+async function getProject(token, project, apiUrl) {
+	const client = createRpcClient(token, apiUrl, { developmentDraft: true });
+	return UUID_SHAPE.test(project) ? client.projects.getByUuid({ projectUuid: project }) : client.projects.getBySlug({ slug: project });
+}
+/**
+* The caller's development draft in a project, summarized: it fails with
+* `NO_DEVELOPMENT_DRAFT` until dev mode created it.
+*/
+async function getDevelopmentDraft(params) {
+	return createRpcClient(params.token, params.apiUrl, {
+		developmentDraft: true,
+		disableTelemetry: params.disableTelemetry
+	}).drafts.get({ projectId: params.projectId });
+}
+async function callTool(params) {
+	return await createRpcClient(params.token, params.apiUrl, {
+		developmentDraft: true,
+		disableTelemetry: params.disableTelemetry
+	}).agent.callTool({
+		projectId: params.projectId,
+		name: params.name,
+		arguments: params.args
+	});
+}
+//#endregion
+export { verifySession as a, NOT_PUBLISHED_CODES as c, getProject as i, NO_DEVELOPMENT_DRAFT_ERROR as l, developmentDraftHeaders as n, DEVELOPMENT_DRAFT as o, getDevelopmentDraft as r, DRAFT_ENDED_ERROR_CODE as s, callTool as t };

package/dist/api-DeE66CPa.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export { a as verifySession } from "./api-DNIQC1ea.mjs";

package/dist/{auth-core-4Jdf5q-u.mjs → auth-core-xLeorUUV.mjs}

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { t as installLocalhostDns } from "./local-dns-DQIT1ucr.mjs";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -21,6 +22,38 @@ function localAuthFile(cwd) {
 function normalizeUrl(url) {
 	return url.replace(/\/+$/, "");
 }
+function isLoopbackUrl(url) {
+	return ["http:", "https:"].includes(url.protocol) && ([
+		"localhost",
+		"127.0.0.1",
+		"[::1]"
+	].includes(url.hostname) || url.hostname.endsWith(".localhost")) && !url.username && !url.password;
+}
+async function createPreviewSignInUrl(destination, target, authToken, signal = AbortSignal.timeout(15e3)) {
+	const url = new URL(destination);
+	if (!isLoopbackUrl(url)) throw new Error("Preview requires an http(s) loopback URL without credentials.");
+	installLocalhostDns(new URL(target.apiUrl).hostname);
+	url.searchParams.set("camox-preview", JSON.stringify({
+		...target,
+		apiUrl: normalizeUrl(target.apiUrl)
+	}));
+	const response = await fetch(`${normalizeUrl(target.apiUrl)}/api/auth/cross-domain/studio-authorize`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${authToken}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({ callback: url.href }),
+		redirect: "error",
+		signal
+	});
+	if (!response.ok) throw new Error(`Could not create preview sign-in (${response.status}). Check your session with camox login.`);
+	const data = await response.json();
+	const token = typeof data.url === "string" ? URL.parse(data.url)?.searchParams.get("ott") : null;
+	if (!token) throw new Error("Authentication backend returned no one-time token.");
+	url.searchParams.set("ott", token);
+	return url.href;
+}
 function readAllTokens(file) {
 	if (!fs.existsSync(file)) return {};
 	const entries = JSON.parse(fs.readFileSync(file, "utf-8"));
@@ -65,6 +98,7 @@ function removeAuthTokenForUrl(authenticationUrl, cwd = process.cwd()) {
 	fs.rmSync(file, { force: true });
 }
 async function verifyOneTimeToken(apiUrl, token) {
+	installLocalhostDns(new URL(apiUrl).hostname);
 	const res = await fetch(`${normalizeUrl(apiUrl)}/api/auth/one-time-token/verify`, {
 		method: "POST",
 		headers: { "Content-Type": "application/json" },
@@ -83,4 +117,4 @@ async function verifyOneTimeToken(apiUrl, token) {
 	};
 }
 //#endregion
-export { writeAuthTokenForUrl as a, verifyOneTimeToken as i, readAuthTokenForUrl as n, removeAuthTokenForUrl as r, normalizeUrl as t };
+export { removeAuthTokenForUrl as a, readAuthTokenForUrl as i, isLoopbackUrl as n, verifyOneTimeToken as o, normalizeUrl as r, writeAuthTokenForUrl as s, createPreviewSignInUrl as t };

package/dist/index.d.mts

@@ -1,2 +1,2 @@
 
-export { };
+export {}