frontpage-host 0.1.8 → 0.1.10

package/AGENTS.md

@@ -112,7 +112,7 @@ Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or
 - Articles: `frontpage articles …` for lifecycle; bodies via sync under `content/` or `articles content get|set`. Section landing is an owned `src/pages/<section>/index.astro`.
 - Migrate a folder into Articles: prefer `frontpage prompt "migrate … into articles"` — do not invent a mass delete+write migration.
 - Extensions: `frontpage extensions`; if LOCKED on plan, do not fake charts/etc.
-- Media in markup: `/__media/uploads/<slug>/…` from `frontpage media` (not raw blob URLs).
+- Media: `frontpage media upload <file>` — images/PDF ≤25 MB, video (MP4/WebM/MOV) ≤50 MB, SVG/text ≤4 MB (sanitizing proxy). Human output prints `sitePath:` first (use that in markup — never raw blob hosts), then optional `url:`. Optional `?w=` on rasters only.
 - Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for structured reads (SQL is guard + RLS site-scoped).
 
 ## Agent prompt loop
@@ -122,13 +122,14 @@ frontpage prompt "make the hero shorter"
 frontpage prompt "Use this logo in the header" --attach ./logo.png
 frontpage prompt "Match this brand PDF" --attach ./guide.pdf --path /
 frontpage prompt "Reuse uploaded art" --attach /__media/uploads/<slug>/<file>
+frontpage media upload ./clip.mp4
 frontpage runs wait          # wait for the agent run to finish (failed/canceled → exit 2)
 # Review https://<subdomain>.frontpage.host — do not publish unless asked.
 ```
 
-- `--attach` accepts a local file (uploads via the same path as `frontpage media upload`), an existing `/__media/…` site path, or an `https://` Blob URL. Repeatable.
+- `--attach` accepts a local file (same transport as `frontpage media upload`), an existing `/__media/…` site path, or an `https://` Blob URL. Repeatable.
 - `--asset-url <https://…>` adds a legacy image URL. Repeatable.
-- Caps match the media proxy: images / PDF / text-code. CLI video and >4 MB binaries are not supported yet (editor attach / Phase E).
+- Caps: images/PDF ≤25 MB, video ≤50 MB, SVG/text via proxy ≤4 MB (large text/data Blob upload is editor-only).
 - Prompt text is still required (API). Attachments ride on the same enqueue as the editor.
 - `runs wait` with `--json`: failures use `ok: false` and include `data.run` (with `run.error` when present).
 - `deploy wait` is fail-closed: exit 2 if the waited run (or latest, when already idle) is `failed`/`canceled`.
