@camox/cli 0.42.0 → 0.44.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { a as getProjectBySlug, i as createProject, n as checkSlugAvailability, o as listOrganizations, r as createOrganization, s as setActiveOrganization, t as callTool } from "./api-COfB7AKI.mjs";
-import { a as writeAuthTokenForUrl, i as verifyOneTimeToken, n as readAuthTokenForUrl, r as removeAuthTokenForUrl } from "./auth-core-cCuk5aZy.mjs";
+import { a as writeAuthTokenForUrl, i as verifyOneTimeToken, n as readAuthTokenForUrl, r as removeAuthTokenForUrl, t as normalizeUrl } from "./auth-core-4Jdf5q-u.mjs";
 import { object, or } from "@optique/core/constructs";
 import { message } from "@optique/core/message";
 import { defineProgram } from "@optique/core/program";
@@ -12,9 +12,11 @@ import { execSync, spawn, spawnSync } from "node:child_process";
 import http from "node:http";
 import * as p from "@clack/prompts";
 import { log } from "@clack/prompts";
-import fs from "node:fs";
-import path from "node:path";
+import fs, { openAsBlob } from "node:fs";
+import { tmpdir } from "node:os";
+import path, { basename, extname, join } from "node:path";
 import { ZodError, z } from "zod";
