frontpage-host 0.1.0

package/dist/http/client.d.ts

@@ -0,0 +1,27 @@
+export declare const EXIT_OK = 0;
+export declare const EXIT_USAGE = 2;
+export declare const EXIT_CONFLICT = 3;
+export declare const EXIT_AUTH = 4;
+export declare const EXIT_UNEXPECTED = 5;
+export declare class CliHttpError extends Error {
+    readonly exitCode: number;
+    readonly status: number;
+    readonly code?: string;
+    constructor(message: string, exitCode: number, status: number, code?: string);
+}
+export declare function apiBase(): string;
+export type V1Envelope = {
+    error?: {
+        code?: string;
+        message?: string;
+        requestId?: string;
+    };
+};
+export declare function v1Get<T>(path: string): Promise<T>;
+export declare function v1Post<T>(path: string, body?: unknown): Promise<T>;
+export declare function v1Put<T>(path: string, body?: unknown): Promise<T>;
+export declare function v1Delete<T>(path: string): Promise<T>;
+export declare function v1Patch<T>(path: string, body?: unknown): Promise<T>;
+/** Multipart POST (e.g. media upload). Does not set Content-Type — fetch sets the boundary. */
+export declare function v1PostMultipart<T>(path: string, form: FormData): Promise<T>;
+export declare function exitCodeForError(err: unknown): number;

package/dist/http/client.js