@@ -179,7 +180,7 @@ Global machine envelope (`--json`):
 { "ok": false, "command": "push", "error": { "message": "…", "code": "conflict", "httpStatus": 409, "exitCode": 3, "requestId": "…" } }
 ```
 
-Failures with `--json` print the envelope on **stdout** (still use the process exit code). Include `requestId` when filing support issues.
+Failures with `--json` print the envelope on **stdout** (still use the process exit code). Include `requestId` when the API returned one (local validation errors omit `requestId` and `httpStatus`).
 
 ## Global flags
 
@@ -190,6 +191,7 @@ Failures with `--json` print the envelope on **stdout** (still use the process e
 | `--site <slug>` | Subdomain override (most site commands) |
 | `--yes` | Confirm destructive ops (`unpublish`, `revert`) when non-TTY |
 | `--help` / `-h` | Per-command help (alias of `frontpage help <cmd>`) |
+| `--version` / `-V` | Print `frontpage-host <semver>` (also `frontpage version`) |
 
 ## Destructive ops — defaults for agents
 

package/dist/argv.d.ts

@@ -0,0 +1,12 @@
+/** Remove `--name value` (or `--name=value`) from rest; return the value. */
+export declare function takeFlag(rest: string[], name: string): string | undefined;
+/** Remove a boolean `--name` flag from rest; return whether it was present. */
+export declare function hasFlag(rest: string[], name: string): boolean;
+/** True when a token looks like a flag (not a negative number). */
+export declare function looksLikeFlag(token: string): boolean;
+/**
+ * After a command has consumed its known options, fail if any flag-like
+ * tokens remain. Positionals (non-flags) are allowed leftovers unless the
+ * caller also checks them.
+ */
+export declare function assertNoUnknownFlags(rest: string[], command: string): void;

package/dist/argv.js

@@ -0,0 +1,48 @@
+/**
+ * Shared argv helpers for command parsers (CLI Agent UX R1–R3).
+ */
+import { CliHttpError, EXIT_USAGE } from "./http/client.js";
+/** Remove `--name value` (or `--name=value`) from rest; return the value. */
+export function takeFlag(rest, name) {
+    const eq = `${name}=`;
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === name) {
+            const v = rest[i + 1];
+            rest.splice(i, 2);
+            return v;
+        }
+        if (a.startsWith(eq)) {
+            rest.splice(i, 1);
+            return a.slice(eq.length);
+        }
+    }
+    return undefined;
+}
+/** Remove a boolean `--name` flag from rest; return whether it was present. */
+export function hasFlag(rest, name) {
+    const i = rest.indexOf(name);
+    if (i === -1)
+        return false;
+    rest.splice(i, 1);
+    return true;
+}
+/** True when a token looks like a flag (not a negative number). */
+export function looksLikeFlag(token) {
+    if (token === "-" || token === "--")
+        return true;
+    if (/^-\d/.test(token))
+        return false; // allow negative numbers as values
+    return token.startsWith("-");
+}
+/**
+ * After a command has consumed its known options, fail if any flag-like
+ * tokens remain. Positionals (non-flags) are allowed leftovers unless the
+ * caller also checks them.
+ */
+export function assertNoUnknownFlags(rest, command) {
+    const unknown = rest.find(looksLikeFlag);
+    if (!unknown)
+        return;
+    throw new CliHttpError(`Unknown flag: ${unknown}. Run: frontpage help ${command}`, EXIT_USAGE, 0, "bad_request");
+}

package/dist/bin.js

@@ -34,6 +34,7 @@ import { runTokens } from "./commands/tokens.js";
 import { runHistory } from "./commands/history.js";
 import { runRevert } from "./commands/revert.js";
 import { runCompletion } from "./commands/completion.js";
+import { runVersion } from "./commands/version.js";
 import { EXIT_USAGE, EXIT_UNEXPECTED } from "./http/client.js";
 import { parseGlobalFlags } from "./flags.js";
 import { setRuntimeFlags, isJson } from "./runtime.js";
@@ -43,6 +44,10 @@ async function main() {
     const argv = parsed.args;
     const cmd = argv[0];
     const args = argv.slice(1);
+    // Global version before help/command dispatch (R6).
+    if (parsed.wantsVersion || cmd === "version") {
+        return runVersion();
+    }
     // Global or per-command help aliases (before site resolution).
     if (!cmd || cmd === "help") {
         return runHelp(cmd === "help" ? args : []);

package/dist/commands/help.js

@@ -70,7 +70,7 @@ export function runHelp(args) {
             console.log(`  ${c.name.padEnd(12)} ${c.summary}`);
         }
         console.log(`\nTopics: frontpage help ${TOPIC_NAMES.join(" | frontpage help ")}`);
-        console.log("Global: --json  --quiet  --yes  --site <slug>  --help");
+        console.log("Global: --json  --quiet  --yes  --site <slug>  --help  --version");
         console.log("Agents: see AGENTS.md in the npm package");
         return 0;
     }

package/dist/commands/media.js

@@ -1,13 +1,18 @@
-import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1PostMultipart } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, exitCodeForError } from "../http/client.js";
+import { emitErr, emitOk, isJson } from "../runtime.js";
+import { uploadLocalMedia } from "../media/upload.js";
+import { v1Get } from "../http/client.js";
 export async function runMedia(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
         const sub = rest[0] ?? "list";
         if (sub === "list" || sub === "ls") {
             const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/media`);
+            if (isJson()) {
+                emitOk("media", { slug, ...data });
+                return EXIT_OK;
+            }
             for (const a of data.assets) {
                 console.log(`${a.sitePath.padEnd(48)}  ${String(a.sizeBytes).padStart(8)}  ${a.name}`);
             }