+import { mkdtemp, open, rm, stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import slugify from "slugify";
 //#region src/lib/auth.ts
@@ -188,11 +190,17 @@ const SIDECAR = path.join("node_modules", ".camox", "runtime.json");
 var RuntimeNotFoundError = class extends Error {
 	cwd;
 	constructor(cwd) {
-		super(`No camox runtime found. Looked for "${SIDECAR}" walking up from ${cwd}. The camox vite plugin writes this file on dev/build — start your project's dev server (or run a build) once before invoking camox.`);
+		super(`No Camox runtime found. Looked for "${SIDECAR}" starting from ${cwd} and its parent directories. Change into your app directory or pass --cwd <app-path>. If you're already targeting the correct app, run its dev server or build once to generate the runtime file.`);
 		this.cwd = cwd;
 		this.name = "RuntimeNotFoundError";
 	}
 };
+var RuntimeDirectoryError = class extends Error {
+	constructor(directory) {
+		super(`Runtime lookup directory "${directory}" does not exist, is not a directory, or cannot be accessed. Check --cwd <app-path>.`);
+		this.name = "RuntimeDirectoryError";
+	}
+};
 var RuntimeMalformedError = class extends Error {
 	constructor(file, reason) {
 		super(`Camox runtime sidecar at ${file} is malformed (${reason}). Re-run your project's dev server to regenerate it.`);
@@ -205,7 +213,13 @@ var RuntimeMalformedError = class extends Error {
 * that tell the user how to fix it.
 */
 function loadRuntime(cwd = process.cwd()) {
-	let dir = cwd;
+	let dir = path.resolve(cwd);
+	try {
+		if (!fs.statSync(dir).isDirectory()) throw new RuntimeDirectoryError(dir);
+	} catch {
+		throw new RuntimeDirectoryError(dir);
+	}
+	const start = dir;
 	while (true) {
 		const candidate = path.join(dir, SIDECAR);
 		if (fs.existsSync(candidate)) {
@@ -223,7 +237,7 @@ function loadRuntime(cwd = process.cwd()) {
 			}
 		}
 		const parent = path.dirname(dir);
-		if (parent === dir) throw new RuntimeNotFoundError(cwd);
+		if (parent === dir) throw new RuntimeNotFoundError(start);
 		dir = parent;
 	}
 }
@@ -239,7 +253,7 @@ function compact(input) {
 	for (const [k, v] of Object.entries(input)) if (v !== void 0) out[k] = v;
 	return out;
 }
-function fail(err, code) {
+function fail$1(err, code) {
 	printError(err);
 	process.exit(code);
 }
@@ -247,7 +261,7 @@ async function resolveProjectId(token, slug, apiUrl) {
 	try {
 		return (await getProjectBySlug(token, slug, apiUrl)).id;
 	} catch (err) {
-		return fail({
+		return fail$1({
 			code: "PROJECT_LOOKUP_FAILED",
 			message: `Could not load project "${slug}".`,
 			details: err instanceof Error ? err.message : String(err)
@@ -258,7 +272,7 @@ async function callRemote(params) {
 	try {
 		return await callTool(params);
 	} catch (err) {
-		return fail(asCliError(err), 1);
+		return fail$1(asCliError(err), 1);
 	}
 }
 /**
@@ -272,37 +286,46 @@ async function callRemote(params) {
 * from the sidecar — it's derived from auth (`dev:<email>`) by default,
 * with `--production` as the only opt-in for prod.
 */
-async function dispatch(opts) {
+async function resolveCommandContext(opts) {
 	let runtime;
 	try {
-		runtime = loadRuntime();
+		runtime = loadRuntime(opts.cwd);
 	} catch (err) {
-		if (err instanceof RuntimeNotFoundError || err instanceof RuntimeMalformedError) return fail({
+		if (err instanceof RuntimeDirectoryError) return fail$1({
+			code: "INVALID_CWD",
+			message: err.message
+		}, 2);
+		if (err instanceof RuntimeNotFoundError || err instanceof RuntimeMalformedError) return fail$1({
 			code: "RUNTIME_NOT_FOUND",
 			message: err.message
 		}, 2);
 		throw err;
 	}
 	const slug = opts.projectFlag?.trim() || process.env.CAMOX_PROJECT?.trim() || runtime.projectSlug;
-	const token = readAuthTokenForUrl(runtime.authenticationUrl);
-	if (!token) return fail({
+	const token = readAuthTokenForUrl(runtime.authenticationUrl, opts.cwd);
+	if (!token) return fail$1({
 		code: "NOT_AUTHENTICATED",
 		message: `No stored credentials for ${runtime.authenticationUrl}. Run \`camox login\` against this backend first.`
 	}, 2);
-	if (!opts.production && !token.email) return fail({
+	if (!opts.production && !token.email) return fail$1({
 		code: "AUTH_INCOMPLETE",
 		message: "Auth token is missing an email. Run `camox login` to refresh credentials."
 	}, 2);
 	const environmentName = opts.production ? "production" : `dev:${token.email}`;
 	const projectId = await resolveProjectId(token.token, slug, runtime.apiUrl);
-	const response = await callRemote({
+	return {
 		token: token.token,
 		apiUrl: runtime.apiUrl,
 		environmentName,
 		projectId,
-		name: opts.toolName,
-		args: compact(opts.args),
 		disableTelemetry: runtime.disableTelemetry
+	};
+}
+async function dispatch(opts) {
+	const response = await callRemote({
+		...await resolveCommandContext(opts),
+		name: opts.toolName,
+		args: compact(opts.args)
 	});
 	if (!response.ok) {
 		printError(response.error);
@@ -312,19 +335,24 @@ async function dispatch(opts) {
 	process.exit(0);
 }
 //#endregion
+//#region src/lib/runtime-options.ts
+const cwdFlag = optional(option("--cwd", string({ metavar: "PATH" }), { description: message`Start runtime lookup in this directory and walk upward. Relative to the shell's current directory; does not change how other file paths resolve.` }));
+//#endregion
 //#region src/commands/blocks.ts
 const projectFlag$3 = optional(option("--project", string({ metavar: "SLUG" })));
 const jsonFlag$3 = option("--json");
 const productionFlag$2 = option("--production");
 const liveFlag$1 = option("--live");
-const parser$8 = command("blocks", or(command("types", object({
+const parser$11 = command("blocks", or(command("types", object({
 	command: constant("blocks.types"),
+	cwd: cwdFlag,
 	project: projectFlag$3,
 	production: productionFlag$2,
 	json: jsonFlag$3
 })), command("describe", object({
 	command: constant("blocks.describe"),
 	type: multiple(option("--type", string({ metavar: "TYPE" })), { min: 1 }),
+	cwd: cwdFlag,
 	project: projectFlag$3,
 	production: productionFlag$2,
 	json: jsonFlag$3
@@ -332,6 +360,7 @@ const parser$8 = command("blocks", or(command("types", object({
 	command: constant("blocks.get"),
 	id: option("--id", integer({ metavar: "ID" })),
 	live: liveFlag$1,
+	cwd: cwdFlag,
 	project: projectFlag$3,
 	production: productionFlag$2,
 	json: jsonFlag$3
@@ -339,6 +368,7 @@ const parser$8 = command("blocks", or(command("types", object({
 	command: constant("blocks.get-many"),
 	id: multiple(option("--id", integer({ metavar: "ID" })), { min: 1 }),
 	live: liveFlag$1,
+	cwd: cwdFlag,
 	project: projectFlag$3,
 	production: productionFlag$2,
 	json: jsonFlag$3
@@ -353,6 +383,7 @@ const parser$8 = command("blocks", or(command("types", object({
 	beforeId: optional(option("--before-id", integer({ metavar: "ID" }))),
 	afterPosition: optional(option("--after-position", string({ metavar: "POS" }))),
 	beforePosition: optional(option("--before-position", string({ metavar: "POS" }))),
+	cwd: cwdFlag,
 	project: projectFlag$3,
 	production: productionFlag$2,
 	json: jsonFlag$3
@@ -361,6 +392,7 @@ const parser$8 = command("blocks", or(command("types", object({
 	id: option("--id", integer({ metavar: "ID" })),
 	content: optional(option("--content", string({ metavar: "JSON" }))),
 	settings: optional(option("--settings", string({ metavar: "JSON" }))),
+	cwd: cwdFlag,
 	project: projectFlag$3,
 	production: productionFlag$2,
 	json: jsonFlag$3
@@ -372,12 +404,14 @@ const parser$8 = command("blocks", or(command("types", object({
 	beforeId: optional(option("--before-id", integer({ metavar: "ID" }))),
 	afterPosition: optional(option("--after-position", string({ metavar: "POS" }))),
 	beforePosition: optional(option("--before-position", string({ metavar: "POS" }))),
+	cwd: cwdFlag,
 	project: projectFlag$3,
 	production: productionFlag$2,
 	json: jsonFlag$3
 })), command("delete", object({
 	command: constant("blocks.delete"),
 	id: option("--id", integer({ metavar: "ID" })),
+	cwd: cwdFlag,
 	project: projectFlag$3,
 	production: productionFlag$2,
 	json: jsonFlag$3
@@ -408,8 +442,9 @@ function collectPositioningArgs(args) {
 		toolArgs
 	};
 }
-async function handler$8(args) {
+async function handler$11(args) {
 	const outputMode = args.json ? "json" : "auto";
+	const cwd = args.cwd;
 	const projectFlag = args.project;
 	const production = args.production;
 	try {
@@ -417,6 +452,7 @@ async function handler$8(args) {
 			case "blocks.types": return dispatch({
 				toolName: "listBlockTypes",
 				args: {},
+				cwd,
 				projectFlag,
 				production,
 				outputMode
@@ -424,6 +460,7 @@ async function handler$8(args) {
 			case "blocks.describe": return dispatch({
 				toolName: "describeBlockTypes",
 				args: { types: [...args.type] },
+				cwd,
 				projectFlag,
 				production,
 				outputMode
@@ -434,6 +471,7 @@ async function handler$8(args) {
 					id: args.id,
 					source: args.live ? "live" : "draft"
 				},
+				cwd,
 				projectFlag,
 				production,
 				outputMode
@@ -444,6 +482,7 @@ async function handler$8(args) {
 					ids: [...args.id],
 					source: args.live ? "live" : "draft"
 				},
+				cwd,
 				projectFlag,
 				production,
 				outputMode
@@ -468,6 +507,7 @@ async function handler$8(args) {
 						settings,
 						...toolArgs
 					},
+					cwd,
 					projectFlag,
 					production,
 					outputMode
@@ -483,6 +523,7 @@ async function handler$8(args) {
 						content,
 						settings
 					},
+					cwd,
 					projectFlag,
 					production,
 					outputMode
@@ -510,6 +551,7 @@ async function handler$8(args) {
 						id: args.id,
 						...toolArgs
 					},
+					cwd,
 					projectFlag,
 					production,
 					outputMode
@@ -518,6 +560,7 @@ async function handler$8(args) {
 			case "blocks.delete": return dispatch({
 				toolName: "deleteBlock",
 				args: { id: args.id },
+				cwd,
 				projectFlag,
 				production,
 				outputMode
@@ -529,32 +572,74 @@ async function handler$8(args) {
 	}
 }
 //#endregion
+//#region src/commands/comments.ts
+const common$1 = {
+	cwd: cwdFlag,
+	project: optional(option("--project", string({ metavar: "SLUG" }))),
+	production: option("--production"),
+	json: option("--json")
+};
+const parser$10 = command("comments", or(command("list", object({
+	command: constant("comments.list"),
+	pageId: option("--page-id", integer({
+		min: 1,
+		metavar: "ID"
+	})),
+	...common$1
+}), { description: message`List all comments (including resolved ones) for a page.` }), command("resolve", object({
+	command: constant("comments.resolve"),
+	pageId: option("--page-id", integer({
+		min: 1,
+		metavar: "ID"
+	})),
+	id: option("--id", string({ metavar: "UUID" })),
+	...common$1
+}), { description: message`Resolve a comment by its UUID and page ID. Use comments list to find both.` })), { description: message`Read and resolve page comments in the selected environment. Defaults to development; use --production to target production.` });
+async function handler$10(args) {
+	return dispatch({
+		toolName: args.command === "comments.list" ? "listComments" : "resolveComment",
+		args: {
+			pageId: args.pageId,
+			...args.command === "comments.resolve" ? { id: args.id } : {}
+		},
+		cwd: args.cwd,
+		projectFlag: args.project,
+		production: args.production,
+		outputMode: args.json ? "json" : "auto"
+	});
+}
+//#endregion
 //#region src/commands/env.ts
 const projectFlag$2 = optional(option("--project", string({ metavar: "SLUG" })));
 const jsonFlag$2 = option("--json");
 const yesFlag = option("--yes", "-y");
-const parser$7 = command("env", or(command("check", object({
+const parser$9 = command("env", or(command("check", object({
 	command: constant("env.check"),
+	cwd: cwdFlag,
 	project: projectFlag$2,
 	json: jsonFlag$2
 })), command("push", object({
 	command: constant("env.push"),
 	yes: yesFlag,
+	cwd: cwdFlag,
 	project: projectFlag$2,
 	json: jsonFlag$2
 })), command("pull", object({
 	command: constant("env.pull"),
 	yes: yesFlag,
+	cwd: cwdFlag,
 	project: projectFlag$2,
 	json: jsonFlag$2
 }))));
-async function handler$7(args) {
+async function handler$9(args) {
 	const outputMode = args.json ? "json" : "auto";
+	const cwd = args.cwd;
 	const projectFlag = args.project;
 	switch (args.command) {
 		case "env.check": return dispatch({
 			toolName: "checkEnvironmentCompatibility",
 			args: {},
+			cwd,
 			projectFlag,
 			outputMode
 		});
@@ -571,12 +656,265 @@ async function handler$7(args) {
 			return dispatch({
 				toolName: "replicateEnvironment",
 				args: { direction: isPush ? "push" : "pull" },
+				cwd,
 				projectFlag,
 				outputMode
 			});
 		}
 	}
 }
+const TIMEOUT_MS = 12e4;
+const MAX_REDIRECTS = 5;
+function fail(code, message) {
+	throw Object.assign(new Error(message), { __cliError: {
+		code,
+		message
+	} });
+}
+function validateMetadata(options) {
+	if (options.alt !== void 0 && options.aiMetadata === "on") fail("INVALID_ARGS", "--alt cannot be combined with --ai-metadata on.");
+}
+function validateUpload(options) {
+	if (options.file !== void 0 === (options.url !== void 0)) fail("INVALID_ARGS", "Pass exactly one of --file or --url.");
+	validateMetadata(options);
+	validateFilename(options.filename);
+}
+function validateFilename(filename) {
+	if (filename !== void 0 && (!filename.trim() || /[\\/]/.test(filename) || filename.split("").some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127) || filename === "." || filename === "..")) fail("INVALID_ARGS", "--filename must be a non-empty filename without directories or control characters.");
+}
+function httpUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return fail("DOWNLOAD_FAILED", "Invalid media URL.");
+	}
+	if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) fail("DOWNLOAD_FAILED", "Media URLs must use HTTP(S) without embedded credentials.");
+	return url;
+}
+const MIME_TYPES = {
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".png": "image/png",
+	".webp": "image/webp",
+	".gif": "image/gif",
+	".avif": "image/avif",
+	".svg": "image/svg+xml",
+	".ico": "image/x-icon",
+	".bmp": "image/bmp",
+	".pdf": "application/pdf",
+	".mp4": "video/mp4",
+	".webm": "video/webm",
+	".mov": "video/quicktime",
+	".mp3": "audio/mpeg",
+	".wav": "audio/wav",
+	".ogg": "audio/ogg",
+	".txt": "text/plain",
+	".json": "application/json"
+};
+function mimeType(filename) {
+	return MIME_TYPES[extname(filename).toLowerCase()] ?? "application/octet-stream";
+}
+async function download(source, destination) {
+	try {
+		let url = httpUrl(source);
+		const signal = AbortSignal.timeout(TIMEOUT_MS);
+		for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects++) {
+			const response = await fetch(url, {
+				redirect: "manual",
+				signal
+			});
+			if ([
+				301,
+				302,
+				303,
+				307,
+				308
+			].includes(response.status)) {
+				await response.body?.cancel();
+				const location = response.headers.get("location");
+				if (!location || redirects === MAX_REDIRECTS) fail("DOWNLOAD_FAILED", "Missing redirect location or too many redirects.");
+				url = httpUrl(new URL(location, url).href);
+				continue;
+			}
+			if (!response.ok || !response.body) {
+				await response.body?.cancel();
+				fail("DOWNLOAD_FAILED", `Media download failed (HTTP ${response.status}).`);
+			}
+			if (Number(response.headers.get("content-length")) > 104857600) {
+				await response.body.cancel();
+				fail("FILE_TOO_LARGE", "File exceeds the 100 MiB limit.");
+			}
+			const file = await open(destination, "w");
+			let size = 0;
+			try {
+				for await (const chunk of response.body) {
+					size += chunk.byteLength;
+					if (size > 104857600) fail("FILE_TOO_LARGE", "File exceeds the 100 MiB limit.");
+					await file.writeFile(chunk);
+				}
+			} finally {
+				await file.close();
+			}
+			const filename = basename(decodeURIComponent(url.pathname)) || "upload";
+			return {
+				filename,
+				mimeType: response.headers.get("content-type")?.split(";")[0]?.trim() || mimeType(filename)
+			};
+		}
+		return fail("DOWNLOAD_FAILED", "Too many redirects.");
+	} catch (error) {
+		if (error && typeof error === "object" && "__cliError" in error) throw error;
+		return fail("DOWNLOAD_FAILED", "Could not download media (network, timeout, or local I/O failure).");
+	}
+}
+async function uploadFile(context, options, targetId) {
+	validateUpload(options);
+	let temporaryDirectory;
+	try {
+		let path = options.file;
+		let filename = path ? basename(path) : "upload";
+		let type = mimeType(filename);
+		if (options.url !== void 0) {
+			temporaryDirectory = await mkdtemp(join(tmpdir(), "camox-upload-"));
+			path = join(temporaryDirectory, "download");
+			const downloaded = await download(options.url, path);
+			filename = downloaded.filename;
+			type = downloaded.mimeType;
+		}
+		if (!path) fail("INVALID_ARGS", "Provide a file path.");
+		const info = await stat(path);
+		if (!info.isFile()) fail("INVALID_ARGS", "Upload source must be a regular file.");
+		if (info.size > 104857600) fail("FILE_TOO_LARGE", "File exceeds the 100 MiB limit.");
+		const body = new FormData();
+		if (type === "application/octet-stream") type = mimeType(options.filename ?? filename);
+		body.set("file", await openAsBlob(path, { type }), options.filename ?? filename);
+		body.set("projectId", String(context.projectId));
+		if (options.alt !== void 0) body.set("alt", options.alt);
+		if (options.aiMetadata !== void 0 || options.alt !== void 0) body.set("aiMetadataEnabled", String(options.alt === void 0 && options.aiMetadata === "on"));
+		const headers = {
+			Authorization: `Bearer ${context.token}`,
+			"x-camox-client": "cli",
+			"x-environment-name": context.environmentName
+		};
+		if (context.disableTelemetry) headers["x-camox-telemetry-disabled"] = "1";
+		let response;
+		try {
+			const endpoint = targetId === void 0 ? "/files/upload" : `/files/${targetId}/content`;
+			response = await fetch(`${context.apiUrl}${endpoint}`, {
+				method: "POST",
+				headers,
+				body,
+				signal: AbortSignal.timeout(TIMEOUT_MS),
+				redirect: "error"
+			});
+		} catch {
+			return fail("UPLOAD_FAILED", targetId === void 0 ? "Media upload failed (network or timeout). Check files list before retrying." : `File replacement failed (network or timeout). Check files get --id ${targetId} before retrying.`);
+		}
+		if (!response.ok) fail("UPLOAD_FAILED", `${targetId === void 0 ? "Media upload" : "File replacement"} failed (HTTP ${response.status}).`);
+		return await response.json();
+	} finally {
+		if (temporaryDirectory) await rm(temporaryDirectory, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/commands/files.ts
+const common = {
+	cwd: cwdFlag,
+	project: optional(option("--project", string({ metavar: "SLUG" }))),
+	production: option("--production"),
+	json: option("--json")
+};
+const metadata = {
+	alt: optional(option("--alt", string({ metavar: "TEXT" }), { description: message`Alt text (including an empty string). Disables automatic metadata.` })),
+	aiMetadata: optional(option("--ai-metadata", choice(["on", "off"]), { description: message`Enable or disable automatic metadata. Cannot enable alongside --alt. Enabling schedules generation for raster images.` }))
+};
+const parser$8 = command("files", or(command("upload", object({
+	command: constant("files.upload"),
+	file: optional(option("--file", string({ metavar: "PATH" }), { description: message`Local file to upload. Pass exactly one of --file or --url.` })),
+	url: optional(option("--url", string({ metavar: "URL" }), { description: message`HTTP(S) URL to download and copy into Camox, not an external reference.` })),
+	filename: optional(option("--filename", string({ metavar: "NAME" }), { description: message`Override the local basename or final URL path filename.` })),
+	...metadata,
+	...common
+}), { description: message`Upload media (maximum 100 MiB). Example: camox files upload --url https://example.com/hero.webp --alt "Product screenshot". Returns the stored file ID and URL. Without metadata options, raster images use automatic metadata.` }), command("update", object({
+	command: constant("files.update"),
+	id: option("--id", integer({
+		min: 1,
+		metavar: "ID"
+	})),
+	file: optional(option("--file", string({ metavar: "PATH" }), { description: message`Replace file content from a local path, keeping its ID and references. Mutually exclusive with --url.` })),
+	url: optional(option("--url", string({ metavar: "URL" }), { description: message`Download and replace file content from an HTTP(S) URL, keeping its ID and references. Mutually exclusive with --file.` })),
+	filename: optional(option("--filename", string({ metavar: "NAME" }), { description: message`Set the filename. Metadata-only renames preserve the URL; replacement uses the source filename unless overridden. Disable AI to prevent future automatic renaming.` })),
+	...metadata,
+	...common
+}), { description: message`Update metadata or replace file content with --file or --url (maximum 100 MiB). Replacing affects every reference to this file in the selected environment; its ID stays unchanged but its URL changes. Omitted alt text and AI settings are preserved. Example: camox files update --id 123 --file ./hero.jpg --alt "Updated description". Use --alt "" for intentionally empty alt text.` }), command("get", object({
+	command: constant("files.get"),
+	id: option("--id", integer({
+		min: 1,
+		metavar: "ID"
+	})),
+	...common
+}), { description: message`Inspect a file in the selected project and environment.` }), command("list", object({
+	command: constant("files.list"),
+	...common
+}), { description: message`List files in the selected project and environment.` })), { description: message`Upload and manage media. Defaults to your development environment; --production explicitly targets production.` });
+async function handler$8(args) {
+	const outputMode = args.json ? "json" : "auto";
+	const options = {
+		cwd: args.cwd,
+		projectFlag: args.project,
+		production: args.production,
+		outputMode
+	};
+	try {
+		if (args.command === "files.upload") {
+			validateUpload(args);
+			printResult(await uploadFile(await resolveCommandContext(options), args), outputMode);
+			process.exit(0);
+		}
+		if (args.command === "files.list") return dispatch({
+			...options,
+			toolName: "listFiles",
+			args: {}
+		});
+		if (args.command === "files.get") return dispatch({
+			...options,
+			toolName: "getFile",
+			args: { id: args.id }
+		});
+		if (args.file !== void 0 || args.url !== void 0) {
+			validateUpload(args);
+			printResult(await uploadFile(await resolveCommandContext(options), args, args.id), outputMode);
+			process.exit(0);
+		}
+		validateMetadata(args);
+		validateFilename(args.filename);
+		if (args.alt === void 0 && args.aiMetadata === void 0 && args.filename === void 0) {
+			printError({
+				code: "INVALID_ARGS",
+				message: "Pass --file, --url, --filename, --alt or --ai-metadata."
+			});
+			process.exit(2);
+		}
+		return dispatch({
+			...options,
+			toolName: "updateFile",
+			args: {
+				id: args.id,
+				alt: args.alt,
+				filename: args.filename,
+				aiMetadataEnabled: args.aiMetadata === void 0 ? void 0 : args.aiMetadata === "on"
+			}
+		});
+	} catch (err) {
+		const error = asCliError(err);
+		printError(error);
+		process.exit(error.code === "INVALID_ARGS" ? 2 : 1);
+	}
+}
 //#endregion
 //#region src/lib/agent-skills.ts
 function createAgentSkillLinks(targetDir) {
@@ -584,8 +922,10 @@ function createAgentSkillLinks(targetDir) {
 	const claudeSkillsDir = path.join(targetDir, ".claude", "skills");
 	fs.mkdirSync(agentsSkillsDir, { recursive: true });
 	fs.mkdirSync(claudeSkillsDir, { recursive: true });
-	fs.symlinkSync("../../node_modules/camox/skills/camox", path.join(agentsSkillsDir, "camox"));
-	fs.symlinkSync("../../.agents/skills/camox", path.join(claudeSkillsDir, "camox"));
+	for (const skill of ["camox", "camoxify"]) {
+		fs.symlinkSync(`../../node_modules/camox/skills/${skill}`, path.join(agentsSkillsDir, skill));
+		fs.symlinkSync(`../../.agents/skills/${skill}`, path.join(claudeSkillsDir, skill));
+	}
 }
 //#endregion
 //#region src/lib/utils.ts
@@ -656,8 +996,8 @@ function copyDir(src, dest, replacements) {
 }
 //#endregion
 //#region src/commands/init.ts
-const parser$6 = command("init", object({ command: constant("init") }));
-const handler$6 = init;
+const parser$7 = command("init", object({ command: constant("init") }));
+const handler$7 = init;
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ownPkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, "..", "package.json"), "utf-8"));
 const PNPM_WORKSPACE = `allowBuilds:
@@ -929,20 +1269,23 @@ src/routeTree.gen.ts
 const projectFlag$1 = optional(option("--project", string({ metavar: "SLUG" })));
 const jsonFlag$1 = option("--json");
 const productionFlag$1 = option("--production");
-const parser$5 = command("layouts", or(command("list", object({
+const parser$6 = command("layouts", or(command("list", object({
 	command: constant("layouts.list"),
+	cwd: cwdFlag,
 	project: projectFlag$1,
 	production: productionFlag$1,
 	json: jsonFlag$1
 }))));
-async function handler$5(args) {
+async function handler$6(args) {
 	const outputMode = args.json ? "json" : "auto";
+	const cwd = args.cwd;
 	const projectFlag = args.project;
 	const production = args.production;
 	switch (args.command) {
 		case "layouts.list": return dispatch({
 			toolName: "listLayouts",
 			args: {},
+			cwd,
 			projectFlag,
 			production,
 			outputMode
@@ -951,8 +1294,8 @@ async function handler$5(args) {
 }
 //#endregion
 //#region src/commands/login.ts
-const parser$4 = command("login", object({ command: constant("login") }));
-const handler$4 = login;
+const parser$5 = command("login", object({ command: constant("login") }));
+const handler$5 = login;
 async function login() {
 	p.intro("camox login");
 	try {
@@ -966,26 +1309,29 @@ async function login() {
 }
 //#endregion
 //#region src/commands/logout.ts
-const parser$3 = command("logout", object({ command: constant("logout") }));
-const handler$3 = logout;
-function logout() {
+const parser$4 = command("logout", object({
+	command: constant("logout"),
+	cwd: cwdFlag
+}));
+const handler$4 = logout;
+function logout(args = {}) {
 	p.intro("camox logout");
 	let authenticationUrl = null;
 	try {
-		authenticationUrl = loadRuntime().authenticationUrl;
+		authenticationUrl = loadRuntime(args.cwd).authenticationUrl;
 	} catch (error) {
-		if (error instanceof RuntimeMalformedError) {
+		if (error instanceof RuntimeMalformedError || error instanceof RuntimeDirectoryError || args.cwd !== void 0 && error instanceof RuntimeNotFoundError) {
 			log.error(error.message);
 			return;
 		}
 		if (!(error instanceof RuntimeNotFoundError)) throw error;
 	}
-	const token = authenticationUrl ? readAuthTokenForUrl(authenticationUrl) : readAuthToken();
+	const token = authenticationUrl ? readAuthTokenForUrl(authenticationUrl, args.cwd) : readAuthToken();
 	if (!token) {
 		log.error("Not logged in.");
 		return;
 	}
-	if (authenticationUrl) removeAuthTokenForUrl(authenticationUrl);
+	if (authenticationUrl) removeAuthTokenForUrl(authenticationUrl, args.cwd);
 	else removeAuthToken();
 	p.log.success(`Logged out from ${token.name}.`);
 }
@@ -997,6 +1343,7 @@ const productionFlag = option("--production");
 const liveFlag = option("--live");
 const list = command("list", object({
 	command: constant("pages.list"),
+	cwd: cwdFlag,
 	project: projectFlag,
 	production: productionFlag,
 	json: jsonFlag
@@ -1006,6 +1353,7 @@ const get = command("get", object({
 	id: optional(option("--id", integer({ metavar: "ID" }))),
 	path: optional(option("--path", string({ metavar: "PATH" }))),
 	live: liveFlag,
+	cwd: cwdFlag,
 	project: projectFlag,
 	production: productionFlag,
 	json: jsonFlag
@@ -1015,6 +1363,7 @@ const publish = command("publish", object({
 	id: optional(option("--id", integer({ metavar: "ID" }))),
 	path: optional(option("--path", string({ metavar: "PATH" }))),
 	noLayout: option("--no-layout"),
+	cwd: cwdFlag,
 	project: projectFlag,
 	production: productionFlag,
 	json: jsonFlag
@@ -1023,6 +1372,7 @@ const unpublish = command("unpublish", object({
 	command: constant("pages.unpublish"),
 	id: optional(option("--id", integer({ metavar: "ID" }))),
 	path: optional(option("--path", string({ metavar: "PATH" }))),
+	cwd: cwdFlag,
 	project: projectFlag,
 	production: productionFlag,
 	json: jsonFlag
@@ -1031,50 +1381,64 @@ const discardChanges = command("discard-changes", object({
 	command: constant("pages.discard-changes"),
 	id: optional(option("--id", integer({ metavar: "ID" }))),
 	path: optional(option("--path", string({ metavar: "PATH" }))),
+	cwd: cwdFlag,
 	project: projectFlag,
 	production: productionFlag,
 	json: jsonFlag
 }));
-const parser$2 = command("pages", or(list, get, command("create", object({
+const parser$3 = command("pages", or(list, get, command("create", object({
 	command: constant("pages.create"),
 	nickname: optional(option("--nickname", string({ metavar: "TEXT" }))),
 	pathSegment: option("--path-segment", string({ metavar: "SEGMENT" })),
 	layoutId: option("--layout-id", integer({ metavar: "ID" })),
 	parentPageId: optional(option("--parent-page-id", integer({ metavar: "ID" }))),
+	cwd: cwdFlag,
 	project: projectFlag,
 	production: productionFlag,
 	json: jsonFlag
 })), command("update", object({
 	command: constant("pages.update"),
-	id: option("--id", integer({ metavar: "ID" })),
+	id: optional(option("--id", integer({
+		min: 1,
+		metavar: "ID"
+	}))),
+	path: optional(option("--path", string({ metavar: "PATH" }))),
+	metaTitle: optional(option("--meta-title", string({ metavar: "TEXT" }), { description: message`Set the SEO title. An empty string clears it. Disables automatic SEO for both fields.` })),
+	metaDescription: optional(option("--meta-description", string({ metavar: "TEXT" }), { description: message`Set the SEO description. An empty string clears it. Disables automatic SEO for both fields.` })),
+	aiSeo: optional(option("--ai-seo", choice(["on", "off"]), { description: message`Enable or disable automatic SEO. Enabling schedules asynchronous generation; it cannot be combined with manual metadata. Disabling preserves current metadata.` })),
 	nickname: optional(option("--nickname", string({ metavar: "TEXT" }))),
 	pathSegment: optional(option("--path-segment", string({ metavar: "SEGMENT" }))),
 	parentPageId: optional(option("--parent-page-id", integer({ metavar: "ID" }))),
+	cwd: cwdFlag,
 	project: projectFlag,
 	production: productionFlag,
 	json: jsonFlag
-})), command("set-layout", object({
+}), { description: message`Update a page draft, including in --production. Pass exactly one of --id or --path and at least one update field. Omitted fields are preserved. Publish separately with pages publish. Example: camox pages update --path /about --meta-title "About us" --meta-description "Meet the team". Read metadata with pages get; add --live for published metadata.` }), command("set-layout", object({
 	command: constant("pages.set-layout"),
 	id: option("--id", integer({ metavar: "ID" })),
 	layoutId: option("--layout-id", integer({ metavar: "ID" })),
+	cwd: cwdFlag,
 	project: projectFlag,
 	production: productionFlag,
 	json: jsonFlag
 })), command("delete", object({
 	command: constant("pages.delete"),
 	id: option("--id", integer({ metavar: "ID" })),
+	cwd: cwdFlag,
 	project: projectFlag,
 	production: productionFlag,
 	json: jsonFlag
 })), publish, unpublish, discardChanges));
-async function handler$2(args) {
+async function handler$3(args) {
 	const outputMode = args.json ? "json" : "auto";
+	const cwd = args.cwd;
 	const projectFlag = args.project;
 	const production = args.production;
 	switch (args.command) {
 		case "pages.list": return dispatch({
 			toolName: "listPages",
 			args: {},
+			cwd,
 			projectFlag,
 			production,
 			outputMode
@@ -1093,6 +1457,7 @@ async function handler$2(args) {
 					...args.id != null ? { id: args.id } : { path: args.path },
 					source: args.live ? "live" : "draft"
 				},
+				cwd,
 				projectFlag,
 				production,
 				outputMode
@@ -1105,28 +1470,63 @@ async function handler$2(args) {
 				layoutId: args.layoutId,
 				parentPageId: args.parentPageId
 			},
+			cwd,
 			projectFlag,
 			production,
 			outputMode
 		});
-		case "pages.update": return dispatch({
-			toolName: "updatePage",
-			args: {
-				id: args.id,
-				nickname: args.nickname,
-				pathSegment: args.pathSegment,
-				parentPageId: args.parentPageId
-			},
-			projectFlag,
-			production,
-			outputMode
-		});
+		case "pages.update":
+			if (args.id == null === (args.path == null)) {
+				printError({
+					code: "INVALID_ARGS",
+					message: "Pass exactly one of --id or --path."
+				});
+				process.exit(2);
+			}
+			if (args.aiSeo === "on" && (args.metaTitle !== void 0 || args.metaDescription !== void 0)) {
+				printError({
+					code: "INVALID_ARGS",
+					message: "Cannot enable automatic SEO alongside manual metadata."
+				});
+				process.exit(2);
+			}
+			if ([
+				args.nickname,
+				args.pathSegment,
+				args.parentPageId,
+				args.metaTitle,
+				args.metaDescription,
+				args.aiSeo
+			].every((value) => value === void 0)) {
+				printError({
+					code: "INVALID_ARGS",
+					message: "Pass at least one field to update."
+				});
+				process.exit(2);
+			}
+			return dispatch({
+				toolName: "updatePage",
+				args: {
+					...args.id != null ? { id: args.id } : { path: args.path },
+					metaTitle: args.metaTitle,
+					metaDescription: args.metaDescription,
+					aiSeoEnabled: args.aiSeo === void 0 ? void 0 : args.aiSeo === "on",
+					nickname: args.nickname,
+					pathSegment: args.pathSegment,
+					parentPageId: args.parentPageId
+				},
+				cwd,
+				projectFlag,
+				production,
+				outputMode
+			});
 		case "pages.set-layout": return dispatch({
 			toolName: "setPageLayout",
 			args: {
 				id: args.id,
 				layoutId: args.layoutId
 			},
+			cwd,
 			projectFlag,
 			production,
 			outputMode
@@ -1134,6 +1534,7 @@ async function handler$2(args) {
 		case "pages.delete": return dispatch({
 			toolName: "deletePage",
 			args: { id: args.id },
+			cwd,
 			projectFlag,
 			production,
 			outputMode
@@ -1152,6 +1553,7 @@ async function handler$2(args) {
 					...args.id != null ? { id: args.id } : { path: args.path },
 					alsoPublishLayout: !args.noLayout
 				},
+				cwd,
 				projectFlag,
 				production,
 				outputMode
@@ -1167,6 +1569,7 @@ async function handler$2(args) {
 			return dispatch({
 				toolName: "unpublishPage",
 				args: args.id != null ? { id: args.id } : { path: args.path },
+				cwd,
 				projectFlag,
 				production,
 				outputMode
@@ -1182,6 +1585,7 @@ async function handler$2(args) {
 			return dispatch({
 				toolName: "discardPageChanges",
 				args: args.id != null ? { id: args.id } : { path: args.path },
+				cwd,
 				projectFlag,
 				production,
 				outputMode
@@ -1189,6 +1593,61 @@ async function handler$2(args) {
 	}
 }
 //#endregion
+//#region src/commands/preview.ts
+const parser$2 = command("preview", object({
+	command: constant("preview"),
+	cwd: cwdFlag,
+	url: option("--url", string()),
+	json: option("--json")
+}), { description: message`Create a single-use sign-in URL for local draft verification. Open it in your automation browser within three minutes. The URL is a credential; do not share it.` });
+async function handler$2(args) {
+	try {
+		const url = new URL(args.url);
+		if (!["http:", "https:"].includes(url.protocol) || ![
+			"localhost",
+			"127.0.0.1",
+			"[::1]"
+		].includes(url.hostname) || url.username || url.password) throw new Error("Preview requires an http(s) loopback URL without credentials.");
+		const runtime = loadRuntime(args.cwd);
+		const auth = readAuthTokenForUrl(runtime.authenticationUrl, args.cwd);
+		if (!auth?.email) {
+			printError({
+				code: "NOT_AUTHENTICATED",
+				message: `Run camox login for ${runtime.authenticationUrl} first.`
+			});
+			process.exitCode = 2;
+			return;
+		}
+		const response = await fetch(`${normalizeUrl(runtime.apiUrl)}/api/auth/one-time-token/generate`, {
+			headers: { Authorization: `Bearer ${auth.token}` },
+			redirect: "error",
+			signal: AbortSignal.timeout(15e3)
+		});
+		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();
+		if (typeof data.token !== "string" || !data.token) throw new Error("Authentication backend returned no one-time token.");
+		const target = {
+			projectSlug: runtime.projectSlug,
+			environmentName: `dev:${auth.email}`,
+			apiUrl: normalizeUrl(runtime.apiUrl)
+		};
+		url.searchParams.set("camox-preview", JSON.stringify(target));
+		url.searchParams.set("ott", data.token);
+		printResult({
+			url: url.href,
+			...target,
+			source: "draft",
+			warning: "Single-use sign-in credential, valid for three minutes. Open in your verification browser; do not share or commit."
+		}, args.json ? "json" : "auto");
+	} catch (error) {
+		printError({
+			code: "PREVIEW_FAILED",
+			message: error instanceof Error ? error.message : "Could not create preview."
+		});
+		process.exitCode = 2;
+	}
+}
+//#endregion
 //#region src/commands/release.ts
 const parser$1 = command("release", object({ command: constant("release") }));
 function handler$1() {
@@ -1220,14 +1679,22 @@ function handler$1() {
 //#region src/commands/status.ts
 const parser = command("status", object({
 	command: constant("status"),
+	cwd: cwdFlag,
 	production: option("--production"),
 	json: option("--json")
 }));
 async function handler(args) {
 	let runtime;
 	try {
-		runtime = loadRuntime();
+		runtime = loadRuntime(args.cwd);
 	} catch (err) {
+		if (err instanceof RuntimeDirectoryError) {
+			printError({
+				code: "INVALID_CWD",
+				message: err.message
+			});
+			process.exit(2);
+		}
 		if (err instanceof RuntimeNotFoundError || err instanceof RuntimeMalformedError) {
 			printError({
 				code: "RUNTIME_NOT_FOUND",
@@ -1237,7 +1704,7 @@ async function handler(args) {
 		}
 		throw err;
 	}
-	const token = readAuthTokenForUrl(runtime.authenticationUrl);
+	const token = readAuthTokenForUrl(runtime.authenticationUrl, args.cwd);
 	const environmentName = args.production ? "production" : token?.email ? `dev:${token.email}` : null;
 	const status = {
 		projectSlug: runtime.projectSlug,
@@ -1267,7 +1734,7 @@ async function handler(args) {
 //#endregion
 //#region src/index.ts
 const result = runSync(defineProgram({
-	parser: or(parser$6, parser$4, parser$3, parser$1, parser, parser$2, parser$8, parser$5, parser$7),
+	parser: or(parser$7, parser$5, parser$4, parser$1, parser, parser$2, parser$3, parser$11, parser$10, parser$6, parser$9, parser$8),
 	metadata: {
 		name: "camox",
 		brief: message`Camox CLI`
@@ -1275,17 +1742,20 @@ const result = runSync(defineProgram({
 }), { help: "both" });
 switch (result.command) {
 	case "init":
-		await handler$6();
+		await handler$7();
 		break;
 	case "login":
-		await handler$4();
+		await handler$5();
 		break;
 	case "logout":
-		handler$3();
+		handler$4(result);
 		break;
 	case "release":
 		handler$1();
 		break;
+	case "preview":
+		await handler$2(result);
+		break;
 	case "status":
 		await handler(result);
 		break;
@@ -1298,7 +1768,7 @@ switch (result.command) {
 	case "pages.publish":
 	case "pages.unpublish":
 	case "pages.discard-changes":
-		await handler$2(result);
+		await handler$3(result);
 		break;
 	case "blocks.types":
 	case "blocks.describe":
@@ -1308,15 +1778,25 @@ switch (result.command) {
 	case "blocks.edit":
 	case "blocks.move":
 	case "blocks.delete":
+		await handler$11(result);
+		break;
+	case "comments.list":
+	case "comments.resolve":
+		await handler$10(result);
+		break;
+	case "files.upload":
+	case "files.update":
+	case "files.get":
+	case "files.list":
 		await handler$8(result);
 		break;
 	case "layouts.list":
-		await handler$5(result);
+		await handler$6(result);
 		break;
 	case "env.check":
 	case "env.push":
 	case "env.pull":
-		await handler$7(result);
+		await handler$9(result);
 		break;
 }
 //#endregion