htmlhost-cli 2.7.1 → 2.9.0

package/README.md

@@ -1,7 +1,11 @@
 # htmlhost
 
+[![npm](https://img.shields.io/npm/v/htmlhost-cli)](https://www.npmjs.com/package/htmlhost-cli) [![MCP compatible](https://img.shields.io/badge/MCP-compatible-8A2BE2)](https://htmlhost.co/docs/mcp)
+
 Deploy HTML projects from the terminal. [htmlhost.co](https://htmlhost.co)
 
+Want your AI assistant to deploy for you? The [htmlhost MCP server](https://www.npmjs.com/package/htmlhost-mcp) uses the same login as this CLI and works with Claude, Cursor, VS Code, Windsurf and Codex. [Setup guide →](https://htmlhost.co/docs/mcp)
+
 ## Install
 
 ```bash
@@ -87,6 +91,17 @@ checks if the remote site was modified (e.g. via the web editor) since your last
 or pull. If changes are detected, you'll be prompted to pull first, deploy anyway, or
 cancel. Use `--no-pull-check` to skip this check (useful in CI/CD).
 
+### `htmlhost status [dir] [--json]`
+
+Like `git status` for a linked folder: the site it deploys to, whether the live
+site changed since your last deploy/pull, and what the next `htmlhost deploy`
+would add, modify, or remove. Read-only.
+
+```bash
+htmlhost status
+htmlhost status --json   # machine-readable, for scripts and AI agents
+```
+
 ### `htmlhost pull [slug] [options]`
 Pull remote changes from an htmlhost.co site to the local project.
 
@@ -151,6 +166,18 @@ Open a deployed site in the default browser.
 ### `htmlhost delete <slug>`
 Delete a site. Use `--force` to skip confirmation.
 
+### `htmlhost versions [slug]`
+List a site's published versions, newest first: when, who, how it was published, and what changed. Every deploy and every save in the web editor is a version. Without a slug, uses the linked site. Add `--json` for machine-readable output.
+
+### `htmlhost rollback [slug] [version]`
+Make an earlier version live again. Without a version number, goes back to the version before the live one. The old version is published again as a new version, so you can switch back the same way. Needs the site owner to be on Pro. Use `--force` to skip confirmation, then `htmlhost pull` so your local files match.
+
+```bash
+htmlhost versions            # linked site
+htmlhost rollback            # back one version
+htmlhost rollback my-site 12 # make v12 live again
+```
+
 ### `htmlhost whoami`
 Show current authenticated user and plan.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlhost-cli",
-  "version": "2.7.1",
+  "version": "2.9.0",
   "description": "Deploy HTML files from the terminal — htmlhost.co CLI",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -49,6 +49,7 @@ function headers(extra = {}) {
   if (!token) throw new ApiError("Not logged in. Run: htmlhost login", 0);
   return {
     Authorization: `Bearer ${token}`,
+    "X-HTMLHost-Client": "cli",
     ...extra,
   };
 }

package/src/cli.mjs

@@ -5,7 +5,7 @@ import { bold, dim, cyan, err } from "./ui.mjs";
 import { ApiError } from "./api.mjs";
 import { startUpdateCheck, applyUpdate } from "./update.mjs";
 
-const VERSION = "2.7.1";
+const VERSION = "2.9.0";
 
 const HELP = `
   ${bold("htmlhost")} ${dim(`v${VERSION}`)} — deploy HTML from the terminal
@@ -13,11 +13,14 @@ const HELP = `
   ${bold("Usage:")}
     ${cyan("htmlhost deploy")} [file|dir] [opts]  Deploy file or directory
     ${cyan("htmlhost upload")} <file|dir...> [opts] Upload media file or directory
+    ${cyan("htmlhost status")} [dir]             Show what deploy would change (like git status)
     ${cyan("htmlhost pull")} [slug] [opts]        Pull remote changes to local
     ${cyan("htmlhost clone")} <slug> [dir]        Clone a site to a local directory
     ${cyan("htmlhost agents")} [dir]             Teach your AI coding tool htmlhost (AGENTS.md)
     ${cyan("htmlhost recipients")} [slug] [cmd]  Manage form notification recipients
     ${cyan("htmlhost list")}                     List your sites
+    ${cyan("htmlhost versions")} [slug]         List a site's published versions
+    ${cyan("htmlhost rollback")} [slug] [ver]    Make an earlier version live again (Pro)
     ${cyan("htmlhost delete")} <slug>            Delete a site
     ${cyan("htmlhost login")}                    Authenticate with an API token
     ${cyan("htmlhost whoami")}                   Show current user
@@ -37,6 +40,9 @@ const HELP = `
     --no-copy         Skip copying the URL to clipboard
     --json            Output response as JSON
 
+  ${bold("Status options:")}
+    --json            Output the status as JSON
+
   ${bold("Pull options:")}
     --force, -f       Pull without confirmation prompt
     --dry-run         Show what would change without writing
@@ -55,6 +61,11 @@ const HELP = `
   ${bold("Delete options:")}
     --force, -f       Skip confirmation prompt
 
+  ${bold("Rollback:")}
+    No version:       goes back to the version before the live one
+    --force, -f       Skip confirmation prompt
+    Restoring publishes the old version again as a new version
+
   ${bold("How deploy works:")}
     No args or dir: deploys entire folder as a multi-page site
     Single file:    deploys just that file (assets auto-inlined)
@@ -69,6 +80,7 @@ const HELP = `
     ${dim("$")} htmlhost upload assets/hero.png ${dim("# upload image, copy URL to clipboard")}
     ${dim("$")} htmlhost upload assets/        ${dim("# upload all files in directory")}
     ${dim("$")} htmlhost upload photo.jpg --open
+    ${dim("$")} htmlhost status                ${dim("# what would deploy change?")}
     ${dim("$")} htmlhost pull                  ${dim("# pull remote changes")}
     ${dim("$")} htmlhost clone my-site         ${dim("# clone into ./my-site/")}
     ${dim("$")} htmlhost delete old-project --force
@@ -134,6 +146,12 @@ export async function run(argv) {
         await upload(args, { json: jsonMode });
         break;
       }
+      case "status":
+      case "st": {
+        const { status } = await import("./commands/status.mjs");
+        await status(args, { json: jsonMode });
+        break;
+      }
       case "pull": {
         const { pull } = await import("./commands/pull.mjs");
         await pull(args);
@@ -166,6 +184,18 @@ export async function run(argv) {
         await deleteSite(args);
         break;
       }
+      case "versions":
+      case "history": {
+        const { versions } = await import("./commands/versions.mjs");
+        await versions(args, { json: jsonMode });
+        break;
+      }
+      case "rollback":
+      case "restore": {
+        const { rollback } = await import("./commands/versions.mjs");
+        await rollback(args, { json: jsonMode });
+        break;
+      }
       case "open": {
         const { open } = await import("./commands/open.mjs");
         await open(args);

package/src/commands/deploy.mjs

@@ -411,16 +411,7 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
   for (const file of htmlFiles) {
     const html = readFileSync(file.filePath, "utf8");
 
-    // Derive page path
-    let pagePath;
-    if (file.relativePath === "index.html") {
-      pagePath = "/";
-    } else if (basename(file.relativePath) === "index.html") {
-      const dirRel = dirname(file.relativePath);
-      pagePath = `/${dirRel}`;
-    } else {
-      pagePath = "/" + file.relativePath.replace(/\.html$/, "");
-    }
+    const pagePath = pagePathForFile(file.relativePath);
 
     if (seenPaths.has(pagePath)) {
       info(`Skipping duplicate route: ${cyan(file.relativePath)} (conflicts with existing ${pagePath})`);
@@ -621,7 +612,17 @@ async function preDeployPullCheck(slug, projectDir) {
  * Skips ignored files/directories.
  * Returns [{ filePath, relativePath, size }]
  */
-function findAllFiles(baseDir, currentDir) {
+/**
+ * The route a local HTML file deploys to: index.html → "/",
+ * blog/index.html → "/blog", about.html → "/about".
+ */
+export function pagePathForFile(relativePath) {
+  if (relativePath === "index.html") return "/";
+  if (basename(relativePath) === "index.html") return `/${dirname(relativePath)}`;
+  return "/" + relativePath.replace(/\.html$/, "");
+}
+
+export function findAllFiles(baseDir, currentDir) {
   const entries = readdirSync(currentDir, { withFileTypes: true });
   const results = [];
 

package/src/commands/status.mjs

@@ -0,0 +1,150 @@
+/**
+ * htmlhost status [--json]
+ *
+ * Like `git status` for a linked folder: which site it deploys to, whether the
+ * live site changed since your last deploy/pull, and what the next
+ * `htmlhost deploy` would add, change or remove. Read-only — nothing is
+ * written, locally or remotely.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { get } from "../api.mjs";
+import { readLink } from "../link.mjs";
+import { findAllFiles, pagePathForFile } from "./deploy.mjs";
+import { ok, err, info, warn, cyan, dim, bold, green, yellow, red } from "../ui.mjs";
+
+const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+
+/**
+ * Compare a local folder with the live site. Pure apart from reading local
+ * files: `remote` is the /api/sites/pull payload.
+ *
+ * - added:    local only — the next deploy uploads it
+ * - modified: on both, contents differ
+ * - removed:  live only — the next deploy deletes it (a deploy replaces the
+ *             whole site with the folder)
+ */
+export function compareWithRemote(dir, remote) {
+  const local = findAllFiles(dir, dir).map((f) => ({ ...f, relativePath: f.relativePath.split("\\").join("/") }));
+  const remotePages = new Map((remote.pages || []).map((p) => [p.path, p]));
+  const remoteAssets = new Map((remote.assets || []).map((a) => [a.path, a]));
+  const added = [];
+  const modified = [];
+  const seenRoutes = new Set();
+
+  for (const f of local) {
+    if (f.relativePath.endsWith(".html")) {
+      const route = pagePathForFile(f.relativePath);
+      if (seenRoutes.has(route)) continue; // deploy skips duplicate routes too
+      seenRoutes.add(route);
+      const page = remotePages.get(route);
+      if (!page) added.push(f.relativePath);
+      else if (readFileSync(f.filePath, "utf8") !== page.html) modified.push(f.relativePath);
+      remotePages.delete(route);
+      continue;
+    }
+    const asset = remoteAssets.get(f.relativePath);
+    remoteAssets.delete(f.relativePath);
+    if (!asset) {
+      added.push(f.relativePath);
+    } else if (asset.content !== null && asset.content !== undefined) {
+      if (readFileSync(f.filePath, "utf8") !== asset.content) modified.push(f.relativePath);
+    } else if (asset.hash) {
+      if (sha256(readFileSync(f.filePath)) !== asset.hash) modified.push(f.relativePath);
+    } else if (asset.sizeBytes != null && f.size !== asset.sizeBytes) {
+      modified.push(f.relativePath);
+    }
+  }
+
+  const removed = [
+    ...[...remotePages.keys()].map((route) => (route === "/" ? "index.html" : `${route.slice(1)}.html`)),
+    ...remoteAssets.keys(),
+  ];
+  return { added, modified, removed };
+}
+
+export async function status(args, { json = false } = {}) {
+  const dir = resolve(args.find((a) => !a.startsWith("-")) || ".");
+  const link = readLink(dir);
+  const slug = link?.site?.slug;
+
+  if (!slug) {
+    if (json) {
+      console.log(JSON.stringify({ linked: false }));
+      return;
+    }
+    err("This folder isn't linked to a site (no .htmlhost file).");
+    console.log(`    ${cyan("htmlhost deploy")} ${dim("to publish it, or")} ${cyan("htmlhost clone <slug>")} ${dim("to start from a live site.")}`);
+    process.exit(1);
+  }
+
+  const mode = link.site.mode;
+  let remote;
+  try {
+    remote = await get(`/api/sites/pull?slug=${encodeURIComponent(slug)}${mode === "file" ? "&meta=true" : ""}`);
+  } catch (e) {
+    err(`Couldn't reach ${slug}.htmlhost.co: ${e.message}`);
+    process.exit(1);
+  }
+
+  const localVersion = link.sync?.version ?? null;
+  const liveVersion = remote.version ?? null;
+  const remoteChanged = localVersion != null && liveVersion != null && liveVersion > localVersion;
+  // Single-file deploys rewrite and inline assets, so file contents can't be
+  // compared one-to-one; report the version state only.
+  const changes = mode === "directory" ? compareWithRemote(dir, remote) : null;
+  const clean = changes && !changes.added.length && !changes.modified.length && !changes.removed.length;
+
+  if (json) {
+    console.log(JSON.stringify({
+      linked: true,
+      slug,
+      url: `https://${slug}.htmlhost.co`,
+      mode,
+      localVersion,
+      liveVersion,
+      remoteChanged,
+      changes,
+    }));
+    return;
+  }
+
+  console.log("");
+  info(`Linked to ${cyan(bold(`${slug}.htmlhost.co`))} ${dim(`(${mode === "file" ? "single file" : "folder"})`)}`);
+
+  if (localVersion == null) {
+    warn(`Live version ${liveVersion}. This folder has no sync record yet — ${cyan("htmlhost pull")} to sync.`);
+  } else if (remoteChanged) {
+    warn(`The live site changed since your last sync ${dim(`(v${localVersion} → v${liveVersion})`)}. Run ${cyan("htmlhost pull")} before deploying.`);
+  } else {
+    ok(`Live site unchanged since your last sync ${dim(`(v${liveVersion})`)}`);
+  }
+
+  if (!changes) {
+    console.log(`  ${dim(`Single-file site — deploy with`)} ${cyan("htmlhost deploy <file>")}`);
+    console.log("");
+    return;
+  }
+
+  console.log("");
+  if (clean) {
+    ok("Nothing to deploy — the folder matches the live site.");
+    console.log("");
+    return;
+  }
+
+  // With the live site unchanged, every difference is a local edit; after a
+  // remote change a difference may be theirs, so say so.
+  console.log(`  ${bold(remoteChanged ? "Differences from the live site:" : "Changes to deploy:")}`);
+  for (const f of changes.added) console.log(`   ${green("+ new:     ")} ${f}`);
+  for (const f of changes.modified) console.log(`   ${yellow("~ modified:")} ${f}`);
+  for (const f of changes.removed) console.log(`   ${red("- removed: ")} ${f} ${dim("(only on the live site; deploy deletes it)")}`);
+  console.log("");
+  console.log(
+    `  ${dim("Run")} ${cyan(remoteChanged ? "htmlhost pull" : "htmlhost deploy")} ${dim(
+      remoteChanged ? "to bring in the live changes first." : "to publish these changes."
+    )}`
+  );
+  console.log("");
+}

package/src/commands/versions.mjs

@@ -0,0 +1,130 @@
+import { get, post } from "../api.mjs";
+import { ok, err, info, warn, dim, cyan, bold, confirm, formatBytes } from "../ui.mjs";
+import { readLink } from "../link.mjs";
+
+/** Explicit slug argument first, then the folder's .htmlhost link. */
+function resolveSlug(positional) {
+  return positional[0] || readLink(process.cwd())?.site?.slug || null;
+}
+
+function when(iso) {
+  const d = new Date(iso);
+  return d.toLocaleString("en-GB", { day: "numeric", month: "short", year: "numeric", hour: "2-digit", minute: "2-digit" });
+}
+
+function pad(str, width) {
+  const s = String(str);
+  const visible = s.replace(/\x1b\[[0-9;]*m/g, "");
+  return s + " ".repeat(Math.max(0, width - visible.length));
+}
+
+/**
+ * htmlhost versions [slug] [--json]
+ * Lists a site's published versions, newest first.
+ */
+export async function versions(args, { json = false } = {}) {
+  const positional = args.filter((a) => !a.startsWith("-"));
+  const slug = resolveSlug(positional);
+  if (!slug) {
+    err("No site given and no .htmlhost link here.");
+    console.log(`  Usage: ${cyan("htmlhost versions")} [slug]`);
+    process.exit(1);
+  }
+
+  const data = await get(`/api/sites/${encodeURIComponent(slug)}/versions`);
+  if (json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  console.log();
+  console.log(`  ${bold("Versions of")} ${cyan(`${data.slug}.htmlhost.co`)}`);
+  console.log();
+  if (!data.versions.length) {
+    console.log(dim("  No versions yet. Your next deploy will be the first."));
+    return;
+  }
+  for (const v of data.versions) {
+    const tag = v.live ? cyan(" live") : "";
+    const name = v.label ? bold(v.label) : v.summary;
+    const by = v.createdBy ? ` · ${v.createdBy}` : "";
+    console.log(`  ${pad(bold(`v${v.version}`), 6)}${tag} ${name}`);
+    console.log(dim(`        ${when(v.createdAt)} · ${v.source}${by} · ${v.pageCount} page${v.pageCount === 1 ? "" : "s"}, ${formatBytes(v.totalBytes)}`));
+  }
+  console.log();
+  if (data.usable) {
+    console.log(dim(`  Restore one with: htmlhost rollback ${data.slug} <version>`));
+  } else {
+    warn("Restoring earlier versions needs Pro: https://htmlhost.co/pricing");
+  }
+}
+
+/**
+ * htmlhost rollback [slug] [version] [--force]
+ * Publishes an earlier version again. Without a version, goes back to the one
+ * before the live version.
+ */
+export async function rollback(args, { json = false } = {}) {
+  const positional = args.filter((a) => !a.startsWith("-"));
+  const force = args.includes("--force") || args.includes("-f");
+  const isVersion = (s) => /^v?\d+$/i.test(s ?? "");
+
+  // `rollback 4`, `rollback my-site`, `rollback my-site 4`
+  let slugArg = null;
+  let versionArg = null;
+  if (positional.length >= 2) [slugArg, versionArg] = positional;
+  else if (isVersion(positional[0])) versionArg = positional[0];
+  else slugArg = positional[0] ?? null;
+
+  const slug = resolveSlug(slugArg ? [slugArg] : []);
+  if (!slug) {
+    err("No site given and no .htmlhost link here.");
+    console.log(`  Usage: ${cyan("htmlhost rollback")} [slug] [version]`);
+    process.exit(1);
+  }
+
+  const data = await get(`/api/sites/${encodeURIComponent(slug)}/versions`);
+  if (!data.usable) {
+    err("Restoring earlier versions needs Pro: https://htmlhost.co/pricing");
+    process.exit(1);
+  }
+  const live = data.versions.find((v) => v.live);
+  let target;
+  if (versionArg) {
+    const n = Number(String(versionArg).replace(/^v/i, ""));
+    target = data.versions.find((v) => v.version === n);
+    if (!target) {
+      err(`Version ${n} isn't in this site's history.`);
+      process.exit(1);
+    }
+  } else {
+    target = data.versions.find((v) => !v.live && (!live || v.version < live.version));
+    if (!target) {
+      err("There's no earlier version to go back to.");
+      process.exit(1);
+    }
+  }
+  if (target.live) {
+    info(`v${target.version} is already live.`);
+    return;
+  }
+
+  if (!force && !json) {
+    const yes = await confirm(`  Make v${target.version} (${when(target.createdAt)}) live again on ${cyan(bold(`${data.slug}.htmlhost.co`))}?`);
+    if (!yes) {
+      console.log("  Cancelled.");
+      return;
+    }
+  }
+
+  const result = await post(`/api/sites/${encodeURIComponent(data.slug)}/versions/${target.version}/restore`, {});
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const url = result.url ? (String(result.url).startsWith("http") ? result.url : `https://${result.url}`) : `https://${data.slug}.htmlhost.co`;
+  ok(`Restored v${target.version} → ${cyan(url)}`);
+  if (readLink(process.cwd())?.site?.slug === data.slug) {
+    console.log(dim(`  Your local files still have the newer version. Run ${cyan("htmlhost pull")} to match the site.`));
+  }
+}