@@ -17,27 +22,33 @@ export async function runMedia(args) {
         if (sub === "upload") {
             const filePath = rest[1];
             if (!filePath) {
-                console.error("Usage: frontpage media upload <file> [--site <slug>]");
+                console.error("Usage: frontpage media upload <file> [--site <slug>] [--json]");
                 return EXIT_USAGE;
             }
-            const bytes = await readFile(filePath);
-            const form = new FormData();
-            form.append("file", new Blob([Uint8Array.from(bytes)]), basename(filePath));
-            const data = await v1PostMultipart(`/api/v1/sites/${encodeURIComponent(slug)}/media`, form);
+            const data = await uploadLocalMedia({ slug, filePath });
+            if (isJson()) {
+                emitOk("media", { slug, ...data });
+                return EXIT_OK;
+            }
             if (data.kind === "text") {
                 console.log(`Inline text (${data.filename}): ${data.sizeBytes ?? 0} bytes — not stored.`);
+                return EXIT_OK;
             }
-            else {
-                console.log(data.url ?? data.key ?? JSON.stringify(data));
-                if (data.key)
-                    console.log(`sitePath: /__media/${data.key}`);
-            }
+            // Human mode: sitePath first so first-line copy/paste is markup-safe (R4).
+            if (data.sitePath)
+                console.log(`sitePath: ${data.sitePath}`);
+            else if (data.key)
+                console.log(`sitePath: /__media/${data.key}`);
+            if (data.url)
+                console.log(`url: ${data.url}`);
             return EXIT_OK;
         }
-        console.error("Usage: frontpage media list|upload <file> [--site <slug>]");
+        console.error("Usage: frontpage media list|upload <file> [--site <slug>] [--json]");
         return EXIT_USAGE;
     }
     catch (err) {
+        if (isJson())
+            return emitErr("media", err);
         console.error(err instanceof Error ? err.message : String(err));
         return exitCodeForError(err);
     }

package/dist/commands/open.d.ts

@@ -1 +1,3 @@
+/** Site-relative path for open; rejects schemes and traversal. */
+export declare function normalizeOpenPath(raw: string): string;
 export declare function runOpen(args: string[]): Promise<number>;

package/dist/commands/open.js

@@ -1,22 +1,56 @@
 import { spawn } from "node:child_process";
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE } from "../http/client.js";
+import { CliHttpError, EXIT_OK, EXIT_USAGE } from "../http/client.js";
+import { assertNoUnknownFlags, hasFlag, takeFlag } from "../argv.js";
 import { emitErr, emitOk, emitUsage, isJson, isQuiet } from "../runtime.js";
