@camox/cli 0.42.0 → 0.44.0

package/README.md

@@ -0,0 +1,146 @@
+# Camox CLI
+
+## Runtime lookup and monorepos
+
+Runtime-backed commands (`status`, `pages`, `blocks`, `layouts`, `env`, `files`,
+`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. Environment selection is unchanged:
+your development environment by default, with explicit `--production` where supported.
+
+## Authenticated local draft preview
+
+CLI login does not sign in a fresh browser. To verify draft writes without publishing:
+
+```sh
+camox preview --url http://localhost:3000/about --json
+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="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.
+The local dev server must already be running.
+
+## Page SEO
+
+Use `pages get` to read metadata and `pages update` 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
+```
+
+- 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
+  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.
+
+See `camox pages update --help` for options and examples.
+
+## Media
+
+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.
+camox files list
+camox files get --id 123
+
+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
+
+# 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
+
+# Replace content and override metadata together.
+camox files update --id 123 --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.
+  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, 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;
+  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.
+- 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.
+- Uploads return the stored file record, including `id`, `url`, `mimeType`, `alt`,
+  and `aiMetadataEnabled`. 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.

package/dist/auth-core-4Jdf5q-u.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+//#region src/lib/auth-core.ts
+function globalAuthFile() {
+	return path.join(os.homedir(), ".camox", "auth.json");
+}
+function localAuthFile(cwd) {
+	let directory = path.resolve(cwd);
+	while (true) {
+		if (fs.existsSync(path.join(directory, ".git"))) {
+			const file = path.join(directory, ".camox", "auth.json");
+			return fs.existsSync(file) ? file : null;
+		}
+		const parent = path.dirname(directory);
+		if (parent === directory) return null;
+		directory = parent;
+	}
+}
+function normalizeUrl(url) {
+	return url.replace(/\/+$/, "");
+}
+function readAllTokens(file) {
+	if (!fs.existsSync(file)) return {};
+	const entries = JSON.parse(fs.readFileSync(file, "utf-8"));
+	if (!entries || typeof entries !== "object" || Array.isArray(entries)) throw new Error(`Invalid Camox credentials file: ${file}`);
+	return entries;
+}
+function writeAllTokens(file, tokens) {
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, JSON.stringify(tokens, null, 2), { mode: 384 });
+	fs.chmodSync(file, 384);
+}
+function credentialFile(authenticationUrl, cwd) {
+	const local = localAuthFile(cwd);
+	if (local && Object.hasOwn(readAllTokens(local), normalizeUrl(authenticationUrl))) return local;
+	return globalAuthFile();
+}
+/** Look up stored credentials for a specific Camox authentication backend. */
+function readAuthTokenForUrl(authenticationUrl, cwd = process.cwd()) {
+	const entry = readAllTokens(credentialFile(authenticationUrl, cwd))[normalizeUrl(authenticationUrl)];
+	if (entry?.token && entry?.name && typeof entry.email === "string") return entry;
+	return null;
+}
+function writeAuthTokenForUrl(authenticationUrl, token, cwd = process.cwd()) {
+	const file = credentialFile(authenticationUrl, cwd);
+	const tokens = readAllTokens(file);
+	tokens[normalizeUrl(authenticationUrl)] = token;
+	writeAllTokens(file, tokens);
+}
+function removeAuthTokenForUrl(authenticationUrl, cwd = process.cwd()) {
+	const file = credentialFile(authenticationUrl, cwd);
+	const tokens = readAllTokens(file);
+	if (file !== globalAuthFile()) {
+		tokens[normalizeUrl(authenticationUrl)] = null;
+		writeAllTokens(file, tokens);
+		return;
+	}
+	delete tokens[normalizeUrl(authenticationUrl)];
+	if (Object.keys(tokens).length > 0) {
+		writeAllTokens(file, tokens);
+		return;
+	}
+	fs.rmSync(file, { force: true });
+}
+async function verifyOneTimeToken(apiUrl, token) {
+	const res = await fetch(`${normalizeUrl(apiUrl)}/api/auth/one-time-token/verify`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ token })
+	});
+	if (!res.ok) throw new Error(`OTT verification failed: ${res.status}`);
+	const data = await res.json();
+	const user = data.user;
+	if (!user?.name) throw new Error("No user info in verification response");
+	const sessionToken = data.session?.token;
+	if (!sessionToken) throw new Error("No session token in verification response");
+	return {
+		name: user.name,
+		email: user.email ?? "",
+		token: sessionToken
+	};
+}
+//#endregion
+export { writeAuthTokenForUrl as a, verifyOneTimeToken as i, readAuthTokenForUrl as n, removeAuthTokenForUrl as r, normalizeUrl as t };