frontpage-host 0.1.0 → 0.1.2

package/AGENTS.md

@@ -0,0 +1,194 @@
+# Frontpage CLI — agent operating manual
+
+This file ships inside the `frontpage-host` npm package. Prefer it over scraping the product website.
+
+## Install and invoke
+
+| Item | Value |
+|------|--------|
+| npm package | `frontpage-host` |
+| Binary | `frontpage` |
+| Wrong package | Do **not** install npm `frontpage` (unrelated) |
+
+```bash
+npm i -g frontpage-host
+frontpage help --json    # introspect commands + topics
+```
+
+Node.js ≥ 20.
+
+## Staging vs production (read this first)
+
+Frontpage has two surfaces:
+
+| Surface | URL | What it is |
+|---------|-----|------------|
+| **Staging** | `https://<subdomain>.frontpage.host` | Working copy for edits, previews, and review |
+| **Production** | Custom domain (when connected), after **publish** | What end customers see on the live domain |
+
+**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`.
+- 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.
+
+**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).
+
+## Non-interactive auth
+
+```bash
+frontpage login "$FRONTPAGE_API_KEY"
+# or export FRONTPAGE_API_KEY=fp_live_…  (wins over keychain)
+frontpage whoami --json
+frontpage doctor --json
+```
+
+- Keys are minted only in the Frontpage UI (profile → Developers). Prefix `fp_live_`.
+- Keys act as the minting user on **every** site they can access. Treat like passwords.
+- `PUBLIC_CLI_ENABLED` is server-side; the CLI cannot turn it on. Bare “not found” on `/api/v1/me` usually means the flag is off (exit 5).
+
+## Site IDs
+
+- Always use the **subdomain** (`arbiter`, `asimov-press`) with `use` / `--site`.
+- Never pass custom domains, FQDNs, or URLs as the site id.
+- Folder state: `.frontpage/state.json` → `{ slug, baseCommitSha }`.
+
+```bash
+frontpage sites --json
+frontpage use <subdomain>
+# or: frontpage <cmd> --site <subdomain>
+```
+
+## File sync recipe
+
+Allowlisted roots only: `src/`, `public/`, `content/`. Other paths never sync (including some platform-owned scaffold files).
+
+```bash
+frontpage pull
+# edit local allowlisted files
+frontpage diff --json          # data.dirty === true when local ≠ remote
+frontpage push --message "…"
+# on exit 3 (CAS / active run): frontpage status --json → pull or wait → retry push
+# Review at https://<subdomain>.frontpage.host
+# Do NOT publish unless the user asked.
+```
+
+Rules:
+
+1. **Pull before push** so `baseCommitSha` is set (CAS).
+2. **Do not push** while an agent run is active (`status` / `runs`).
+3. Push updates **staging** (subdomain). Production is unchanged until someone runs `publish`.
+4. Pushing module markup may auto-activate modules (same as the editor agent).
+5. Binaries use base64; do not UTF-8 round-trip them.
+6. Prefer reviewing the subdomain after push; only use `deploy wait` if you need to block until a build finishes.
+
+## Agent prompt loop
+
+```bash
+frontpage prompt "make the hero shorter"
+frontpage runs wait          # wait for the agent run to finish
+# Review https://<subdomain>.frontpage.host — do not publish unless asked.
+```
+
+Mid-task continuation is automatic. There is **no** `runs continue` in v1.
+
+## Content / JSON-native commands
+
+These already return JSON bodies (wrap further with global `--json` where supported):
+
+- `usage`, `analytics`, `seo`, `articles`, `settings`, `inbox` (default JSON)
+- Mutate: `modules enable|disable|archive|config`, `extensions …`
+
+Click-edit (exact single occurrence), **not** file push:
+
+```bash
+frontpage edit --path / --old "exact old" --new "exact new"
+```
+
+`edit` also updates **staging**, same as push. Still do not publish unless asked.
+
+## History / revert
+
+```bash
+frontpage history --json
+frontpage revert <40-char-sha> --yes    # required --yes when non-TTY; only if user asked
+```
+
+- `S` = staging tip, `P` = production tip.
+- Revert creates a **new** commit whose tree matches the target (linear restore) on the site branch (staging).
+- Full 40-char SHA only. Refused while an agent run is active.
+
+## Exit codes — what to do next
+
+| Code | Meaning | Next step |
+|------|---------|-----------|
+| 0 | Success | Continue |
+| 2 | Usage / budget / rate-limit / unavailable / failed run wait | Fix args, wait, or check `usage` |
+| 3 | Conflict (CAS tip moved, active run, cancel-while-deploying) | `status` / `pull` / `runs wait`; retry |
+| 4 | Authn/authz **or** site not found (404 often hides existence) | Check key, membership, subdomain |
+| 5 | Unexpected server/network / API disabled | Retry; verify `PUBLIC_CLI_ENABLED` / `FRONTPAGE_API_BASE` |
+
+Global machine envelope (`--json`):
+
+```json
+{ "ok": true, "command": "status", "data": { } }
+{ "ok": false, "command": "push", "error": { "message": "…", "code": "conflict", "httpStatus": 409, "exitCode": 3 } }
+```
+
+Failures with `--json` print the envelope on **stdout** (still use the process exit code).
+
+## Global flags
+
+| Flag | Meaning |
+|------|---------|
+| `--json` | Stable JSON envelope for supported commands |
+| `--quiet` | Suppress progress spinners / chatter |
+| `--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>`) |
+
+## Destructive ops — defaults for agents
+
+**Never** run unless the user explicitly asked (or their workflow clearly requires it):
+
+- `frontpage publish` (promotes staging → **production** / custom domain)
+- `frontpage unpublish` (takes production offline) — requires `--yes` when non-TTY
+- `frontpage revert <sha>` — requires `--yes` when non-TTY
+- `frontpage inbox … --mark-read` (side-effecting)
+- Broad `settings` mutations or mass `edit` without a clear request
+
+Safe default after finishing work: summarize what changed and give the staging URL for review.
+
+## Other nuances agents often miss
+
+1. **CLI site id ≠ public domain.** Target `asimov-press`, not `asimov-press.frontpage.host` or a custom domain.
+2. **Keys are account-wide.** One key can reach every site the user can access.
+3. **404 → exit 4** often means “no access / not found,” not only a bad password.
+4. **Allowlist only.** If a file is not under `src/`, `public/`, or `content/`, the CLI will not sync it. Some scaffold files are platform-owned and refuse CLI read/write.
+5. **Full-tree push for allowlisted roots.** Local allowlisted files become the intended remote tree for those roots on push.
+6. **Active-run guard.** Push/revert refuse while an editor agent run is active (exit 3).
+7. **CAS.** Tip moved since pull → exit 3; pull and retry.
+8. **No invented v1 commands:** `domains*`, `billing*`, `members*`, `suggestions*`, `sites delete|restore`, `runs continue`, MCP, git remotes / clone URLs.
+9. **`deploy wait` ≠ publish.** Optional build wait only; staging visibility is the subdomain.
+10. **Honesty on stubs.** `open --prod` is currently a no-op stub (still opens the subdomain).
+
+## Isolation (hard fence)
+
+- API never returns another site’s branch, GitHub tokens, or clone URLs.
+- Site targeting is subdomain → `site/<slug>` only.
+- See `frontpage help isolation`.
+
+## Canonical introspection
+
+```bash
+frontpage help
+frontpage help --json
+frontpage help sync
+frontpage help agent
+frontpage doctor --json
+```

package/README.md

@@ -0,0 +1,57 @@
+# frontpage-host
+
+Frontpage CLI — manage your site from the terminal.
+
+**npm package:** `frontpage-host`  
+**Binary:** `frontpage`  
+**Do not install** the unrelated npm package named `frontpage`.
+
+## Install
+
+```bash
+npm i -g frontpage-host
+# or one-shot:
+npx frontpage-host help
+```
+
+Requires Node.js ≥ 20.
+
+## 60-second path
+
+1. In the Frontpage editor: profile menu → **Developers** → create an API key (`fp_live_…`).
+2. `frontpage login` (or `frontpage login "$FRONTPAGE_API_KEY"`).
+3. `frontpage sites` — note the **subdomain** (not a custom domain).
+4. `mkdir my-site && cd my-site && frontpage use <subdomain>`
+5. `frontpage pull` → edit files under `src/`, `public/`, or `content/`
+6. `frontpage push --message "describe the change"`
+7. Review staging at `https://<subdomain>.frontpage.host` (no separate staging-deploy step).
+8. `frontpage publish` only when you intentionally promote to production.
+
+## Environment
+
+| Variable | Purpose |
+|----------|---------|
+| `FRONTPAGE_API_KEY` | Bearer key (preferred in CI; overrides keychain) |
+| `FRONTPAGE_API_BASE` | API origin (default `https://app.frontpage.host`) |
+
+## Help (source of truth in the binary)
+
+```bash
+frontpage help              # catalog + quickstart
+frontpage help quickstart
+frontpage help auth
+frontpage help sync
+frontpage help agent
+frontpage help content
+frontpage help history
+frontpage help isolation
+frontpage help exit-codes
+frontpage help push         # per-command details
+frontpage push --help       # same
+```
+
+Machine-readable: `frontpage help --json` and global `--json` / `--quiet` on commands.
+
+## Agents
+
+See [AGENTS.md](./AGENTS.md) and [llms.txt](./llms.txt) in this package.

