frontpage-host 0.1.10 → 0.1.11

package/AGENTS.md

@@ -29,15 +29,16 @@ Frontpage has two surfaces:
 **How changes become visible on staging**
 
 - `frontpage push`, `frontpage prompt`, and `frontpage edit` update the site branch and the **staging** surface.
-- After a push or agent run finishes building, changes are visible at `https://<subdomain>.frontpage.host`.
+- After a push or agent run finishes building, changes are on the site branch behind `https://<subdomain>.frontpage.host`.
 - There is **no separate “deploy to staging” step** agents must run. Do not treat `frontpage deploy wait` as “going live.” At most it waits for an in-flight build to finish before you open the subdomain to review.
 - `frontpage open` opens the subdomain staging URL.
+- **Custom-domain caveat:** `<subdomain>.frontpage.host` is publicly viewable (anonymous) only when the site has **no** custom domain and subdomain sharing is public. If a custom domain is connected (e.g. `arbiter.wiki`), the subdomain is often **owner-private** — an unauthenticated browser/curl may see the app login page. That login wall is **not** a failed push. Anonymous public review is then on the **published custom domain**; editing the subdomain still needs an owner browser session (CLI API key ≠ browser cookie).
 
 **Production publish is a deliberate promote**
 
 - `frontpage publish` copies the current **staging tip** to **production** (custom domain / published site).
 - **Never run `publish` or `unpublish` unless the user explicitly asked**, or the user’s own automation/workflow clearly requires autonomous publishing.
-- Default: finish work on staging, tell the user to review `https://<subdomain>.frontpage.host`, and let **them** publish (or ask you to publish after they approve).
+- Default: finish work on staging, tell the user to review the staging subdomain when it is publicly shareable (see custom-domain caveat above), and let **them** publish (or ask you to publish after they approve).
 
 ## Non-interactive auth
 
@@ -112,7 +113,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). Human output prints `sitePath:` first (use that in markup — never raw blob hosts), then optional `url:`. 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. **Text/CSV** uploads are inline only — **not** added to the media library and **cannot** be linked via `/__media` (`media upload --json` omits full `content`; use `inbox … --csv` for submission exports).
 - Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for structured reads (SQL is guard + RLS site-scoped).
 
 ## Agent prompt loop

package/dist/commands/analytics.d.ts

@@ -1 +1,8 @@
+/**
+ * Funnel --steps: JSON array (canonical) or comma-separated site paths (R9).
+ * Example shorthand: `--steps /, /problems, /updates`
+ */
+export declare function parseFunnelSteps(raw: string): Array<{
+    path: string;
+}>;
 export declare function runAnalytics(args: string[]): Promise<number>;

package/dist/commands/analytics.js

