frontpage-host 0.1.9 → 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: `frontpage media upload <file>` — images/PDF ≤25 MB, video (MP4/WebM/MOV) ≤50 MB, SVG/text ≤4 MB (sanitizing proxy). Use returned `sitePath` (`/__media/uploads/<slug>/…`) in markup — never raw blob hosts. Optional `?w=` on rasters only.
+- 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
@@ -180,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
 
@@ -191,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

@@ -34,12 +34,13 @@ export async function runMedia(args) {
                 console.log(`Inline text (${data.filename}): ${data.sizeBytes ?? 0} bytes — not stored.`);
                 return EXIT_OK;
             }
-            if (data.url)
-                console.log(data.url);
+            // 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>] [--json]");

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/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;

package/dist/flags.js

@@ -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 function parseGlobalFlags(argv) {
     const args = [];
@@ -8,6 +8,7 @@ export function parseGlobalFlags(argv) {
     let quiet = false;
     let yes = false;
     let wantsHelp = false;
+    let wantsVersion = false;
     for (const a of argv) {
         if (a === "--json") {
             json = true;
@@ -25,7 +26,11 @@ export function parseGlobalFlags(argv) {
             wantsHelp = true;
             continue;
         }
+        if (a === "--version" || a === "-V") {
+            wantsVersion = true;
+            continue;
+        }
         args.push(a);
     }
-    return { json, quiet, yes, wantsHelp, args };
+    return { json, quiet, yes, wantsHelp, wantsVersion, args };
 }

package/dist/media/upload.js

@@ -124,7 +124,8 @@ export async function uploadLocalMedia(args) {
         headBytes: bytes.subarray(0, 4096),
     });
     if (decision.transport === "reject") {
-        throw new CliHttpError(decision.message, EXIT_USAGE, 400, "bad_request");
+        // Local validation only — omit httpStatus (status 0) and never invent requestId (R10).
+        throw new CliHttpError(decision.message, EXIT_USAGE, 0, "bad_request");
     }
     if (decision.transport === "client") {
         return uploadViaClient({

package/dist/registry.js

@@ -26,6 +26,13 @@ export const COMMANDS = [
             "frontpage help --json",
         ],
     },
+    {
+        name: "version",
+        summary: "Print frontpage-host package version",
+        usage: "frontpage version | frontpage --version | frontpage -V",
+        examples: ["frontpage --version", "frontpage version --json"],
+        flags: ["Also available as global --version / -V"],
+    },
     {
         name: "login",
         summary: "Save an API key to the OS keychain",
@@ -133,15 +140,21 @@ export const COMMANDS = [
     {
         name: "search",
         summary: "Search remote text files",
-        usage: "frontpage search <pattern> [path] [--regex] [--case-sensitive] [--whole-word] [--files-only] [--context-lines N] [--max-results N] [--site <slug>] [--json]",
+        usage: "frontpage search <pattern> [path|--path <path>] [--regex] [--case-sensitive] [--whole-word] [--files-only] [--context-lines N] [--max-results N] [--site <slug>] [--json]",
         topics: ["sync"],
+        examples: [
+            "frontpage search Subscribe src/pages",
+            "frontpage search Subscribe --path src/pages",
+        ],
         flags: [
+            "--path <prefix> (alias for positional path filter; flag wins if both present)",
             "--regex",
             "--case-sensitive",
             "--whole-word",
             "--files-only",
             "--context-lines <n>",
             "--max-results <n>",
+            "Unknown leftover flags fail closed (exit 2)",
         ],
     },
     {
@@ -184,9 +197,13 @@ export const COMMANDS = [
     {
         name: "open",
         summary: "Open the site subdomain in a browser",
-        usage: "frontpage open [--site <slug>] [--prod]",
+        usage: "frontpage open [/path|--path /path] [--site <slug>] [--prod]",
         topics: ["sync"],
-        flags: ["--prod is a no-op stub today — always opens https://<slug>.frontpage.host/"],
+        examples: ["frontpage open", "frontpage open /updates", "frontpage open --path /pricing"],
+        flags: [
+            "Optional site-relative path appended to https://<slug>.frontpage.host",
+            "--prod is a no-op stub today — still opens the *.frontpage.host subdomain",
+        ],
     },
     {
         name: "prompt",
@@ -326,7 +343,8 @@ export const COMMANDS = [
         ],
         flags: [
             "Auto-selects proxy (≤4 MB) vs direct-to-Blob for large rasters/PDFs and all video",
-            "Prints sitePath (/__media/uploads/<slug>/…) for markup — never raw blob hosts in pages",
+            "Human success: sitePath first (markup-safe), then url: (blob URL for debugging)",
+            "Use sitePath (/__media/uploads/<slug>/…) in markup — never raw blob hosts in pages",
             "SVG stays on the sanitizing proxy path (≤4 MB)",
         ],
         seeAlso: ["prompt", "help content", "help site-building"],
@@ -341,8 +359,14 @@ export const COMMANDS = [
     {
         name: "seo",
         summary: "Get or set page SEO",
-        usage: "frontpage seo get|set --path / [--title …] [--description …] [--site <slug>]",
+        usage: "frontpage seo get [/path|--path /path] | seo set --path / [--title …] [--description …] [--site <slug>]",
         topics: ["content"],
+        examples: [
+            "frontpage seo get /",
+            "frontpage seo get --path /updates",
+            "frontpage seo set --path / --title \"Home\"",
+        ],
+        flags: ["get accepts positional path or --path (flag wins); unknown leftover flags fail closed"],
     },
     {
         name: "articles",
@@ -447,8 +471,8 @@ export const TOPICS = {
   frontpage push [--message …] [--wait]   # uploads allowlisted files; CAS + active-run guard
   frontpage ls [prefix]
   frontpage cat <path>
-  frontpage search <pattern> [path] [--regex] [--case-sensitive] [--whole-word] [--files-only]
-  frontpage open                 # opens https://<slug>.frontpage.host/ (--prod is a no-op stub)
+  frontpage search <pattern> [path|--path <path>] [--regex] [--case-sensitive] [--whole-word] [--files-only]
+  frontpage open [/path]         # opens https://<slug>.frontpage.host[/path] (--prod is a no-op stub)
 
   Local state: .frontpage/state.json { slug, baseCommitSha }
   Pull BEFORE EDITING when tip may have moved (UI agent / another checkout) — check tipDrift.
@@ -520,14 +544,14 @@ export const TOPICS = {
   frontpage extensions
 
   --attach uploads via media (images/PDF/video/text) or accepts /__media/… / https URLs.
-  API errors include requestId in --json error envelopes (and stderr when not --json).
+  API errors include requestId in --json envelopes when the server returned one; local validation errors omit requestId and httpStatus.
   Mid-task continuation is automatic — there is no runs continue.
   Do not file-sync while an agent run is active (see help sync for push --wait).
   Default after work: review https://<subdomain>.frontpage.host; do not publish.`,
     content: `Content
-  frontpage media list|upload <file>   # images/PDF ≤25 MB, video ≤50 MB; sitePath for markup
+  frontpage media list|upload <file>   # images/PDF ≤25 MB, video ≤50 MB; human prints sitePath first
   frontpage inbox [leads|subscribers|orders|…] [--mark-read] [--csv]
-  frontpage seo get|set --path /
+  frontpage seo get [/path|--path /path] | seo set --path /
   frontpage articles list|content|create-section|create-article|set-draft|…
   frontpage fonts [list|search] [--slot …] [--query …]
   frontpage tokens set --group … --key … --value …
@@ -573,7 +597,8 @@ export const TOPICS = {
     { "ok": true, "command": "…", "data": {…} }
     { "ok": false, "command": "…", "error": { "message", "code?", "httpStatus?", "exitCode", "requestId?" }, "data"? }
   Failures with --json still use the process exit code; envelope is on stdout.
-  Prefer requestId from error envelopes when filing support issues.`,
+  requestId is present only when the API returned one — local CLI validation (e.g. media size/type reject) omits requestId and httpStatus.
+  Prefer requestId from API error envelopes when filing support issues.`,
 };
 export function findCommand(name) {
     return COMMANDS.find((c) => c.name === name);

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/** Read package identity from frontpage-host package.json (works from dist/). */
+export declare function packageIdentity(): {
+    name: string;
+    version: string;
+};
+/** Human one-liner: `frontpage-host 0.1.10`. */
+export declare function versionLine(): string;

package/dist/version.js

@@ -0,0 +1,15 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+/** Read package identity from frontpage-host package.json (works from dist/). */
+export function packageIdentity() {
+    const pkg = require("../package.json");
+    return {
+        name: pkg.name ?? "frontpage-host",
+        version: pkg.version ?? "0.0.0",
+    };
+}
+/** Human one-liner: `frontpage-host 0.1.10`. */
+export function versionLine() {
+    const { name, version } = packageIdentity();
+    return `${name} ${version}`;
+}

package/llms.txt

@@ -10,9 +10,11 @@
 - Search flags: --regex --case-sensitive --whole-word --files-only --context-lines --max-results
 - Modules setup: frontpage modules request-setup <key> --reason "…" (owner status bar; CLI cannot show it)
 - Analytics ops: frontpage analytics summary|query|funnel|timeseries|compare|sql (bare analytics = dashboard)
-- Media: frontpage media upload <file> (images/PDF ≤25 MB, video ≤50 MB, SVG/text ≤4 MB); use sitePath /__media/uploads/<slug>/… in markup
+- Media: frontpage media upload <file> (images/PDF ≤25 MB, video ≤50 MB, SVG/text ≤4 MB); human prints sitePath first — use /__media/uploads/<slug>/… in markup
 - Prompt attachments: frontpage prompt "…" --attach <file|/__media/…|https://…> [--asset-url https://…] (same media caps as media upload)
-- Errors: --json error envelopes include requestId; runs wait failed/canceled → ok:false + run.error (exit 2); deploy wait fail-closed; push --wait
+- Version: frontpage --version | -V | version
+- SEO get: frontpage seo get [/path|--path /path]; search path filter: [path|--path <path>]; open [/path|--path /path]
+- Errors: --json API envelopes include requestId when the server returned one; local validation omits requestId/httpStatus; runs wait failed/canceled → ok:false + run.error (exit 2); deploy wait fail-closed; push --wait
 - Auth: mint fp_live_ key in Frontpage UI (Developers); frontpage login KEY or FRONTPAGE_API_KEY
 - Site id: subdomain only (frontpage use <subdomain>). Not custom domains.
 - Staging: https://<subdomain>.frontpage.host — push/prompt/edit update staging; no separate staging deploy step for agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontpage-host",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {