frontpage-host 0.1.0 → 0.1.1

package/dist/commands/open.js

@@ -1,28 +1,32 @@
 import { spawn } from "node:child_process";
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE } from "../http/client.js";
+import { emitErr, emitOk, emitUsage, isJson, isQuiet } from "../runtime.js";
 export async function runOpen(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
         const prod = rest.includes("--prod") || args.includes("--prod");
-        const url = prod
-            ? `https://${slug}.frontpage.host/` // staging subdomain always; custom domain is gateway-resolved
-            : `https://${slug}.frontpage.host/`;
-        // Both staging editing and public subdomain use *.frontpage.host; --prod is reserved
-        // for a future production custom-domain lookup. For Phase 1 open the site subdomain.
-        void prod;
+        const url = `https://${slug}.frontpage.host/`;
+        // --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/");
+        }
         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();
-        console.log(url);
+        if (isJson()) {
+            emitOk("open", { slug, url, prodRequested: prod, prodNoOp: true });
+        }
+        else {
+            console.log(url);
+        }
         return EXIT_OK;
     }
     catch (err) {
         if (err instanceof Error && err.message.includes("Usage")) {
-            console.error("Usage: frontpage open [--site <slug>] [--prod]");
-            return EXIT_USAGE;
+            return emitUsage("open", "Usage: frontpage open [--site <slug>] [--prod]", EXIT_USAGE);
         }
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("open", err);
     }
 }

package/dist/commands/pages.js

@@ -1,16 +1,21 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, exitCodeForError, v1Get } from "../http/client.js";
+import { EXIT_OK, v1Get } from "../http/client.js";
+import { emitErr, emitOk, isJson } from "../runtime.js";
 export async function runPages(args) {
     try {
         const { slug } = await resolveSlug(args);
         const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/pages`);
-        for (const p of data.pages) {
-            console.log(`${p.path.padEnd(40)}  ${p.title}`);
+        if (isJson()) {
+            emitOk("pages", { slug, pages: data.pages });
+        }
+        else {
+            for (const p of data.pages) {
+                console.log(`${p.path.padEnd(40)}  ${p.title}`);
+            }
         }
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("pages", err);
     }
 }

package/dist/commands/prompt.js

@@ -1,5 +1,6 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Post } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, v1Post } from "../http/client.js";
+import { emitErr, emitOk, emitUsage, isJson } from "../runtime.js";
 export async function runPrompt(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
@@ -19,21 +20,23 @@ export async function runPrompt(args) {
         }
         const prompt = promptParts.join(" ").trim();
         if (!prompt) {
-            console.error('Usage: frontpage prompt "..." [--site <slug>] [--path /page]');
-            return EXIT_USAGE;
+            return emitUsage("prompt", 'Usage: frontpage prompt "..." [--site <slug>] [--path /page]', EXIT_USAGE);
         }
         if (!currentPath.startsWith("/")) {
-            console.error("currentPath must start with /");
-            return EXIT_USAGE;
+            return emitUsage("prompt", "currentPath must start with /", EXIT_USAGE);
         }
         const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs`, { prompt, currentPath });
-        console.log(data.runId);
-        if (data.coalesced)
-            console.error("(coalesced with an identical queued run)");
+        if (isJson()) {
+            emitOk("prompt", { slug, ...data });
+        }
+        else {
+            console.log(data.runId);
+            if (data.coalesced)
+                console.error("(coalesced with an identical queued run)");
+        }
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("prompt", err);
     }
 }

package/dist/commands/publish.js