package/dist/bin.js

@@ -33,13 +33,21 @@ import { runHistory } from "./commands/history.js";
 import { runRevert } from "./commands/revert.js";
 import { runCompletion } from "./commands/completion.js";
 import { EXIT_USAGE, EXIT_UNEXPECTED } from "./http/client.js";
+import { parseGlobalFlags } from "./flags.js";
+import { setRuntimeFlags, isJson } from "./runtime.js";
 async function main() {
-    const argv = process.argv.slice(2);
+    const parsed = parseGlobalFlags(process.argv.slice(2));
+    setRuntimeFlags({ json: parsed.json, quiet: parsed.quiet, yes: parsed.yes });
+    const argv = parsed.args;
     const cmd = argv[0];
     const args = argv.slice(1);
-    if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    // Global or per-command help aliases (before site resolution).
+    if (!cmd || cmd === "help") {
         return runHelp(cmd === "help" ? args : []);
     }
+    if (parsed.wantsHelp) {
+        return runHelp([cmd, ...args]);
+    }
     switch (cmd) {
         case "login":
             return runLogin(args);
@@ -109,8 +117,17 @@ async function main() {
         case "completion":
             return runCompletion(args);
         default:
-            console.error(`Unknown command: ${cmd}`);
-            console.error("Run: frontpage help");
+            if (isJson()) {
+                console.log(JSON.stringify({
+                    ok: false,
+                    command: cmd,
+                    error: { message: `Unknown command: ${cmd}`, exitCode: EXIT_USAGE },
+                }));
+            }
+            else {
+                console.error(`Unknown command: ${cmd}`);
+                console.error("Run: frontpage help");
+            }
             return EXIT_USAGE;
     }
 }
@@ -119,6 +136,16 @@ main()
     process.exitCode = code;
 })
     .catch((err) => {
-    console.error(err instanceof Error ? err.message : String(err));
+    const message = err instanceof Error ? err.message : String(err);
+    if (isJson()) {
+        console.log(JSON.stringify({
+            ok: false,
+            command: "frontpage",
+            error: { message, exitCode: EXIT_UNEXPECTED },
+        }));
+    }
+    else {
+        console.error(message);
+    }
     process.exitCode = EXIT_UNEXPECTED;
 });

package/dist/commands/deploy.js

@@ -1,12 +1,13 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, v1Get } from "../http/client.js";
+import { emitErr, emitOk, emitUsage, progress } from "../runtime.js";
+import { isJson } from "../runtime.js";
 /** `frontpage deploy wait` — wait until no run is in deploying/queued/running. */
 export async function runDeploy(args) {
     try {
         const sub = args[0];
         if (sub !== "wait") {
-            console.error("Usage: frontpage deploy wait [--site <slug>]");
-            return EXIT_USAGE;
+            return emitUsage("deploy", "Usage: frontpage deploy wait [--site <slug>]", EXIT_USAGE);
         }
         const { slug } = await resolveSlug(args.slice(1));
         const started = Date.now();
@@ -15,18 +16,26 @@ export async function runDeploy(args) {
             const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs`);
             const busy = (data.active ?? []).filter((r) => ["queued", "running", "deploying"].includes(r.status));
             if (busy.length === 0) {
-                console.log(data.run ? `${data.run.id}  ${data.run.status}` : "No active deploy.");
+                if (isJson()) {
+                    emitOk("deploy", {
+                        slug,
+                        waited: true,
+                        run: data.run,
+                        status: data.run?.status ?? "idle",
+                    });
+                }
+                else {
+                    console.log(data.run ? `${data.run.id}  ${data.run.status}` : "No active deploy.");
+                }
                 return EXIT_OK;
             }
             const head = busy.find((r) => r.status === "deploying") ?? busy[0];
-            process.stderr.write(`\r${head.status}  ${head.statusMessage ?? ""}   `);
+            progress(`\r${head.status}  ${head.statusMessage ?? ""}   `);
             await new Promise((r) => setTimeout(r, 2000));
         }
-        console.error("Timed out waiting for deploy.");
-        return EXIT_USAGE;
+        return emitUsage("deploy", "Timed out waiting for deploy.", EXIT_USAGE);
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("deploy", err);
     }
 }

package/dist/commands/diff.js

@@ -2,7 +2,8 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { join, relative, sep } from "node:path";
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, v1Get } from "../http/client.js";
+import { emitErr, emitOk, emitUsage, isJson } from "../runtime.js";
 const ROOTS = ["src", "public", "content"];
 async function walkLocal(cwd) {
     const map = new Map();
@@ -47,47 +48,56 @@ export async function runDiff(args) {
         const local = await walkLocal(cwd);
         const listing = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/files`);
         const remotePaths = new Set(listing.files.map((f) => f.path));
-        let changed = 0;
-        let onlyLocal = 0;
-        let onlyRemote = 0;
+        const added = [];
+        const modified = [];
+        const deleted = [];
         for (const path of [...local.keys()].sort()) {
             if (!remotePaths.has(path)) {
-                console.log(`A  ${path}`);
-                onlyLocal++;
+                added.push(path);
                 continue;
             }
             const encPath = path.split("/").map(encodeURIComponent).join("/");
             const remote = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/files/${encPath}`);
             const rh = remoteHash(remote.file);
             const lh = local.get(path);
-            if (rh !== lh) {
-                console.log(`M  ${path}`);
-                changed++;
-            }
+            if (rh !== lh)
+                modified.push(path);
         }
         for (const f of listing.files) {
-            if (!local.has(f.path)) {
-                console.log(`D  ${f.path}`);
-                onlyRemote++;
-            }
+            if (!local.has(f.path))
+                deleted.push(f.path);
         }
-        const total = changed + onlyLocal + onlyRemote;
-        if (total === 0) {
+        const dirty = added.length + modified.length + deleted.length > 0;
+        void (await stat(cwd).catch(() => null));
+        if (isJson()) {
+            emitOk("diff", {
+                slug,
+                baseCommitSha: listing.baseCommitSha,
+                dirty,
+                added,
+                modified,
+                deleted,
+            });
+            return EXIT_OK;
+        }
+        for (const path of added)
+            console.log(`A  ${path}`);
+        for (const path of modified)
+            console.log(`M  ${path}`);
+        for (const path of deleted)
+            console.log(`D  ${path}`);
+        if (!dirty) {
             console.log("No differences.");
         }
         else {
-            console.error(`# ${total} difference(s) · tip ${(listing.baseCommitSha ?? "").slice(0, 7) || "?"} · A=local-only M=modified D=remote-only`);
+            console.error(`# ${added.length + modified.length + deleted.length} difference(s) · tip ${(listing.baseCommitSha ?? "").slice(0, 7) || "?"} · A=local-only M=modified D=remote-only`);
         }
-        // Ensure cwd has the tree (optional UX check)
-        void (await stat(cwd).catch(() => null));
         return EXIT_OK;
     }
     catch (err) {
         if (err instanceof Error && /No site selected/.test(err.message)) {
-            console.error(err.message);
-            return EXIT_USAGE;
+            return emitUsage("diff", err.message, EXIT_USAGE);
         }
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("diff", err);
     }
 }