@@ -1,24 +1,48 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1Post } from "../http/client.js";
+import { CliHttpError, EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1Post } from "../http/client.js";
+import { assertNoUnknownFlags, 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 parseJsonFlag(raw, label) {
     if (raw === undefined)
         return undefined;
     try {
         return JSON.parse(raw);
     }
-    catch {
-        throw new Error(`${label} must be valid JSON`);
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new CliHttpError(`Invalid JSON for ${label}: ${detail}`, EXIT_USAGE, 0, "bad_request");
     }
 }
+/**
+ * Funnel --steps: JSON array (canonical) or comma-separated site paths (R9).
+ * Example shorthand: `--steps /, /problems, /updates`
+ */
+export function parseFunnelSteps(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        throw new CliHttpError(`Usage: frontpage analytics funnel --steps '[{"path":"/"},{"path":"/pricing"}]' or --steps /, /pricing`, EXIT_USAGE, 0, "bad_request");
+    }
+    if (trimmed.startsWith("[")) {
+        const parsed = parseJsonFlag(trimmed, "--steps");
+        if (!Array.isArray(parsed)) {
+            throw new CliHttpError("Invalid JSON for --steps: expected an array of { path } objects", EXIT_USAGE, 0, "bad_request");
+        }
+        return parsed;
+    }
+    const paths = trimmed
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (paths.length === 0) {
+        throw new CliHttpError("Invalid --steps: provide a JSON array or comma-separated paths like /, /pricing", EXIT_USAGE, 0, "bad_request");
+    }
+    for (const path of paths) {
+        if (!path.startsWith("/") || path.startsWith("//")) {
+            throw new CliHttpError(`Invalid funnel step path "${path}" — each step must be a site-relative path starting with /`, EXIT_USAGE, 0, "bad_request");
+        }
+    }
+    return paths.map((path) => ({ path }));
+}
 function rangeFields(work) {
     const days = takeFlag(work, "--days");
     const from = takeFlag(work, "--from");
@@ -35,6 +59,12 @@ function rangeFields(work) {
 function printJson(data) {
     console.log(JSON.stringify(data, null, 2));
 }
+function finishWork(work) {
+    assertNoUnknownFlags(work, "analytics");
+    if (work.length > 0) {
+        throw new CliHttpError(`Unexpected argument: ${work[0]}. Run: frontpage help analytics`, EXIT_USAGE, 0, "bad_request");
+    }
+}
 export async function runAnalytics(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
@@ -42,10 +72,11 @@ export async function runAnalytics(args) {
         const sub = work[0];
         const ops = new Set(["summary", "query", "funnel", "timeseries", "compare", "sql", "dashboard"]);
         // Bare `analytics` or `analytics dashboard` → legacy GET dashboard (compat).
-        if (!sub || sub === "dashboard" || !ops.has(sub) && sub.startsWith("--")) {
+        if (!sub || sub === "dashboard" || (!ops.has(sub) && sub.startsWith("--"))) {
             if (sub === "dashboard")
                 work.shift();
             const days = takeFlag(work, "--days") ?? "7";
+            finishWork(work);
             const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/analytics?days=${encodeURIComponent(days)}`);
             if (isJson()) {
                 emitOk("analytics", data);
@@ -63,6 +94,7 @@ export async function runAnalytics(args) {
         if (sub === "summary") {
             const filters = parseJsonFlag(takeFlag(work, "--filters"), "--filters");
             const body = { op: "summary", ...rangeFields(work), ...(filters ? { filters } : {}) };
+            finishWork(work);
             const data = await v1Post(base, body);
             if (isJson())
                 emitOk("analytics", data);
@@ -87,6 +119,7 @@ export async function runAnalytics(args) {
                 ...(limit ? { limit: Number(limit) } : {}),
                 ...(filters ? { filters } : {}),
             };
+            finishWork(work);
             const data = await v1Post(base, body);
             if (isJson())
                 emitOk("analytics", data);
@@ -95,13 +128,21 @@ export async function runAnalytics(args) {
             return EXIT_OK;
         }
         if (sub === "funnel") {
-            const stepsRaw = takeFlag(work, "--steps");
+            let stepsRaw = takeFlag(work, "--steps");
             if (!stepsRaw) {
-                console.error(`Usage: frontpage analytics funnel --steps '[{"path":"/"},{"path":"/pricing"}]' [--days N]`);
+                console.error(`Usage: frontpage analytics funnel --steps '[{"path":"/"},{"path":"/pricing"}]' [--days N]\n` +
+                    `   or: frontpage analytics funnel --steps /, /pricing, /updates [--days N]`);
                 return EXIT_USAGE;
             }
-            const steps = parseJsonFlag(stepsRaw, "--steps");
+            // Shell splits `--steps /, /pricing` into multiple argv tokens; reassemble path list.
+            if (!stepsRaw.trim().startsWith("[")) {
+                while (work[0] && work[0].startsWith("/") && !work[0].startsWith("//")) {
+                    stepsRaw = `${stepsRaw},${work.shift()}`;
+                }
+            }
+            const steps = parseFunnelSteps(stepsRaw);
             const body = { op: "funnel", steps, ...rangeFields(work) };
+            finishWork(work);
             const data = await v1Post(base, body);
             if (isJson())
                 emitOk("analytics", data);
@@ -120,6 +161,7 @@ export async function runAnalytics(args) {
                 ...(interval ? { interval } : {}),
                 ...(filters ? { filters } : {}),
             };
+            finishWork(work);
             const data = await v1Post(base, body);
             if (isJson())
                 emitOk("analytics", data);
@@ -144,6 +186,7 @@ export async function runAnalytics(args) {
                 ...rangeFields(work),
                 ...(metric ? { metric } : {}),
             };
+            finishWork(work);
             const data = await v1Post(base, body);
             if (isJson())
                 emitOk("analytics", data);
@@ -152,7 +195,16 @@ export async function runAnalytics(args) {
             return EXIT_OK;
         }
         if (sub === "sql") {
-            const sql = takeFlag(work, "--sql") ?? work.join(" ").trim();
+            const sqlFlag = takeFlag(work, "--sql");
+            const sql = sqlFlag ?? work.join(" ").trim();
+            if (sqlFlag) {
+                // Consumed via flag; reject leftover flags/args.
+                finishWork(work);
+            }
+            else if (sql) {
+                // Positional SQL consumed all remaining tokens.
+                work.length = 0;
+            }
             if (!sql) {
                 console.error('Usage: frontpage analytics sql --sql "SELECT path, count(*) FROM analytics_events GROUP BY 1"');
                 return EXIT_USAGE;

package/dist/commands/media.d.ts

@@ -1 +1,4 @@
+import { type UploadedMedia } from "../media/upload.js";
+/** Sanitize media --json payload: omit full text body (R5); keep content for prompt --attach path. */
+export declare function mediaJsonData(slug: string, data: UploadedMedia): Record<string, unknown>;
 export declare function runMedia(args: string[]): Promise<number>;

package/dist/commands/media.js

@@ -1,13 +1,47 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get } from "../http/client.js";
+import { assertNoUnknownFlags } from "../argv.js";
 import { emitErr, emitOk, isJson } from "../runtime.js";
 import { uploadLocalMedia } from "../media/upload.js";
-import { v1Get } from "../http/client.js";
+const TEXT_NOT_LIBRARY = "not added to the media library and cannot be linked via /__media. " +
+    "For form submission exports use inbox … --csv; large data files via the editor.";
+/** Sanitize media --json payload: omit full text body (R5); keep content for prompt --attach path. */
+export function mediaJsonData(slug, data) {
+    if (data.kind === "text") {
+        const content = data.content;
+        const contentBytes = data.sizeBytes ??
+            (typeof content === "string" ? Buffer.byteLength(content, "utf8") : 0);
+        const contentPreview = typeof content === "string"
+            ? content.length > 256
+                ? content.slice(0, 256)
+                : content
+            : undefined;
+        return {
+            slug,
+            kind: data.kind,
+            filename: data.filename,
+            sizeBytes: data.sizeBytes,
+            contentType: data.contentType,
+            transport: data.transport,
+            contentBytes,
+            contentPreview,
+            contentOmitted: true,
+            libraryAsset: false,
+        };
+    }
+    return { slug, ...data };
+}
 export async function runMedia(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
         const sub = rest[0] ?? "list";
         if (sub === "list" || sub === "ls") {
+            const work = rest.slice(1);
+            assertNoUnknownFlags(work, "media");
+            if (work.length > 0) {
+                console.error(`Unexpected argument: ${work[0]}\nUsage: frontpage media list [--site <slug>] [--json]`);
+                return EXIT_USAGE;
+            }
             const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/media`);
             if (isJson()) {
                 emitOk("media", { slug, ...data });
@@ -20,18 +54,24 @@ export async function runMedia(args) {
             return EXIT_OK;
         }
         if (sub === "upload") {
-            const filePath = rest[1];
+            const work = rest.slice(1);
+            const filePath = work.shift();
             if (!filePath) {
                 console.error("Usage: frontpage media upload <file> [--site <slug>] [--json]");
                 return EXIT_USAGE;
             }
+            assertNoUnknownFlags(work, "media");
+            if (work.length > 0) {
+                console.error(`Unexpected argument: ${work[0]}\nUsage: frontpage media upload <file> [--site <slug>] [--json]`);
+                return EXIT_USAGE;
+            }
             const data = await uploadLocalMedia({ slug, filePath });
             if (isJson()) {
-                emitOk("media", { slug, ...data });
+                emitOk("media", mediaJsonData(slug, data));
                 return EXIT_OK;
             }
             if (data.kind === "text") {
-                console.log(`Inline text (${data.filename}): ${data.sizeBytes ?? 0} bytes — not stored.`);
+                console.log(`Inline text (${data.filename}): ${data.sizeBytes ?? 0} bytes — ${TEXT_NOT_LIBRARY}`);
                 return EXIT_OK;
             }
             // Human mode: sitePath first so first-line copy/paste is markup-safe (R4).

package/dist/commands/modules.js

@@ -1,13 +1,6 @@
 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 { takeFlag } from "../argv.js";
 export async function runModules(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
@@ -22,7 +15,12 @@ export async function runModules(args) {
         if (sub === "docs" || sub === "doc") {
             const key = rest[1];
             if (!key) {
+                const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/modules`);
                 console.error("Usage: frontpage modules docs <key> [--instance <id>] [--site <slug>]");
+                console.error("Known modules (run: frontpage modules docs <key>):");
+                for (const m of data.modules) {
+                    console.error(`  ${m.key.padEnd(16)}  ${m.name}`);
+                }
                 return EXIT_USAGE;
             }
             const work = rest.slice(2);

package/dist/registry.js

@@ -294,12 +294,16 @@ export const COMMANDS = [
             "frontpage analytics summary --days 30",
             "frontpage analytics query --dimension path --measure count --limit 10",
             `frontpage analytics funnel --steps '[{"path":"/"},{"path":"/pricing"}]'`,
+            "frontpage analytics funnel --steps /, /pricing, /updates",
             "frontpage analytics timeseries --metric pageviews --interval day --days 14",
             `frontpage analytics compare --a '{"device":"mobile"}' --b '{"device":"desktop"}'`,
             'frontpage analytics sql --sql "SELECT path, count(*)::int AS n FROM analytics_events GROUP BY 1 ORDER BY n DESC LIMIT 10"',
         ],
         flags: [
             "Bare analytics / dashboard = legacy GET dashboard (compat)",
+            "funnel --steps accepts JSON array or comma-separated paths (/, /pricing)",
+            "Invalid JSON for --steps / --a / --b prints an explicit parse error (not bare Usage)",
+            "Unknown leftover flags fail closed (exit 2)",
             "Ops use POST …/analytics with allowlisted dimensions/measures; SQL is guard-validated + RLS",
         ],
     },
@@ -316,6 +320,7 @@ export const COMMANDS = [
         topics: ["agent", "content"],
         examples: [
             "frontpage modules docs forms",
+            "frontpage modules docs signups",
             "frontpage modules list",
             'frontpage modules request-setup payments --reason "You asked for a $50 deposit button — Stripe setup makes it live"',
         ],
@@ -345,7 +350,9 @@ export const COMMANDS = [
             "Auto-selects proxy (≤4 MB) vs direct-to-Blob for large rasters/PDFs and all video",
             "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",
+            "Text/CSV upload is inline only — not a media-library asset (no /__media link); --json omits full content",
             "SVG stays on the sanitizing proxy path (≤4 MB)",
+            "Unknown leftover flags fail closed (exit 2)",
         ],
         seeAlso: ["prompt", "help content", "help site-building"],
     },
@@ -446,7 +453,9 @@ export const TOPICS = {
   5. frontpage pull
   6. Edit files under src/, public/, or content/
   7. frontpage push --message "…"
-  8. Review https://<subdomain>.frontpage.host  (staging)
+  8. Review staging: https://<subdomain>.frontpage.host when that subdomain is publicly shareable.
+     With a custom domain connected, the subdomain is often owner-private (login wall ≠ failed push);
+     anonymous review is on the published custom domain after publish.
   9. frontpage publish             # ONLY if the user asked — promotes to production
 
   Staging is the subdomain. There is no separate staging-deploy step for agents.
@@ -547,15 +556,17 @@ export const TOPICS = {
   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.`,
+  Default after work: review staging on https://<subdomain>.frontpage.host when public;
+  with a custom domain, that subdomain may require an owner browser session (login wall ≠ failed deploy).
+  Do not publish unless asked.`,
     content: `Content
-  frontpage media list|upload <file>   # images/PDF ≤25 MB, video ≤50 MB; human prints sitePath first
+  frontpage media list|upload <file>   # images/PDF/video; text/CSV = inline not library; sitePath first when stored
   frontpage inbox [leads|subscribers|orders|…] [--mark-read] [--csv]
   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 …
-  frontpage modules list|docs|request-setup|enable|disable|archive|config <key>
+  frontpage modules list|docs|request-setup|enable|disable|archive|config <key>  # mailing list key: signups
   frontpage extensions list|docs|enable|disable|config <key>
   frontpage settings get|set
   frontpage edit --path / --old "…" --new "…"

package/llms.txt

@@ -10,14 +10,16 @@
 - 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); human prints sitePath first — use /__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. Text/CSV is inline only (not media library; --json omits full content).
 - Prompt attachments: frontpage prompt "…" --attach <file|/__media/…|https://…> [--asset-url https://…] (same media caps as media upload)
 - Version: frontpage --version | -V | version
 - SEO get: frontpage seo get [/path|--path /path]; search path filter: [path|--path <path>]; open [/path|--path /path]
+- Analytics funnel: --steps JSON array or comma paths (/, /pricing); bad JSON → Invalid JSON for --steps
+- Modules: unknown key errors list Known: …; mailing list module key is signups (not subscribe)
 - 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
+- Staging: https://<subdomain>.frontpage.host — push/prompt/edit update staging; no separate staging deploy step. With a custom domain, subdomain may be owner-private (login wall ≠ failed push); public review is published custom domain.
 - Production: custom domain after frontpage publish — NEVER publish/unpublish unless the user explicitly asks
 - Sync: allowlist src/ public/ content/; platform overlay + secret-like paths rejected; pull before edit if tip may have moved (status/diff tipDrift); pull → edit → diff (blobSha) → push [--wait] (CAS); no push during active agent run; UI agent does not use CLI pull; review on subdomain
 - Machine: global --json / --quiet; exit 0/2/3/4/5 (see help exit-codes)

package/package.json

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