@@ -1,28 +1,40 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, exitCodeForError, v1Delete, v1Post } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, v1Delete, v1Post } from "../http/client.js";
+import { emitErr, emitOk, emitUsage, isJson, requireYesOrTty } from "../runtime.js";
 export async function runPublish(args) {
     try {
         const { slug } = await resolveSlug(args);
         const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/publish`);
-        console.log(`Published ${slug}`);
-        if (data.productionUrl)
-            console.log(data.productionUrl);
+        if (isJson()) {
+            emitOk("publish", { slug, productionUrl: data.productionUrl ?? null });
+        }
+        else {
+            console.log(`Published ${slug}`);
+            if (data.productionUrl)
+                console.log(data.productionUrl);
+        }
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("publish", err);
     }
 }
 export async function runUnpublish(args) {
     try {
+        const refuse = requireYesOrTty("unpublish");
+        if (refuse)
+            return emitUsage("unpublish", refuse, EXIT_USAGE);
         const { slug } = await resolveSlug(args);
         await v1Delete(`/api/v1/sites/${encodeURIComponent(slug)}/publish`);
-        console.log(`Unpublished ${slug}`);
+        if (isJson()) {
+            emitOk("unpublish", { slug });
+        }
+        else {
+            console.log(`Unpublished ${slug}`);
+        }
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("unpublish", err);
     }
 }

package/dist/commands/pull.js

@@ -1,8 +1,9 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve, sep } from "node:path";
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_UNEXPECTED, exitCodeForError, v1Get } from "../http/client.js";
+import { EXIT_OK, EXIT_UNEXPECTED, v1Get } from "../http/client.js";
 import { readState, writeState } from "../state/frontpage-state.js";
+import { emitErr, emitOk, emitUsage, isJson } from "../runtime.js";
 /** Reject absolute / traversal paths before writing into cwd (defense in depth). */
 function assertSafePullPath(repoPath, cwd) {
     if (!repoPath ||
@@ -31,8 +32,7 @@ export async function runPull(args) {
                 abs = assertSafePullPath(file.path, cwd);
             }
             catch (err) {
-                console.error(err instanceof Error ? err.message : String(err));
-                return EXIT_UNEXPECTED;
+                return emitUsage("pull", err instanceof Error ? err.message : String(err), EXIT_UNEXPECTED);
             }
             await mkdir(dirname(abs), { recursive: true });
             if (file.encoding === "base64") {
@@ -45,16 +45,26 @@ export async function runPull(args) {
         }
         const prev = await readState(cwd);
         await writeState({ ...prev, slug: data.slug, baseCommitSha: data.baseCommitSha ?? undefined }, cwd);
-        console.log(`Pulled ${written} file(s) for ${data.slug}`);
-        if (data.baseCommitSha)
-            console.log(`baseCommitSha: ${data.baseCommitSha}`);
-        if (data.truncated)
-            console.log("Warning: pull truncated (file or size cap). Re-run or narrow the tree.");
-        console.log("Wrote .frontpage/state.json");
+        if (isJson()) {
+            emitOk("pull", {
+                slug: data.slug,
+                baseCommitSha: data.baseCommitSha,
+                written,
+                fileCount: data.fileCount,
+                truncated: data.truncated,
+            });
+        }
+        else {
+            console.log(`Pulled ${written} file(s) for ${data.slug}`);
+            if (data.baseCommitSha)
+                console.log(`baseCommitSha: ${data.baseCommitSha}`);
+            if (data.truncated)
+                console.log("Warning: pull truncated (file or size cap). Re-run or narrow the tree.");
+            console.log("Wrote .frontpage/state.json");
+        }
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("pull", err);
     }
 }

package/dist/commands/push.js

@@ -1,8 +1,9 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Put } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, v1Put } from "../http/client.js";
 import { readState, writeState } from "../state/frontpage-state.js";
+import { emitErr, emitOk, emitUsage, isJson } from "../runtime.js";
 const TEXT_EXTS = new Set([
     ".astro",
     ".ts",
@@ -68,13 +69,11 @@ export async function runPush(args) {
         const cwd = process.cwd();
         const state = await readState(cwd);
         if (!state.baseCommitSha) {
-            console.error("No baseCommitSha in .frontpage/state.json. Run: frontpage pull");
-            return EXIT_USAGE;
+            return emitUsage("push", "No baseCommitSha in .frontpage/state.json. Run: frontpage pull", EXIT_USAGE);
         }
         const paths = await walkAllowlisted(cwd);
         if (paths.length === 0) {
-            console.error("No allowlisted files (src/, public/, content/) found in this folder.");
-            return EXIT_USAGE;
+            return emitUsage("push", "No allowlisted files (src/, public/, content/) found in this folder.", EXIT_USAGE);
         }
         const files = [];
         for (const path of paths) {
@@ -100,6 +99,16 @@ export async function runPush(args) {
         if (data.commitSha) {
             await writeState({ ...state, slug, baseCommitSha: data.commitSha }, cwd);
         }
+        if (isJson()) {
+            emitOk("push", {
+                slug,
+                changed: data.changed,
+                commitSha: data.commitSha,
+                baseCommitSha: data.baseCommitSha,
+                filesChanged: data.filesChanged,
+            });
+            return EXIT_OK;
+        }
         if (!data.changed) {
             console.log("Nothing to commit (remote already matches).");
             return EXIT_OK;
@@ -111,7 +120,6 @@ export async function runPush(args) {
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("push", err);
     }
 }

package/dist/commands/revert.js

@@ -1,27 +1,32 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Post } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, v1Post } from "../http/client.js";
+import { emitErr, emitOk, emitUsage, isJson, requireYesOrTty } from "../runtime.js";
 export async function runRevert(args) {
     try {
+        const refuse = requireYesOrTty("revert");
+        if (refuse)
+            return emitUsage("revert", refuse, EXIT_USAGE);
         const { slug, rest } = await resolveSlug(args);
         const target = rest.find((a) => !a.startsWith("-"));
         if (!target || !/^[0-9a-f]{7,40}$/i.test(target)) {
-            console.error("Usage: frontpage revert <commitSha> [--site <slug>]");
-            console.error("Pass a full 40-char SHA from `frontpage history`.");
-            return EXIT_USAGE;
+            return emitUsage("revert", "Usage: frontpage revert <commitSha> [--site <slug>] [--yes]\nPass a full 40-char SHA from `frontpage history`.", EXIT_USAGE);
         }
         if (target.length !== 40) {
-            console.error("targetCommitSha must be a full 40-char hex SHA (not a short SHA).");
-            return EXIT_USAGE;
+            return emitUsage("revert", "targetCommitSha must be a full 40-char hex SHA (not a short SHA).", EXIT_USAGE);
         }
         const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/revert`, {
             targetCommitSha: target.toLowerCase(),
         });
-        console.log(`${data.commitHash.slice(0, 7)}  ${data.message}`);
-        console.log(`restored ${data.targetCommitSha.slice(0, 7)}  (was ${data.previousTipSha.slice(0, 7)})`);
+        if (isJson()) {
+            emitOk("revert", { slug, ...data });
+        }
+        else {
+            console.log(`${data.commitHash.slice(0, 7)}  ${data.message}`);
+            console.log(`restored ${data.targetCommitSha.slice(0, 7)}  (was ${data.previousTipSha.slice(0, 7)})`);
+        }
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("revert", err);
     }
 }