package/dist/commands/doctor.js

@@ -1,26 +1,51 @@
 import { getApiKey, maskKey } from "../auth/keychain.js";
-import { apiBase, EXIT_OK, EXIT_AUTH, EXIT_UNEXPECTED, v1Get } from "../http/client.js";
+import { apiBase, EXIT_OK, EXIT_AUTH, exitCodeForError, v1Get } from "../http/client.js";
 import { readState } from "../state/frontpage-state.js";
+import { emitErr, emitOk, emitUsage, isJson } from "../runtime.js";
 export async function runDoctor() {
-    console.log(`API base: ${apiBase()}`);
     const key = await getApiKey();
+    const state = await readState();
+    const base = apiBase();
     if (!key) {
+        if (isJson()) {
+            return emitUsage("doctor", "No API key. Run: frontpage login", EXIT_AUTH);
+        }
         console.error("No API key. Run: frontpage login");
         return EXIT_AUTH;
     }
-    console.log(`API key:  ${maskKey(key)} (never prints the full secret)`);
-    const state = await readState();
-    console.log(`Folder site: ${state.slug ?? "(not set — run frontpage use <subdomain>)"}`);
     try {
         const me = await v1Get("/api/v1/me");
-        console.log(`whoami:   ok (${me.email ?? me.userId})`);
         const sites = await v1Get("/api/v1/sites");
-        console.log(`sites:    ok (${sites.sites.length} site(s))`);
-        console.log("doctor:   all checks passed");
+        const data = {
+            apiBase: base,
+            apiKeyMasked: maskKey(key),
+            folderSite: state.slug ?? null,
+            baseCommitSha: state.baseCommitSha ?? null,
+            whoami: { email: me.email ?? null, userId: me.userId },
+            siteCount: sites.sites.length,
+            ok: true,
+        };
+        if (isJson()) {
+            emitOk("doctor", data);
+        }
+        else {
+            console.log(`API base: ${base}`);
+            console.log(`API key:  ${maskKey(key)} (never prints the full secret)`);
+            console.log(`Folder site: ${state.slug ?? "(not set — run frontpage use <subdomain>)"}`);
+            console.log(`whoami:   ok (${me.email ?? me.userId})`);
+            console.log(`sites:    ok (${sites.sites.length} site(s))`);
+            console.log("doctor:   all checks passed");
+        }
         return EXIT_OK;
     }
     catch (err) {
+        if (isJson()) {
+            return emitErr("doctor", err);
+        }
+        console.log(`API base: ${base}`);
+        console.log(`API key:  ${maskKey(key)} (never prints the full secret)`);
+        console.log(`Folder site: ${state.slug ?? "(not set — run frontpage use <subdomain>)"}`);
         console.error(err instanceof Error ? err.message : String(err));
-        return EXIT_UNEXPECTED;
+        return exitCodeForError(err);
     }
 }