+/** Site-relative path for open; rejects schemes and traversal. */
+export function normalizeOpenPath(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("/") || trimmed.startsWith("//")) {
+        throw new CliHttpError("Open path must be site-relative and start with / (e.g. /updates).", EXIT_USAGE, 0, "bad_request");
+    }
+    if (/^https?:/i.test(trimmed) || trimmed.includes("..") || trimmed.includes("\\")) {
+        throw new CliHttpError("Open path must be a site-relative path (no http(s) URLs or ..).", EXIT_USAGE, 0, "bad_request");
+    }
+    const collapsed = trimmed.replace(/\/+/g, "/");
+    if (collapsed.length > 1 && collapsed.endsWith("/"))
+        return collapsed.slice(0, -1);
+    return collapsed;
+}
 export async function runOpen(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
-        const prod = rest.includes("--prod") || args.includes("--prod");
-        const url = `https://${slug}.frontpage.host/`;
+        const work = [...rest];
+        const prod = hasFlag(work, "--prod");
+        const pathFlag = takeFlag(work, "--path");
+        let path = "/";
+        if (pathFlag !== undefined) {
+            path = normalizeOpenPath(pathFlag);
+        }
+        else {
+            const positional = work.find((a) => a.startsWith("/") && !a.startsWith("//"));
+            if (positional) {
+                work.splice(work.indexOf(positional), 1);
+                path = normalizeOpenPath(positional);
+            }
+        }
+        assertNoUnknownFlags(work, "open");
+        if (work.length > 0) {
+            return emitUsage("open", "Usage: frontpage open [/path|--path /path] [--site <slug>] [--prod]", EXIT_USAGE);
+        }
+        const url = path === "/"
+            ? `https://${slug}.frontpage.host/`
+            : `https://${slug}.frontpage.host${path}`;
         // --prod is reserved for a future production custom-domain lookup; both
         // modes currently open the site subdomain on *.frontpage.host.
         if (prod && !isJson() && !isQuiet()) {
-            console.error("Note: --prod is a no-op stub; opening https://<slug>.frontpage.host/");
+            console.error("Note: --prod is a no-op stub; opening https://<slug>.frontpage.host/…");
         }
         const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
         const openerArgs = process.platform === "win32" ? ["/c", "start", "", url] : [url];
         spawn(opener, openerArgs, { detached: true, stdio: "ignore" }).unref();
         if (isJson()) {
-            emitOk("open", { slug, url, prodRequested: prod, prodNoOp: true });
+            emitOk("open", { slug, url, path, prodRequested: prod, prodNoOp: true });
         }
         else {
             console.log(url);
@@ -25,7 +59,7 @@ export async function runOpen(args) {
     }
     catch (err) {
         if (err instanceof Error && err.message.includes("Usage")) {
-            return emitUsage("open", "Usage: frontpage open [--site <slug>] [--prod]", EXIT_USAGE);
+            return emitUsage("open", "Usage: frontpage open [/path|--path /path] [--site <slug>] [--prod]", EXIT_USAGE);
         }
         return emitErr("open", err);
     }

package/dist/commands/prompt-attach.d.ts

@@ -1,8 +1,10 @@
-/** Mirror ATTACH_LIMITS in src/lib/agent/attachments.ts (images/docs/text only via proxy media). */
+import { type UploadedMedia } from "../media/upload.js";
+/** Mirror ATTACH_LIMITS in src/lib/agent/attachments.ts. */
 export declare const CLI_ATTACH_LIMITS: {
     readonly maxImages: 6;
     readonly maxDocuments: 4;
     readonly maxTextFiles: 6;
+    readonly maxVideos: 3;
 };
 export type PromptAttachmentsPayload = {
     images: Array<{
@@ -17,19 +19,19 @@ export type PromptAttachmentsPayload = {
         name: string;
         content: string;
     }>;
+    videos: Array<{
+        url: string;
+        name?: string;
+        sizeBytes?: number;
+    }>;
 };
-export type MediaUploadResult = {
-    kind: string;
-    url?: string;
-    key?: string;
-    filename?: string;
-    sizeBytes?: number;
-    content?: string;
-};
+export type MediaUploadResult = UploadedMedia;
 export declare function emptyAttachments(): PromptAttachmentsPayload;
 export declare function isHttpsUrl(s: string): boolean;
 export declare function isMediaSitePath(s: string): boolean;
-export declare function classifyRemoteByName(nameOrUrl: string): "image" | "document";
+export declare function classifyRemoteByName(nameOrUrl: string): "image" | "document" | "video";
+/** Agent normalizeAttachments only keeps videos on our Blob host under uploads/. */
+export declare function isFrontpageBlobUploadUrl(url: string): boolean;
 export declare function addHttpsRef(out: PromptAttachmentsPayload, url: string, opts?: {
     name?: string;
     asImageOnly?: boolean;

package/dist/commands/prompt-attach.js

@@ -1,19 +1,21 @@
 /**
- * §CLI Phase C — resolve --attach / --asset-url into the agent attachments payload.
- * Local files upload via the same multipart media endpoint as `frontpage media upload`.
+ * §CLI Phase C (+ E) — resolve --attach / --asset-url into the agent attachments payload.
+ * Local files use the same transport matrix as `frontpage media upload`.
  */
-import { access, readFile } from "node:fs/promises";
-import { basename } from "node:path";
+import { access } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
-import { v1Get, v1PostMultipart, CliHttpError, EXIT_USAGE, EXIT_UNEXPECTED } from "../http/client.js";
-/** Mirror ATTACH_LIMITS in src/lib/agent/attachments.ts (images/docs/text only via proxy media). */
+import { v1Get, CliHttpError, EXIT_USAGE, EXIT_UNEXPECTED } from "../http/client.js";
+import { uploadLocalMedia } from "../media/upload.js";
+import { VIDEO_UPLOAD_EXT, extOf } from "../media/limits.js";
+/** Mirror ATTACH_LIMITS in src/lib/agent/attachments.ts. */
 export const CLI_ATTACH_LIMITS = {
     maxImages: 6,
     maxDocuments: 4,
     maxTextFiles: 6,
+    maxVideos: 3,
 };
 export function emptyAttachments() {
-    return { images: [], documents: [], textFiles: [] };
+    return { images: [], documents: [], textFiles: [], videos: [] };
 }
 export function isHttpsUrl(s) {
     return /^https:\/\/[^\s]+$/i.test(s) && s.length <= 2048;
@@ -23,7 +25,9 @@ export function isMediaSitePath(s) {
 }
 export function classifyRemoteByName(nameOrUrl) {
     const base = nameOrUrl.split(/[?#]/)[0] ?? nameOrUrl;
-    const ext = base.includes(".") ? (base.split(".").pop() ?? "").toLowerCase() : "";
+    const ext = extOf(base);
+    if (VIDEO_UPLOAD_EXT.has(ext))
+        return "video";
     if (ext === "pdf")
         return "document";
     return "image";
@@ -42,6 +46,19 @@ function pushText(list, name, content) {
     }
     list.push({ name, content });
 }
+/** Agent normalizeAttachments only keeps videos on our Blob host under uploads/. */
+export function isFrontpageBlobUploadUrl(url) {
+    try {
+        const u = new URL(url);
+        if (!u.hostname.endsWith(".blob.vercel-storage.com"))
+            return false;
+        const pathname = u.pathname.replace(/^\/+/, "");
+        return pathname.startsWith("uploads/");
+    }
+    catch {
+        return false;
+    }
+}
 export function addHttpsRef(out, url, opts) {
     if (!isHttpsUrl(url)) {
         throw new CliHttpError(`Not an https URL: ${url}`, EXIT_USAGE, 400, "bad_request");
@@ -49,10 +66,16 @@ export function addHttpsRef(out, url, opts) {
     const kind = opts?.asImageOnly ? "image" : classifyRemoteByName(opts?.name ?? url);
     if (kind === "document") {
         pushUniqueUrl(out.documents, CLI_ATTACH_LIMITS.maxDocuments, url, opts?.name, "document");
+        return;
     }
-    else {
-        pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, url, opts?.name, "image");
+    if (kind === "video") {
+        if (!isFrontpageBlobUploadUrl(url)) {
+            throw new CliHttpError("Video --attach URLs must be Frontpage Blob uploads (…blob.vercel-storage.com/uploads/…). Upload with frontpage media upload first, or pass a local .mp4/.webm/.mov file.", EXIT_USAGE, 400, "bad_request");
+        }
+        pushUniqueUrl(out.videos, CLI_ATTACH_LIMITS.maxVideos, url, opts?.name, "video");
+        return;
     }
+    pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, url, opts?.name, "image");
 }
 export function addUploadResult(out, data) {
     const name = data.filename?.trim() || undefined;
@@ -63,19 +86,31 @@ export function addUploadResult(out, data) {
         pushText(out.textFiles, name ?? "snippet.txt", data.content);
         return;
     }
-    if (data.kind === "image" || data.kind === "document") {
+    if (data.kind === "image" || data.kind === "document" || data.kind === "video") {
         if (!data.url || !isHttpsUrl(data.url)) {
             throw new CliHttpError(`Upload of ${name ?? "file"} did not return a Blob URL.`, EXIT_UNEXPECTED, 500, "internal");
         }
         if (data.kind === "document") {
             pushUniqueUrl(out.documents, CLI_ATTACH_LIMITS.maxDocuments, data.url, name, "document");
+            return;
         }
-        else {
-            pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, data.url, name, "image");
+        if (data.kind === "video") {
+            if (out.videos.length >= CLI_ATTACH_LIMITS.maxVideos) {
+                throw new CliHttpError(`Too many video attachments (max ${CLI_ATTACH_LIMITS.maxVideos}).`, EXIT_USAGE, 400, "bad_request");
+            }
+            if (!out.videos.some((x) => x.url === data.url)) {
+                out.videos.push({
+                    url: data.url,
+                    name,
+                    sizeBytes: data.sizeBytes,
+                });
+            }
+            return;
         }
+        pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, data.url, name, "image");
         return;
     }
-    throw new CliHttpError(`Unsupported upload kind "${data.kind}" for prompt attach. Use images, PDFs, or text/code files (video/large files need the editor path until Phase E).`, EXIT_USAGE, 400, "bad_request");
+    throw new CliHttpError(`Unsupported upload kind "${data.kind}" for prompt attach. Use images, PDFs, videos, or text/code files.`, EXIT_USAGE, 400, "bad_request");
 }
 export async function uploadLocalForAttach(slug, filePath) {
     try {
@@ -84,13 +119,7 @@ export async function uploadLocalForAttach(slug, filePath) {
     catch {
         throw new CliHttpError(`Cannot read file for --attach: ${filePath}`, EXIT_USAGE, 400, "bad_request");
     }
-    const bytes = await readFile(filePath);
-    if (bytes.length === 0) {
-        throw new CliHttpError(`File is empty: ${filePath}`, EXIT_USAGE, 400, "bad_request");
-    }
-    const form = new FormData();
-    form.append("file", new Blob([Uint8Array.from(bytes)]), basename(filePath));
-    return v1PostMultipart(`/api/v1/sites/${encodeURIComponent(slug)}/media`, form);
+    return uploadLocalMedia({ slug, filePath });
 }
 export async function resolveSitePathUrl(slug, sitePath) {
     const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/media`);
@@ -123,6 +152,9 @@ export async function resolveAttachRef(slug, ref, out) {
         if (kind === "document") {
             pushUniqueUrl(out.documents, CLI_ATTACH_LIMITS.maxDocuments, asset.url, asset.name, "document");
         }
+        else if (kind === "video") {
+            pushUniqueUrl(out.videos, CLI_ATTACH_LIMITS.maxVideos, asset.url, asset.name, "video");
+        }
         else {
             pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, asset.url, asset.name, "image");
         }
@@ -143,7 +175,8 @@ export async function buildPromptAttachments(args) {
     }
     if (out.images.length === 0 &&
         out.documents.length === 0 &&
-        out.textFiles.length === 0) {
+        out.textFiles.length === 0 &&
+        out.videos.length === 0) {
         throw new CliHttpError("No attachments could be resolved from --attach / --asset-url.", EXIT_USAGE, 400, "bad_request");
     }
     return out;

package/dist/commands/prompt.js

@@ -29,6 +29,7 @@ export async function runPrompt(args) {
                         images: attachments.images.length,
                         documents: attachments.documents.length,
                         textFiles: attachments.textFiles.length,
+                        videos: attachments.videos.length,
                     }
                     : undefined,
             });
@@ -40,7 +41,8 @@ export async function runPrompt(args) {
             if (attachments) {
                 const n = attachments.images.length +
                     attachments.documents.length +
-                    attachments.textFiles.length;
+                    attachments.textFiles.length +
+                    attachments.videos.length;
                 console.error(`(attached ${n} file${n === 1 ? "" : "s"})`);
             }
         }

package/dist/commands/search.js

@@ -1,21 +1,8 @@
 import { resolveSlug } from "../site.js";
 import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get } from "../http/client.js";
+import { assertNoUnknownFlags, hasFlag, takeFlag } from "../argv.js";
 import { emitErr, emitOk, isJson } from "../runtime.js";
-function takeFlag(rest, name) {
-    const i = rest.indexOf(name);
-    if (i === -1)
-        return undefined;
-    const v = rest[i + 1];
-    rest.splice(i, 2);
-    return v;
-}
-function hasFlag(rest, name) {
-    const i = rest.indexOf(name);
-    if (i === -1)
-        return false;
-    rest.splice(i, 1);
-    return true;
-}
+const SEARCH_USAGE = "Usage: frontpage search <pattern> [path|--path <path>] [--regex] [--case-sensitive] [--whole-word] [--files-only] [--context-lines N] [--max-results N] [--site <slug>]";
 export async function runSearch(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
@@ -26,12 +13,21 @@ export async function runSearch(args) {
         const filesOnly = hasFlag(work, "--files-only");
         const contextLines = takeFlag(work, "--context-lines");
         const maxResults = takeFlag(work, "--max-results");
-        const pattern = work[0];
+        const pathFlag = takeFlag(work, "--path");
+        const pattern = work.shift();
         if (!pattern) {
-            console.error("Usage: frontpage search <pattern> [path] [--regex] [--case-sensitive] [--whole-word] [--files-only] [--context-lines N] [--max-results N] [--site <slug>]");
+            console.error(SEARCH_USAGE);
+            return EXIT_USAGE;
+        }
+        let pathFilter = pathFlag;
+        if (pathFilter === undefined && work[0] && !work[0].startsWith("-")) {
+            pathFilter = work.shift();
+        }
+        assertNoUnknownFlags(work, "search");
+        if (work.length > 0) {
+            console.error(`Unexpected argument: ${work[0]}\n${SEARCH_USAGE}`);
             return EXIT_USAGE;
         }
-        const pathFilter = work[1] && !work[1].startsWith("-") ? work[1] : undefined;
         const q = new URLSearchParams({ pattern });
         if (pathFilter)
             q.set("path", pathFilter);

package/dist/commands/seo.js

@@ -1,27 +1,39 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1Post } from "../http/client.js";
-function takeFlag(rest, name) {
-    const i = rest.indexOf(name);
-    if (i === -1)
-        return undefined;
-    const v = rest[i + 1];
-    rest.splice(i, 2);
-    return v;
+import { CliHttpError, EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1Post } from "../http/client.js";
+import { assertNoUnknownFlags, takeFlag } from "../argv.js";
+import { emitErr, isJson } from "../runtime.js";
+function resolveSeoPath(work) {
+    const fromFlag = takeFlag(work, "--path");
+    if (fromFlag !== undefined) {
+        if (!fromFlag.startsWith("/") || fromFlag.startsWith("//")) {
+            throw new CliHttpError("SEO path must start with / (e.g. / or /about).", EXIT_USAGE, 0, "bad_request");
+        }
+        return fromFlag;
+    }
+    const positional = work.find((a) => a.startsWith("/") && !a.startsWith("//"));
+    if (positional) {
+        const i = work.indexOf(positional);
+        work.splice(i, 1);
+        return positional;
+    }
+    return "/";
 }
 export async function runSeo(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
         const sub = rest[0];
-        if (!sub || sub === "get") {
-            const pathArgs = rest[0] === "get" ? rest.slice(1) : rest;
-            const path = pathArgs[0] ?? "/";
+        // `seo`, `seo get`, `seo get /path`, `seo get --path /path`, `seo --path /path`
+        if (!sub || sub === "get" || sub === "--path" || (sub.startsWith("/") && !sub.startsWith("//"))) {
+            const work = sub === "get" ? rest.slice(1) : [...rest];
+            const path = resolveSeoPath(work);
+            assertNoUnknownFlags(work, "seo");
             const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/seo?path=${encodeURIComponent(path)}`);
             console.log(JSON.stringify(data, null, 2));
             return EXIT_OK;
         }
         if (sub === "set") {
             const work = rest.slice(1);
-            const path = takeFlag(work, "--path") ?? work.find((a) => a.startsWith("/")) ?? "/";
+            const path = resolveSeoPath(work);
             const body = { path };
             for (const field of [
                 "title",
@@ -39,6 +51,7 @@ export async function runSeo(args) {
             if (noindex !== undefined) {
                 body.noindex = noindex === "true" || noindex === "1";
             }
+            assertNoUnknownFlags(work, "seo");
             if (Object.keys(body).length <= 1) {
                 console.error("Usage: frontpage seo set --path / [--title …] [--description …] [--ogImage …] [--noindex true|false]");
                 return EXIT_USAGE;
@@ -47,10 +60,12 @@ export async function runSeo(args) {
             console.log(JSON.stringify(data, null, 2));
             return EXIT_OK;
         }
-        console.error("Usage: frontpage seo get|set … [--site <slug>]");
+        console.error("Usage: frontpage seo get [/path|--path /path] | seo set --path / [--title …] [--site <slug>]");
         return EXIT_USAGE;
     }
     catch (err) {
+        if (isJson())
+            return emitErr("seo", err);
         console.error(err instanceof Error ? err.message : String(err));
         return exitCodeForError(err);
     }

package/dist/commands/version.d.ts

@@ -0,0 +1 @@
+export declare function runVersion(): number;

package/dist/commands/version.js

@@ -0,0 +1,13 @@
+import { EXIT_OK } from "../http/client.js";
+import { emitOk, isJson } from "../runtime.js";
+import { packageIdentity, versionLine } from "../version.js";
+export function runVersion() {
+    const identity = packageIdentity();
+    if (isJson()) {
+        emitOk("version", identity);
+    }
+    else {
+        console.log(versionLine());
+    }
+    return EXIT_OK;
+}

package/dist/flags.d.ts

@@ -1,6 +1,6 @@
 /**
  * Strip global flags from argv. Safe to call before command dispatch.
- * Recognizes --json, --quiet, --yes, and help aliases anywhere in the list.
+ * Recognizes --json, --quiet, --yes, --version/-V, and help aliases anywhere in the list.
  */
 export type GlobalFlags = {
     json: boolean;
@@ -8,6 +8,8 @@ export type GlobalFlags = {
     yes: boolean;
     /** True when argv asked for help (--help / -h), not the `help` command itself. */
     wantsHelp: boolean;
+    /** True when argv asked for version (--version / -V). */
+    wantsVersion: boolean;
     args: string[];
 };
 export declare function parseGlobalFlags(argv: string[]): GlobalFlags;