package/dist/commands/runs.js

@@ -1,5 +1,6 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1Post } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, v1Get, v1Post } from "../http/client.js";
+import { emitErr, emitOk, emitUsage, isJson, progress } from "../runtime.js";
 const TERMINAL = new Set(["succeeded", "failed", "canceled"]);
 function printRun(run) {
     const msg = run.statusMessage || run.summary || run.error || "";
@@ -23,20 +24,21 @@ export async function runRuns(args) {
             return await retryRunCmd(args.slice(1));
         if (sub === "get")
             return await getRun(args.slice(1));
-        // `frontpage runs <runId>` → get
         if (/^[0-9a-f-]{36}$/i.test(sub))
             return await getRun(args);
-        console.error("Usage: frontpage runs [current|wait|cancel|retry|get] …");
-        return EXIT_USAGE;
+        return emitUsage("runs", "Usage: frontpage runs [list|current|wait|cancel|retry|get] [runId] [--site <slug>]", EXIT_USAGE);
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("runs", err);
     }
 }
 async function listRuns(args) {
     const { slug } = await resolveSlug(args);
     const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs`);
+    if (isJson()) {
+        emitOk("runs", { slug, ...data });
+        return EXIT_OK;
+    }
     if (data.run) {
         console.log("latest:");
         printRun(data.run);
@@ -60,11 +62,15 @@ async function getRun(args) {
     const { slug, rest } = await resolveSlug(args);
     const runId = rest[0];
     if (!runId) {
-        console.error("Usage: frontpage runs get <runId> [--site <slug>]");
-        return EXIT_USAGE;
+        return emitUsage("runs", "Usage: frontpage runs get <runId> [--site <slug>]", EXIT_USAGE);
     }
     const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs/${encodeURIComponent(runId)}`);