package/dist/commands/help.js

@@ -1,14 +1,77 @@
-import { COMMANDS, TOPICS, findCommand } from "../registry.js";
+import { COMMANDS, TOPIC_NAMES, TOPICS, findCommand } from "../registry.js";
+import { isJson, emitOk } from "../runtime.js";
+function printCommandHelp(cmd) {
+    console.log(`${cmd.name} — ${cmd.summary}`);
+    if (cmd.usage)
+        console.log(`Usage: ${cmd.usage}`);
+    if (cmd.flags?.length) {
+        console.log("\nFlags / notes:");
+        for (const f of cmd.flags)
+            console.log(`  - ${f}`);
+    }
+    if (cmd.examples?.length) {
+        console.log("\nExamples:");
+        for (const e of cmd.examples)
+            console.log(`  ${e}`);
+    }
+    if (cmd.dangers?.length) {
+        console.log("\nDanger:");
+        for (const d of cmd.dangers)
+            console.log(`  ! ${d}`);
+    }
+    if (cmd.seeAlso?.length) {
+        console.log(`\nSee also: ${cmd.seeAlso.join(", ")}`);
+    }
+}
 export function runHelp(args) {
-    const topic = args[0]?.trim();
+    const filtered = args.filter((a) => a !== "--json" && a !== "--quiet" && a !== "-q");
+    const topic = filtered[0]?.trim();
+    if (isJson()) {
+        if (!topic) {
+            emitOk("help", {
+                commands: COMMANDS.map((c) => ({
+                    name: c.name,
+                    summary: c.summary,
+                    usage: c.usage,
+                    topics: c.topics,
+                    examples: c.examples,
+                    flags: c.flags,
+                    dangers: c.dangers,
+                    seeAlso: c.seeAlso,
+                })),
+                topics: TOPIC_NAMES,
+                topicBodies: TOPICS,
+            });
+            return 0;
+        }
+        if (TOPICS[topic]) {
+            emitOk("help", { topic, body: TOPICS[topic] });
+            return 0;
+        }
+        const cmd = findCommand(topic);
+        if (cmd) {
+            emitOk("help", { command: cmd });
+            return 0;
+        }
+        console.log(JSON.stringify({
+            ok: false,
+            command: "help",
+            error: { message: `Unknown help topic: ${topic}`, exitCode: 2 },
+        }));
+        return 2;
+    }
     if (!topic) {
         console.log("Frontpage CLI\n");
-        console.log("Usage: frontpage <command> [options]\n");
-        console.log("Commands:");
+        console.log("Package: frontpage-host  ·  Binary: frontpage");
+        console.log("Do not install the unrelated npm package named \"frontpage\".\n");
+        console.log(TOPICS.quickstart.split("\n").slice(0, 12).join("\n"));
+        console.log("\nCommands:");
         for (const c of COMMANDS) {
-            console.log(`  ${c.name.padEnd(10)} ${c.summary}`);
+            console.log(`  ${c.name.padEnd(12)} ${c.summary}`);
         }
-        console.log("\nTopics: frontpage help auth | frontpage help exit-codes");
+        console.log(`\nTopics: frontpage help ${TOPIC_NAMES.join(" | frontpage help ")}`);
+        console.log("Global: --json  --quiet  --yes  --site <slug>  --help");
+        console.log("Agents: see AGENTS.md in the npm package");
         return 0;
     }
     if (TOPICS[topic]) {
@@ -17,9 +80,7 @@ export function runHelp(args) {
     }
     const cmd = findCommand(topic);
     if (cmd) {
-        console.log(`${cmd.name} — ${cmd.summary}`);
-        if (cmd.usage)
-            console.log(`Usage: ${cmd.usage}`);
+        printCommandHelp(cmd);
         return 0;
     }
     console.error(`Unknown help topic: ${topic}`);

package/dist/commands/history.js

@@ -1,5 +1,6 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, v1Get } from "../http/client.js";
+import { emitErr, emitOk, emitUsage, isJson } from "../runtime.js";
 export async function runHistory(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
@@ -23,13 +24,13 @@ export async function runHistory(args) {
                 page = a.slice("--page=".length);
                 continue;
             }
-            if (a === "--help" || a === "-h") {
-                console.error("Usage: frontpage history [--limit N] [--page N] [--site <slug>]");
-                return EXIT_USAGE;
-            }
         }
         const qs = new URLSearchParams({ limit, page });
         const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/history?${qs}`);
+        if (isJson()) {
+            emitOk("history", { slug, ...data });
+            return EXIT_OK;
+        }
         for (const c of data.commits) {
             const mark = data.stagingCommit === c.sha ? "S" : data.productionCommit === c.sha ? "P" : " ";
             const who = c.actorEmail ?? c.actorKind ?? "";
@@ -43,7 +44,9 @@ export async function runHistory(args) {
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        if (err instanceof Error && /Usage:/.test(err.message)) {
+            return emitUsage("history", err.message, EXIT_USAGE);
+        }
+        return emitErr("history", err);
     }
 }

package/dist/commands/ls.js

@@ -1,11 +1,16 @@
 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 runLs(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
         const prefix = rest[0];
         const q = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
         const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/files${q}`);
+        if (isJson()) {
+            emitOk("ls", { ...data, prefix: prefix ?? null });
+            return EXIT_OK;
+        }
         for (const f of data.files) {
             console.log(`${String(f.bytes).padStart(10)}  ${f.path}`);
         }
@@ -13,7 +18,6 @@ export async function runLs(args) {
         return EXIT_OK;
     }
     catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        return exitCodeForError(err);
+        return emitErr("ls", err);
     }
 }