@camox/cli 0.58.0 → 0.59.0

package/README.md

@@ -1,229 +1,71 @@
 # Camox CLI
 
-## Runtime lookup and monorepos
-
-Runtime-backed commands (`status`, `pages`, `blocks`, `layouts`, `locales`, `files`,
-`publish`, `delete`, `preview`, and `logout`) accept `--cwd PATH`:
-
-```sh
-camox pages list --cwd apps/site
-camox status --cwd apps/site
-camox files upload --cwd apps/site --file ./hero.webp --alt "Product screenshot"
-```
-
-The CLI searches for `node_modules/.camox/runtime.json` starting in that directory
-and walking upward. Without `--cwd`, lookup starts in the shell's current directory.
-There is no workspace or child-directory discovery. Run the app's dev server or
-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.
-
-## Your development draft
-
-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 delete it together.
-
-## Publishing and deleting
-
-```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 delete                   # 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 delete` 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:
+The CLI does what the hosted platform needs from a terminal. Projects are created
+from the dashboard at [camox.ai](https://camox.ai), and their content is edited
+in the studio.
 
 ```sh
-camox preview --url http://localhost:3000/about --json
-camox preview --cwd apps/site --url http://localhost:3000/about --json
+camox login              # sign in to Camox in the browser
+camox logout             # sign out
+camox release            # build the website and sync its definitions to Live
+camox release --dry-run  # build it as a release would, without syncing anything
+camox clone PROJECT      # clone a project's code, where its project allows it
+camox push               # push the current branch's commits to a new draft
 ```
 
-Open the returned `url` in the browser you use for verification. Wait for
-`[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.
+## Signing in
 
-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 and backend. There is no
-automatic default-browser opening.
-The local dev server must already be running.
+`camox login` opens the browser and stores the session in `~/.camox/auth.json`,
+keyed by the Camox URL. A repository can override it for a given URL with its
+own `.camox/auth.json`, next to its `.git`.
 
-## Page SEO
+`camox logout` signs out of the authentication URL of the app it finds:
+it looks for `node_modules/.camox/runtime.json` from the current directory, or
+from `--cwd PATH`, walking upward. Without one, it signs out of camox.ai.
 
-Use `pages get` to read metadata and `pages set-seo` to edit it:
+## Releasing
 
-```sh
-camox pages get --path /about --json
-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
-```
-
-- `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 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
+`camox release` runs `vp build` in release mode. It needs `CAMOX_DEPLOY_TOKEN`
+and is what the release and Upgrade sandboxes run, not something members run
+by hand. `--dry-run` builds the same way without a token and without syncing
+definitions to Live, to check that a website builds.
 
-`pages get` shows page-owned blocks. To find layout-owned blocks:
+## Cloning a project's code
 
-```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.
+On a project whose code can be worked on outside Camox (a flag set by hand on
+the project), a member of its organization can clone its code
+(ADR 0026). `camox clone PROJECT [DIRECTORY]` takes its Project Slug or Project
+ID, clones its repo into `DIRECTORY` (its Project Slug by default), then runs
+`pnpm install`.
 
-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.
+The clone authenticates with short-lived read tokens. `camox clone` sets
+`camox git-credential` as the credential helper for the repo's host in the
+clone's own `.git/config`, never in the global one, so `git fetch` and
+`git pull` get a fresh token from the API with your Camox login when they need
+one. `git-credential` is the helper Git runs, not a command to run by hand.
 
-## Locales
+## Pushing to a draft
 
-```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
-```
+From a clone, `camox push` sends the current branch's commits to Camox, which
+opens a draft named after the branch with them (ADR 0026). It reads the Project
+ID from the checkout's `vite.config.ts`, fetches `main`, and sends the commits
+since the branch's merge base with `main` as a Git bundle to the API, never to
+the repo. The API checks them first and refuses, writing nothing, a branch that
+changes a platform-owned file or anything under `src/` other than TypeScript or
+CSS, that starts from a commit never on `main`, that is missing an Upgrade on
+`main` (merge `main` first), that conflicts with `main`, or whose head doesn't
+build. An accepted push lands the commits as they are on the draft's branch and
+builds the head as one revision. `camox push` waits for that build, sets the
+branch's upstream to the draft's branch, and prints the draft's studio URL. A
+refusal prints its message, with the build's errors when it doesn't build, and
+exits non-zero.
 
-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.
+## The SDK's auth module
 
-## Media
+`@camox/cli/auth` exports the token storage and sign-in helpers the SDK's Vite
+plugin imports.
 
-Run `camox login` and start your project's dev server (or build once) so the CLI
-can discover the project's runtime configuration.
-
-```sh
-# Upload a local file with manual alt text.
-camox files upload --file ./hero.webp --alt "Product screenshot" --json
-
-# Download a remote file and store a copy in Camox.
-camox files upload --url https://example.com/hero.webp --alt "Product screenshot"
-
-# Optionally override the uploaded filename.
-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
-FILE_ID=0199f1c2-7b3e-7a10-9c4d-5e6f7a8b9c0d
-camox files get --id "$FILE_ID"
-
-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 "$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 "$FILE_ID" --file ./new-hero.webp --filename hero.webp --alt "New screenshot"
-```
+## The Template's copy
 
-- Upload requires exactly one of `--file` or `--url`. URLs are copied, not linked.
-- 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
-  file types do not. AI may update both the filename and alt text asynchronously.
-- `--ai-metadata on` schedules generation for raster images; success does not mean
-  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 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: 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 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 `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.
-- Only HTTP(S) URLs without embedded credentials are supported. Signed query
-  URLs work and are not included in download errors. Camox credentials are never
-  sent to the source URL. Remote authentication flags and batch uploads are not
-  supported.
-
-See `camox files --help`, `camox files upload --help`, and
-`camox files update --help` for command options.
+`scripts/` refreshes `template-default` on Cloudflare Artifacts, which new
+projects fork. See [scripts/README.md](scripts/README.md).

package/dist/api-DOHUrl0V.mjs

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

package/dist/api-DU0iBFMw.mjs

@@ -0,0 +1,56 @@
+#!/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 src/lib/uuid.ts
+/** A UUID's text, in either case, for the patterns that find one. */
+const UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+//#endregion
+//#region src/lib/api.ts
+const CAMOX_API_URL = process.env.CAMOX_API_URL || "https://api.camox.ai";
+installLocalhostDns(new URL(CAMOX_API_URL).hostname);
+function createRpcClient(token) {
+	const link = new RPCLink({
+		url: `${CAMOX_API_URL}/rpc`,
+		headers: {
+			Authorization: `Bearer ${token}`,
+			"x-camox-client": "cli"
+		}
+	});
+	return createORPCClient(link);
+}
+async function verifySession(token) {
+	return (await fetch(`${CAMOX_API_URL}/api/auth/get-session`, {
+		method: "GET",
+		headers: {
+			Authorization: `Bearer ${token}`,
+			"Content-Type": "application/json"
+		}
+	})).ok;
+}
+const UUID_SHAPE = new RegExp(`^${UUID}$`, "i");
+/** The Project ID of a project named by its Project ID or its Project Slug. */
+async function projectIdOf(token, project) {
+	if (UUID_SHAPE.test(project)) return project.toLowerCase();
+	const { uuid } = await createRpcClient(token).projects.getBySlug({ slug: project });
+	return uuid;
+}
+/**
+* A short-lived read token for a project's repo, with the repo's Git remote: only for a member,
+* on a project whose code can be worked on outside Camox (ADR 0026).
+*/
+async function createCodeReadToken(token, project) {
+	const projectUuid = await projectIdOf(token, project);
+	return createRpcClient(token).projects.createCodeReadToken({ projectUuid });
+}
+/**
+* Pushes a branch's commits, as a Git bundle, to a draft of a project whose code can be worked
+* on outside Camox (ADR 0026): a new one, or the open draft `draftId` names. Resolves to the
+* push's events, where it stands, then the push once its head built; a refusal throws as they're
+* read, with its message, and its build errors for a head that doesn't build.
+*/
+function pushCode(token, input) {
+	return createRpcClient(token).code.push(input);
+}
+//#endregion
+export { UUID as i, pushCode as n, verifySession as r, createCodeReadToken as t };