-    printRun(data.run);
+    if (isJson()) {
+        emitOk("runs", { slug, run: data.run });
+    }
+    else {
+        printRun(data.run);
+    }
     return EXIT_OK;
 }
 async function waitRun(args) {
@@ -75,10 +81,15 @@ async function waitRun(args) {
     while (Date.now() - started < maxMs) {
         if (runId) {
             const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs/${encodeURIComponent(runId)}`);
-            process.stderr.write(`\r${data.run.status}  ${data.run.statusMessage ?? ""}   `);
+            progress(`\r${data.run.status}  ${data.run.statusMessage ?? ""}   `);
             if (TERMINAL.has(data.run.status)) {
-                process.stderr.write("\n");
-                printRun(data.run);
+                progress("\n");
+                if (isJson()) {
+                    emitOk("runs", { slug, action: "wait", run: data.run });
+                }
+                else {
+                    printRun(data.run);
+                }
                 if (data.run.status === "failed")
                     return EXIT_USAGE;
                 if (data.run.status === "canceled")
@@ -93,42 +104,59 @@ async function waitRun(args) {
                 : data.run;
             if (current) {
                 runId = current.id;
-                process.stderr.write(`\r${current.status}  ${current.statusMessage ?? ""}   `);
+                progress(`\r${current.status}  ${current.statusMessage ?? ""}   `);
                 if (TERMINAL.has(current.status) && !data.poll?.active) {
-                    process.stderr.write("\n");
-                    printRun(current);
+                    progress("\n");
+                    if (isJson()) {
+                        emitOk("runs", { slug, action: "wait", run: current });
+                    }
+                    else {
+                        printRun(current);
+                    }
                     return current.status === "succeeded" ? EXIT_OK : EXIT_USAGE;
                 }
             }
             else {
-                console.log("No active run.");
+                if (isJson()) {
+                    emitOk("runs", { slug, action: "wait", run: null });
+                }
+                else {
+                    console.log("No active run.");
+                }
                 return EXIT_OK;
             }
         }
         await new Promise((r) => setTimeout(r, 2000));
     }
-    console.error("Timed out waiting for run.");
-    return EXIT_USAGE;
+    return emitUsage("runs", "Timed out waiting for run.", EXIT_USAGE);
 }
 async function cancelRun(args) {
     const { slug, rest } = await resolveSlug(args);
     const runId = rest[0];
     if (!runId) {
-        console.error("Usage: frontpage runs cancel <runId> [--site <slug>]");
-        return EXIT_USAGE;
+        return emitUsage("runs", "Usage: frontpage runs cancel <runId> [--site <slug>]", EXIT_USAGE);
     }
     await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs/${encodeURIComponent(runId)}/cancel`);
-    console.log(`Canceled ${runId}`);
+    if (isJson()) {
+        emitOk("runs", { slug, action: "cancel", runId });
+    }
+    else {
+        console.log(`Canceled ${runId}`);
+    }
     return EXIT_OK;
 }
 async function retryRunCmd(args) {
     const { slug, rest } = await resolveSlug(args);
     const runId = rest[0];
     if (!runId) {
-        console.error("Usage: frontpage runs retry <runId> [--site <slug>]");
-        return EXIT_USAGE;
+        return emitUsage("runs", "Usage: frontpage runs retry <runId> [--site <slug>]", EXIT_USAGE);
     }
     const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs/${encodeURIComponent(runId)}/retry`);
-    console.log(data.runId);
+    if (isJson()) {
+        emitOk("runs", { slug, action: "retry", runId: data.runId, previousRunId: runId });
+    }
+    else {
+        console.log(data.runId);
+    }
     return EXIT_OK;
 }

package/dist/commands/sites.js

@@ -1,7 +1,13 @@
-import { EXIT_OK, exitCodeForError, v1Get } from "../http/client.js";
+import { EXIT_OK } from "../http/client.js";
+import { v1Get } from "../http/client.js";
+import { emitErr, emitOk, isJson } from "../runtime.js";
 export async function runSites() {
     try {
         const data = await v1Get("/api/v1/sites");
+        if (isJson()) {
+            emitOk("sites", data);
+            return EXIT_OK;
+        }
         if (data.sites.length === 0) {
             console.log("No sites. Create a site in Frontpage first.");
             return EXIT_OK;
@@ -14,7 +20,6 @@ export async function runSites() {
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("sites", err);
     }
 }

package/dist/commands/status.js

@@ -1,6 +1,7 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, exitCodeForError, v1Get, apiBase } from "../http/client.js";
+import { EXIT_OK, v1Get, apiBase } from "../http/client.js";
 import { readState } from "../state/frontpage-state.js";
+import { emitErr, emitOk, isJson } from "../runtime.js";
 export async function runStatus(args) {
     try {
         const { slug } = await resolveSlug(args);
@@ -11,7 +12,22 @@ export async function runStatus(args) {
                 active: [],
             })),
         ]);
-        console.log(`API base:       ${apiBase()}`);
+        const tipDrift = Boolean(state.baseCommitSha && data.baseCommitSha && state.baseCommitSha !== data.baseCommitSha);
+        const payload = {
+            apiBase: apiBase(),
+            site: slug,
+            localSlug: state.slug ?? null,
+            localBaseCommitSha: state.baseCommitSha ?? null,
+            remoteTip: data.baseCommitSha,
+            remoteFileCount: data.files.length,
+            activeRuns: runs.active ?? [],
+            tipDrift,
+        };
+        if (isJson()) {
+            emitOk("status", payload);
+            return EXIT_OK;
+        }
+        console.log(`API base:       ${payload.apiBase}`);
         console.log(`Site:           ${slug}`);
         console.log(`Local state:    ${state.slug ?? "(none)"}${state.baseCommitSha ? ` @ ${state.baseCommitSha.slice(0, 7)}` : ""}`);
         console.log(`Remote tip:     ${data.baseCommitSha ?? "(unknown)"}`);
@@ -23,13 +39,12 @@ export async function runStatus(args) {
         else {
             console.log("Active runs:    none");
         }
-        if (state.baseCommitSha && data.baseCommitSha && state.baseCommitSha !== data.baseCommitSha) {
+        if (tipDrift) {
             console.log("Note: remote tip differs from last pull — run frontpage pull");
         }
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("status", err);
     }
 }

package/dist/commands/whoami.js

@@ -1,14 +1,20 @@
-import { EXIT_OK, exitCodeForError, v1Get } from "../http/client.js";
+import { EXIT_OK } from "../http/client.js";
+import { v1Get } from "../http/client.js";
+import { emitErr, emitOk, isJson } from "../runtime.js";
 export async function runWhoami() {
     try {
         const me = await v1Get("/api/v1/me");
-        console.log(`email:  ${me.email ?? "(none)"}`);
-        console.log(`userId: ${me.userId}`);
-        console.log(`keyId:  ${me.keyId}`);
+        if (isJson()) {
+            emitOk("whoami", me);
+        }
+        else {
+            console.log(`email:  ${me.email ?? "(none)"}`);
+            console.log(`userId: ${me.userId}`);
+            console.log(`keyId:  ${me.keyId}`);
+        }
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("whoami", err);
     }
 }

package/dist/completions/generate.js

@@ -14,15 +14,16 @@ _frontpage_completions() {
   fi
   local cmd="\${COMP_WORDS[1]}"
   case "\${cmd}" in
-    help) COMPREPLY=( $(compgen -W "\${cmds} auth sync agent content history exit-codes" -- "\${cur}") ) ;;
+    help) COMPREPLY=( $(compgen -W "\${cmds} quickstart auth sync agent content history isolation exit-codes" -- "\${cur}") ) ;;
     completion) COMPREPLY=( $(compgen -W "bash zsh fish" -- "\${cur}") ) ;;
-    runs) COMPREPLY=( $(compgen -W "current wait cancel retry get" -- "\${cur}") ) ;;
+    runs) COMPREPLY=( $(compgen -W "list current wait cancel retry get" -- "\${cur}") ) ;;
     deploy) COMPREPLY=( $(compgen -W "wait" -- "\${cur}") ) ;;
     media) COMPREPLY=( $(compgen -W "list upload" -- "\${cur}") ) ;;
     seo|settings) COMPREPLY=( $(compgen -W "get set" -- "\${cur}") ) ;;
     articles) COMPREPLY=( $(compgen -W "list content create-section create-article set-draft" -- "\${cur}") ) ;;
-    modules|extensions) COMPREPLY=( $(compgen -W "list enable disable config" -- "\${cur}") ) ;;
-    *) COMPREPLY=( $(compgen -W "--site --help" -- "\${cur}") ) ;;
+    modules) COMPREPLY=( $(compgen -W "list enable disable archive config" -- "\${cur}") ) ;;
+    extensions) COMPREPLY=( $(compgen -W "list enable disable config" -- "\${cur}") ) ;;
+    *) COMPREPLY=( $(compgen -W "--site --help --json --quiet --yes" -- "\${cur}") ) ;;
   esac
 }
 complete -F _frontpage_completions frontpage

package/dist/flags.d.ts

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

package/dist/flags.js

@@ -0,0 +1,31 @@
+/**
+ * Strip global flags from argv. Safe to call before command dispatch.
+ * Recognizes --json, --quiet, --yes, and help aliases anywhere in the list.
+ */
+export function parseGlobalFlags(argv) {
+    const args = [];
+    let json = false;
+    let quiet = false;
+    let yes = false;
+    let wantsHelp = false;
+    for (const a of argv) {
+        if (a === "--json") {
+            json = true;
+            continue;
+        }
+        if (a === "--quiet" || a === "-q") {
+            quiet = true;
+            continue;
+        }
+        if (a === "--yes" || a === "-y") {
+            yes = true;
+            continue;
+        }
+        if (a === "--help" || a === "-h") {
+            wantsHelp = true;
+            continue;
+        }
+        args.push(a);
+    }
+    return { json, quiet, yes, wantsHelp, args };
+}

package/dist/registry.d.ts

@@ -8,7 +8,12 @@ export type CommandDef = {
     usage?: string;
     /** Topic tags for `help <topic>`. */
     topics?: string[];
+    examples?: string[];
+    flags?: string[];
+    dangers?: string[];
+    seeAlso?: string[];
 };
 export declare const COMMANDS: readonly CommandDef[];
+export declare const TOPIC_NAMES: readonly ["quickstart", "auth", "sync", "agent", "content", "history", "isolation", "exit-codes"];
 export declare const TOPICS: Record<string, string>;
 export declare function findCommand(name: string): CommandDef | undefined;