@@ -0,0 +1,163 @@
+/**
+ * Thin HTTP client for `/api/v1`.
+ * Exit: 0 ok · 2 rate-limit/budget/usage · 3 conflict · 4 auth · 5 other.
+ */
+import { getApiKey } from "../auth/keychain.js";
+export const EXIT_OK = 0;
+export const EXIT_USAGE = 2;
+export const EXIT_CONFLICT = 3;
+export const EXIT_AUTH = 4;
+export const EXIT_UNEXPECTED = 5;
+export class CliHttpError extends Error {
+    exitCode;
+    status;
+    code;
+    constructor(message, exitCode, status, code) {
+        super(message);
+        this.name = "CliHttpError";
+        this.exitCode = exitCode;
+        this.status = status;
+        this.code = code;
+    }
+}
+export function apiBase() {
+    const fromEnv = process.env.FRONTPAGE_API_BASE?.replace(/\/$/, "");
+    if (fromEnv)
+        return fromEnv;
+    return "https://app.frontpage.host";
+}
+async function v1Request(method, path, body) {
+    const key = await getApiKey();
+    if (!key) {
+        throw new CliHttpError("Not logged in. Run: frontpage login", EXIT_AUTH, 401);
+    }
+    const url = `${apiBase()}${path.startsWith("/") ? path : `/${path}`}`;
+    const headers = {
+        Authorization: `Bearer ${key}`,
+        Accept: "application/json",
+    };
+    let payload;
+    if (body !== undefined) {
+        headers["Content-Type"] = "application/json";
+        payload = JSON.stringify(body);
+    }
+    let res;
+    try {
+        res = await fetch(url, { method, headers, body: payload });
+    }
+    catch (err) {
+        throw new CliHttpError(`Network error: ${err instanceof Error ? err.message : String(err)}`, EXIT_UNEXPECTED, 0);
+    }
+    const text = await res.text();
+    let parsed = {};
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        parsed = {};
+    }
+    if (res.ok)
+        return parsed;
+    const message = parsed.error?.message ?? `Request failed (${res.status})`;
+    const code = parsed.error?.code;
+    if (res.status === 401 || res.status === 403) {
+        throw new CliHttpError(message, EXIT_AUTH, res.status, code);
+    }
+    if (res.status === 402 || res.status === 429 || code === "rate_limited" || code === "payment_required") {
+        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
+    }
+    if (res.status === 409 || code === "conflict") {
+        throw new CliHttpError(message, EXIT_CONFLICT, res.status, code);
+    }
+    if (res.status === 413 || code === "payload_too_large") {
+        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
+    }
+    if (res.status === 503 || code === "unavailable") {
+        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
+    }
+    if (res.status === 404) {
+        const lower = message.toLowerCase();
+        if (lower === "not found." || lower === "not found") {
+            throw new CliHttpError("API not available (is PUBLIC_CLI_ENABLED on for this environment?).", EXIT_UNEXPECTED, res.status, code);
+        }
+        throw new CliHttpError(message, EXIT_AUTH, res.status, code);
+    }
+    throw new CliHttpError(message, EXIT_UNEXPECTED, res.status, code);
+}
+export async function v1Get(path) {
+    return v1Request("GET", path);
+}
+export async function v1Post(path, body) {
+    return v1Request("POST", path, body ?? {});
+}
+export async function v1Put(path, body) {
+    return v1Request("PUT", path, body ?? {});
+}
+export async function v1Delete(path) {
+    return v1Request("DELETE", path);
+}
+export async function v1Patch(path, body) {
+    return v1Request("PATCH", path, body ?? {});
+}
+/** Multipart POST (e.g. media upload). Does not set Content-Type — fetch sets the boundary. */
+export async function v1PostMultipart(path, form) {
+    const key = await getApiKey();
+    if (!key) {
+        throw new CliHttpError("Not logged in. Run: frontpage login", EXIT_AUTH, 401);
+    }
+    const url = `${apiBase()}${path.startsWith("/") ? path : `/${path}`}`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${key}`,
+                Accept: "application/json",
+            },
+            body: form,
+        });
+    }
+    catch (err) {
+        throw new CliHttpError(`Network error: ${err instanceof Error ? err.message : String(err)}`, EXIT_UNEXPECTED, 0);
+    }
+    const text = await res.text();
+    let parsed = {};
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        parsed = {};
+    }
+    if (res.ok)
+        return parsed;
+    const message = parsed.error?.message ?? `Request failed (${res.status})`;
+    const code = parsed.error?.code;
+    if (res.status === 401 || res.status === 403) {
+        throw new CliHttpError(message, EXIT_AUTH, res.status, code);
+    }
+    if (res.status === 402 || res.status === 429 || code === "rate_limited" || code === "payment_required") {
+        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
+    }
+    if (res.status === 409 || code === "conflict") {
+        throw new CliHttpError(message, EXIT_CONFLICT, res.status, code);
+    }
+    if (res.status === 413 || code === "payload_too_large") {
+        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
+    }
+    if (res.status === 503 || code === "unavailable") {
+        throw new CliHttpError(message, EXIT_USAGE, res.status, code);
+    }
+    if (res.status === 404) {
+        const lower = message.toLowerCase();
+        if (lower === "not found." || lower === "not found") {
+            throw new CliHttpError("API not available (is PUBLIC_CLI_ENABLED on for this environment?).", EXIT_UNEXPECTED, res.status, code);
+        }
+        throw new CliHttpError(message, EXIT_AUTH, res.status, code);
+    }
+    throw new CliHttpError(message, EXIT_UNEXPECTED, res.status, code);
+}
+export function exitCodeForError(err) {
+    if (err instanceof CliHttpError)
+        return err.exitCode;
+    return EXIT_UNEXPECTED;
+}

package/dist/registry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Command registry — single source of truth for help + dispatch.
+ * Only shipped Phase 0–5 commands appear here.
+ */
+export type CommandDef = {
+    name: string;
+    summary: string;
+    usage?: string;
+    /** Topic tags for `help <topic>`. */
+    topics?: string[];
+};
+export declare const COMMANDS: readonly CommandDef[];
+export declare const TOPICS: Record<string, string>;
+export declare function findCommand(name: string): CommandDef | undefined;

package/dist/registry.js

@@ -0,0 +1,116 @@
+/**
+ * Command registry — single source of truth for help + dispatch.
+ * Only shipped Phase 0–5 commands appear here.
+ */
+export const COMMANDS = [
+    { name: "help", summary: "Show available commands", usage: "frontpage help [command|topic]", topics: ["auth", "sync", "agent", "content", "history", "exit-codes"] },
+    { name: "login", summary: "Save an API key to the OS keychain", usage: "frontpage login [api-key]", topics: ["auth"] },
+    { name: "logout", summary: "Remove the saved API key", usage: "frontpage logout", topics: ["auth"] },
+    { name: "whoami", summary: "Show the identity for the current API key", usage: "frontpage whoami", topics: ["auth"] },
+    { name: "sites", summary: "List sites your key can access", usage: "frontpage sites", topics: ["auth"] },
+    { name: "use", summary: "Set the default site subdomain for this folder", usage: "frontpage use <subdomain>", topics: ["auth", "sync"] },
+    { name: "link", summary: "Alias for use", usage: "frontpage link <subdomain>", topics: ["auth", "sync"] },
+    { name: "doctor", summary: "Check CLI auth and API connectivity", usage: "frontpage doctor", topics: ["auth"] },
+    { name: "pull", summary: "Download allowlisted site files into this folder", usage: "frontpage pull [--site <slug>]", topics: ["sync"] },
+    { name: "push", summary: "Upload local allowlisted files (CAS + active-run guard)", usage: "frontpage push [--site <slug>] [--message …]", topics: ["sync"] },
+    { name: "diff", summary: "Compare local allowlisted files to the remote tip", usage: "frontpage diff [--site <slug>]", topics: ["sync"] },
+    { name: "ls", summary: "List remote allowlisted files", usage: "frontpage ls [prefix] [--site <slug>]", topics: ["sync"] },
+    { name: "cat", summary: "Print a remote file", usage: "frontpage cat <path> [--site <slug>]", topics: ["sync"] },
+    { name: "search", summary: "Search remote text files", usage: "frontpage search <pattern> [path] [--site <slug>]", topics: ["sync"] },
+    { name: "status", summary: "Show linked site and tip vs last pull", usage: "frontpage status [--site <slug>]", topics: ["sync"] },
+    { name: "open", summary: "Open the site in a browser", usage: "frontpage open [--site <slug>]", topics: ["sync"] },
+    { name: "prompt", summary: "Enqueue an agent build", usage: 'frontpage prompt "..." [--site <slug>] [--path /]', topics: ["agent"] },
+    { name: "runs", summary: "List, wait, cancel, or retry agent runs", usage: "frontpage runs [current|wait|cancel|retry|get] …", topics: ["agent"] },
+    { name: "publish", summary: "Promote staging to production", usage: "frontpage publish [--site <slug>]", topics: ["agent"] },
+    { name: "unpublish", summary: "Take the live site offline (admin)", usage: "frontpage unpublish [--site <slug>]", topics: ["agent"] },
+    { name: "deploy", summary: "Wait for active agent deploy to finish", usage: "frontpage deploy wait [--site <slug>]", topics: ["agent"] },
+    { name: "usage", summary: "Show plan and AI/bandwidth usage", usage: "frontpage usage [--site <slug>]", topics: ["agent"] },
+    { name: "analytics", summary: "Show analytics dashboard JSON", usage: "frontpage analytics [--days 7] [--site <slug>]", topics: ["agent"] },
+    { name: "pages", summary: "List site pages", usage: "frontpage pages [--site <slug>]", topics: ["agent"] },
+    { name: "modules", summary: "List or mutate modules (secret masks only)", usage: "frontpage modules [list|enable|disable|config] …", topics: ["agent", "content"] },
+    { name: "extensions", summary: "List or mutate extensions (no secret values)", usage: "frontpage extensions [list|enable|disable|config] …", topics: ["agent", "content"] },
+    { name: "media", summary: "List or upload site media assets", usage: "frontpage media list|upload <file>", topics: ["content"] },
+    { name: "inbox", summary: "List leads / subscribers / orders", usage: "frontpage inbox [leads|…] [--mark-read] [--csv]", topics: ["content"] },
+    { name: "seo", summary: "Get or set page SEO", usage: "frontpage seo get|set --path / …", topics: ["content"] },
+    { name: "articles", summary: "Articles hub, content, and section ops", usage: "frontpage articles list|content|create-article|…", topics: ["content"] },
+    { name: "settings", summary: "Get or set site settings (admin)", usage: "frontpage settings get|set …", topics: ["content"] },
+    { name: "edit", summary: "Click-edit style exact text replace + deploy", usage: 'frontpage edit --path / --old "…" --new "…"', topics: ["content"] },
+    { name: "history", summary: "List recent commits on the site branch", usage: "frontpage history [--limit N] [--page N]", topics: ["history", "agent"] },
+    { name: "revert", summary: "Restore site to a prior commit (tree restore + deploy)", usage: "frontpage revert <40-char-sha>", topics: ["history"] },
+    { name: "completion", summary: "Print shell completion script", usage: "frontpage completion bash|zsh|fish", topics: ["auth"] },
+];
+export const TOPICS = {
+    auth: `Authentication
+  1. Create a key in the Frontpage editor: profile menu → Developers
+  2. frontpage login
+  3. frontpage sites
+  4. frontpage use <subdomain>   (e.g. asimov-press, not a custom domain)
+
+  Keys act as you on every site you can access. Treat them like passwords.
+  Override with FRONTPAGE_API_KEY in CI.`,
+    sync: `File sync
+  frontpage use <subdomain>
+  frontpage pull                 # downloads src/, public/, content/ into cwd
+  frontpage diff                 # local vs remote tip
+  frontpage push [--message …]   # uploads allowlisted files; CAS + active-run guard
+  frontpage ls [prefix]
+  frontpage cat <path>
+  frontpage search <pattern>
+  frontpage status
+  frontpage open
+
+  Local state: .frontpage/state.json { slug, baseCommitSha }
+  Pull first so push can compare-and-swap on baseCommitSha.
+  Do not push while the editor agent is building (status / runs show active work).
+  Pushing module markup may auto-activate modules (same as the agent).
+  tokens.ts may be auto-repaired at commit if it would break the build.
+  Binaries use base64 (not utf8-corrupted).`,
+    agent: `Agent + publish
+  frontpage prompt "make the hero shorter"
+  frontpage runs                 # latest + active
+  frontpage runs wait [runId]
+  frontpage runs cancel <runId>
+  frontpage runs retry <runId>
+  frontpage deploy wait
+  frontpage publish
+  frontpage unpublish            # admin only
+  frontpage usage
+  frontpage analytics [--days 7]
+  frontpage pages
+  frontpage modules
+  frontpage extensions
+
+  Mid-task continuation is automatic — there is no runs continue.
+  Do not push while an agent run is active.`,
+    content: `Content
+  frontpage media list|upload <file>
+  frontpage inbox [leads|subscribers|…] [--mark-read] [--csv]
+  frontpage seo get|set --path /
+  frontpage articles list|content|create-section|create-article|set-draft|…
+  frontpage modules enable|disable|config <key>
+  frontpage extensions enable|disable|config <key>
+  frontpage settings get|set
+  frontpage edit --path / --old "…" --new "…"
+
+  edit uses click-edit (exact single occurrence), not push / gated-write.
+  Module OAuth and secret values are not exposed via the CLI.
+  Domains, billing, members, and site delete are out of v1.`,
+    history: `History
+  frontpage history [--limit 20] [--page 1]
+  frontpage revert <40-char-sha>
+
+  history lists commits on site/<slug> (plan Time Machine window).
+  S = staging tip, P = production tip.
+  revert creates a NEW commit whose tree matches the target (linear restore).
+  Target SHA must be on this site's history (not another site in the monorepo).
+  Refused while an agent run is active. Goes through commitSiteBranch (build gate).`,
+    "exit-codes": `Exit codes
+  0  success
+  2  usage / budget / rate-limit / unavailable
+  3  conflict (CAS / active run / unreachable domain / cancel-while-deploying)
+  4  authentication or authorization failure
+  5  unexpected server or network error`,
+};
+export function findCommand(name) {
+    return COMMANDS.find((c) => c.name === name);
+}

package/dist/site.d.ts

@@ -0,0 +1,5 @@
+/** Resolve --site flag or .frontpage/state.json slug. */
+export declare function resolveSlug(args: string[]): Promise<{
+    slug: string;
+    rest: string[];
+}>;

package/dist/site.js

@@ -0,0 +1,32 @@
+import { assertSubdomainSlug, readState } from "./state/frontpage-state.js";
+import { CliHttpError, EXIT_USAGE } from "./http/client.js";
+/** Resolve --site flag or .frontpage/state.json slug. */
+export async function resolveSlug(args) {
+    const rest = [];
+    let siteFlag;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--site" || a === "-s") {
+            siteFlag = args[++i];
+            continue;
+        }
+        if (a.startsWith("--site=")) {
+            siteFlag = a.slice("--site=".length);
+            continue;
+        }
+        rest.push(a);
+    }
+    if (siteFlag) {
+        try {
+            return { slug: assertSubdomainSlug(siteFlag), rest };
+        }
+        catch (err) {
+            throw new CliHttpError(err instanceof Error ? err.message : String(err), EXIT_USAGE, 400);
+        }
+    }
+    const state = await readState();
+    if (!state.slug) {
+        throw new CliHttpError("No site selected. Run: frontpage use <subdomain>   or pass --site <subdomain>", EXIT_USAGE, 400);
+    }
+    return { slug: state.slug, rest };
+}

package/dist/state/frontpage-state.d.ts

@@ -0,0 +1,8 @@
+export type FrontpageState = {
+    slug?: string;
+    /** Tip SHA from the last successful pull (Phase 3 CAS will use this). */
+    baseCommitSha?: string;
+};
+export declare function assertSubdomainSlug(raw: string): string;
+export declare function readState(cwd?: string): Promise<FrontpageState>;
+export declare function writeState(state: FrontpageState, cwd?: string): Promise<void>;

package/dist/state/frontpage-state.js

@@ -0,0 +1,28 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+const SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+export function assertSubdomainSlug(raw) {
+    const slug = raw.trim().toLowerCase();
+    if (!slug || slug.includes(".") || slug.includes("/") || !SLUG_PATTERN.test(slug)) {
+        throw new Error("Site must be a subdomain slug (e.g. asimov-press), not a domain or URL.");
+    }
+    return slug;
+}
+function statePath(cwd = process.cwd()) {
+    return join(cwd, ".frontpage", "state.json");
+}
+export async function readState(cwd = process.cwd()) {
+    try {
+        const raw = await readFile(statePath(cwd), "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function writeState(state, cwd = process.cwd()) {
+    const dir = join(cwd, ".frontpage");
+    await mkdir(dir, { recursive: true });
+    await writeFile(statePath(cwd), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "frontpage-host",
+  "version": "0.1.0",
+  "description": "Frontpage CLI — manage your site from the terminal",
+  "type": "module",
+  "bin": {
+    "frontpage": "dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/bin.ts",
+    "test": "vitest run",
+    "frontpage": "tsx src/bin.ts",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mkmccarty3/frontpage-app.git",
+    "directory": "cli"
+  },
+  "homepage": "https://frontpage.host",
+  "keywords": [
+    "frontpage",
+    "cli",
+    "landing-page"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  }
+}