htmlhost-cli 2.7.1 → 2.8.0

package/README.md

@@ -87,6 +87,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.
 

package/package.json

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

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.8.0";
 
 const HELP = `
   ${bold("htmlhost")} ${dim(`v${VERSION}`)} — deploy HTML from the terminal
@@ -13,6 +13,7 @@ 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)
@@ -37,6 +38,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
@@ -69,6 +73,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 +139,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);

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("");
+}