htmlhost-cli 2.6.1 → 2.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlhost-cli",
-  "version": "2.6.1",
+  "version": "2.7.1",
   "description": "Deploy HTML files from the terminal — htmlhost.co CLI",
   "type": "module",
   "bin": {
@@ -26,5 +26,8 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/htmlhost/cli.git"
+  },
+  "scripts": {
+    "test": "node --test test/"
   }
 }

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.6.1";
+const VERSION = "2.7.1";
 
 const HELP = `
   ${bold("htmlhost")} ${dim(`v${VERSION}`)} — deploy HTML from the terminal
@@ -91,7 +91,10 @@ export async function run(argv) {
     args.push(...filtered);
   }
 
-  if (!command || command === "help" || command === "--help" || command === "-h") {
+  // `htmlhost <command> --help` must never run the command — for deploy that
+  // would scan the folder and prompt to overwrite the linked site.
+  if (!command || command === "help" || command === "--help" || command === "-h" ||
+      args.includes("--help") || args.includes("-h")) {
     console.log(HELP);
     return;
   }

package/src/commands/clone.mjs

@@ -10,6 +10,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from
 import { join, dirname, resolve } from "node:path";
 import { get, downloadBuffer } from "../api.mjs";
 import { fetchAgentGuide, writeAgentGuide } from "./agents.mjs";
+import { writeLink, directorySite } from "../link.mjs";
 import {
   ok,
   err,
@@ -24,7 +25,6 @@ import {
   formatBytes,
 } from "../ui.mjs";
 
-const LINK_FILE = ".htmlhost";
 
 /**
  * Map a page path to a local file path.
@@ -138,32 +138,16 @@ export async function clone(args) {
   }
 
   // --- Write .htmlhost link file ---
-  const isMultiPage = pageCount > 1;
-  const linkData = isMultiPage
-    ? {
-        multipage: {
-          slug: cleanSlug,
-          url: `${cleanSlug}.htmlhost.co`,
-          pageCount,
-        },
-        sync: {
-          version: data.version,
-          updatedAt: data.updatedAt,
-          pulledAt: new Date().toISOString(),
-        },
-      }
-    : {
-        slug: cleanSlug,
-        url: `${cleanSlug}.htmlhost.co`,
-        sync: {
-          version: data.version,
-          updatedAt: data.updatedAt,
-          pulledAt: new Date().toISOString(),
-        },
-      };
-
-  const linkPath = join(destDir, LINK_FILE);
-  writeFileSync(linkPath, JSON.stringify(linkData, null, 2) + "\n", "utf8");
+  // A clone is always the whole site as a folder, so it links in directory
+  // mode whatever the page count — `deploy` then updates this same site.
+  writeLink(destDir, {
+    site: directorySite(cleanSlug, pageCount),
+    sync: {
+      version: data.version,
+      updatedAt: data.updatedAt,
+      pulledAt: new Date().toISOString(),
+    },
+  });
 
   // Teach the user's AI coding tool how htmlhost works. Best-effort: a
   // failed download mustn't fail the clone.

package/src/commands/deploy.mjs

@@ -1,13 +1,12 @@
-import { readFileSync, writeFileSync, statSync, existsSync, readdirSync, mkdirSync } from "node:fs";
-import { basename, resolve, dirname, join, extname } from "node:path";
+import { readFileSync, statSync, readdirSync } from "node:fs";
+import { basename, resolve, dirname, join } from "node:path";
 import { createInterface } from "node:readline";
 import { createHash } from "node:crypto";
 import { post } from "../api.mjs";
 import { ok, err, info, warn, cyan, dim, bold, yellow, green, formatBytes, mimeFromExt } from "../ui.mjs";
 import { checkRemoteChanges } from "./pull.mjs";
 import { fetchAgentGuide, hasAgentGuide, writeAgentGuide } from "./agents.mjs";
-
-const LINK_FILE = ".htmlhost";
+import { readLink, writeLink, directorySite, directoryDeploySlug, fileDeploySlug } from "../link.mjs";
 
 /**
  * Upload a file to a presigned URL with automatic retry.
@@ -92,27 +91,6 @@ function shouldIgnore(name) {
   return DEFAULT_IGNORE.includes(name);
 }
 
-/**
- * Read the project link from .htmlhost
- */
-function readLink(dir) {
-  const linkPath = join(dir, LINK_FILE);
-  if (!existsSync(linkPath)) return null;
-  try {
-    return JSON.parse(readFileSync(linkPath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Save project link to .htmlhost
- */
-function writeLink(dir, data) {
-  const linkPath = join(dir, LINK_FILE);
-  writeFileSync(linkPath, JSON.stringify(data, null, 2) + "\n", "utf8");
-}
-
 /**
  * Simple y/N confirmation prompt.
  */
@@ -158,11 +136,12 @@ function promptChoice(question, options) {
  * - Use --new to force fresh deploys
  */
 export async function deploy(args, { json = false } = {}) {
-  let target = args.find((a) => !a.startsWith("--"));
+  const { positionals, values } = parseArgs(args, ["--ttl", "--title", "--slug"]);
+  const target = positionals[0];
 
-  const ttl = getFlag(args, "--ttl");
-  const title = getFlag(args, "--title");
-  const slug = getFlag(args, "--slug");
+  const ttl = values["--ttl"] ?? null;
+  const title = values["--title"] ?? null;
+  const slug = values["--slug"] ?? null;
   const forceNew = args.includes("--new");
   const skipAssets = args.includes("--no-assets");
   const skipPullCheck = args.includes("--no-pull-check");
@@ -199,18 +178,19 @@ async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug,
 
   if (!slug && !forceNew) {
     const link = readLink(projectDir);
+    const linkedSlug = fileDeploySlug(link);
 
-    if (link?.slug && !link?.multipage) {
-      // Single-file format
-      if (link.onRedeploy === "overwrite") {
-        slug = link.slug;
+    if (linkedSlug) {
+      const onRedeploy = link.site.onRedeploy;
+      if (onRedeploy === "overwrite") {
+        slug = linkedSlug;
         isLinked = true;
         info(`Linked to ${cyan(slug)} ${dim("(auto-overwrite)")}`);
-      } else if (link.onRedeploy === "new") {
+      } else if (onRedeploy === "new") {
         info(`Creating new site ${dim("(auto-new)")}`);
       } else {
         const choice = await promptChoice(
-          `This project is linked to ${cyan(bold(link.slug + ".htmlhost.co"))}`,
+          `This project is linked to ${cyan(bold(linkedSlug + ".htmlhost.co"))}`,
           [
             "Overwrite existing site",
             "Create a new site instead",
@@ -222,7 +202,7 @@ async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug,
 
         switch (choice) {
           case 0:
-            slug = link.slug;
+            slug = linkedSlug;
             isLinked = true;
             break;
           case 1:
@@ -233,13 +213,13 @@ async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug,
             process.exit(0);
             break;
           case 3:
-            slug = link.slug;
+            slug = linkedSlug;
             isLinked = true;
-            writeLink(projectDir, { ...link, onRedeploy: "overwrite" });
+            writeLink(projectDir, { ...link, site: { ...link.site, onRedeploy: "overwrite" } });
             info(`Saved preference: ${dim("always overwrite")}`);
             break;
           case 4:
-            writeLink(projectDir, { ...link, onRedeploy: "new" });
+            writeLink(projectDir, { ...link, site: { ...link.site, onRedeploy: "new" } });
             info(`Saved preference: ${dim("always create new")}`);
             break;
         }
@@ -293,11 +273,16 @@ async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug,
   const data = await post("/api/sites", body);
 
   // Save link
-  const existingLink = readLink(projectDir);
+  const existingLink = readLink(projectDir) || {};
+  const onRedeploy = existingLink.site?.mode === "file" ? existingLink.site.onRedeploy : undefined;
   writeLink(projectDir, {
-    slug: data.slug,
-    url: data.url,
-    ...(existingLink?.onRedeploy ? { onRedeploy: existingLink.onRedeploy } : {}),
+    ...existingLink,
+    site: {
+      slug: data.slug,
+      url: data.url,
+      mode: "file",
+      ...(onRedeploy ? { onRedeploy } : {}),
+    },
     sync: {
       version: data.version,
       updatedAt: new Date().toISOString(),
@@ -358,7 +343,8 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
 
   // Read existing link data
   const link = readLink(dirPath);
-  let existingSlug = explicitSlug || (!forceNew && link?.multipage?.slug) || null;
+  const linkedSlug = forceNew ? null : directoryDeploySlug(link);
+  let existingSlug = explicitSlug || linkedSlug || null;
 
   // Calculate total size
   const totalSize = allFiles.reduce((sum, f) => sum + f.size, 0);
@@ -490,13 +476,7 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
     // Write .htmlhost early so a crash mid-upload doesn't orphan the site
     if (generatedSlug && !existingSlug) {
       existingSlug = generatedSlug;
-      writeLink(dirPath, {
-        multipage: {
-          slug: existingSlug,
-          url: `${existingSlug}.htmlhost.co`,
-          pageCount: pagePayloads.length,
-        },
-      });
+      writeLink(dirPath, { site: directorySite(existingSlug, pagePayloads.length) });
     }
 
     for (const u of uploadUrls) {
@@ -529,7 +509,7 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
   if (existingSlug) {
     body.slug = existingSlug;
     // We pass isNewSite only if the generated slug wasn't originally provided
-    if (!explicitSlug && !(!forceNew && link?.multipage?.slug)) {
+    if (!explicitSlug && !linkedSlug) {
       body.isNewSite = true;
     }
   }
@@ -540,11 +520,8 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
 
     // Save link
     writeLink(dirPath, {
-      multipage: {
-        slug: data.slug,
-        url: data.url,
-        pageCount: data.pageCount || pagePayloads.length,
-      },
+      ...(link || {}),
+      site: { ...directorySite(data.slug, data.pageCount || pagePayloads.length), url: data.url },
       sync: {
         version: data.version,
         updatedAt: new Date().toISOString(),
@@ -690,8 +667,24 @@ function findAllFiles(baseDir, currentDir) {
   return results;
 }
 
-function getFlag(args, flag) {
-  const idx = args.indexOf(flag);
-  if (idx === -1 || idx >= args.length - 1) return null;
-  return args[idx + 1];
+/**
+ * Split args into positionals and flag values. Each flag in `valueFlags`
+ * consumes the next arg (or takes `--flag=value`), so `deploy --ttl 1d`
+ * doesn't mistake "1d" for the deploy target.
+ */
+export function parseArgs(args, valueFlags) {
+  const positionals = [];
+  const values = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    const eq = a.indexOf("=");
+    const name = eq === -1 ? a : a.slice(0, eq);
+    if (valueFlags.includes(name)) {
+      if (eq !== -1) values[name] = a.slice(eq + 1);
+      else if (i + 1 < args.length) values[name] = args[++i];
+    } else if (!a.startsWith("-")) {
+      positionals.push(a);
+    }
+  }
+  return { positionals, values };
 }

package/src/commands/pull.mjs

@@ -8,6 +8,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from "no
 import { join, dirname, resolve, basename } from "node:path";
 import { createHash } from "node:crypto";
 import { get, downloadBuffer } from "../api.mjs";
+import { readLink, writeLink } from "../link.mjs";
 import {
   ok,
   err,
@@ -22,29 +23,6 @@ import {
   formatBytes,
 } from "../ui.mjs";
 
-const LINK_FILE = ".htmlhost";
-
-/**
- * Read the project link from .htmlhost
- */
-function readLink(dir) {
-  const linkPath = join(dir, LINK_FILE);
-  if (!existsSync(linkPath)) return null;
-  try {
-    return JSON.parse(readFileSync(linkPath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Save project link to .htmlhost
- */
-function writeLink(dir, data) {
-  const linkPath = join(dir, LINK_FILE);
-  writeFileSync(linkPath, JSON.stringify(data, null, 2) + "\n", "utf8");
-}
-
 /**
  * Map a page path back to a local file path.
  * "/" → "index.html", "/about" → "about.html", "/blog" → "blog/index.html" or "blog.html"
@@ -89,11 +67,7 @@ export async function pull(args) {
   // Resolve slug
   let slug = slugArg;
   if (!slug) {
-    if (link?.multipage?.slug) {
-      slug = link.multipage.slug;
-    } else if (link?.slug) {
-      slug = link.slug;
-    }
+    slug = link?.site?.slug;
   }
 
   if (!slug) {

package/src/commands/recipients.mjs

@@ -1,22 +1,10 @@
 import { get, post } from "../api.mjs";
 import { ok, err, info, dim, cyan, bold, yellow, confirm } from "../ui.mjs";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { readLink } from "../link.mjs";
 
-const LINK_FILE = ".htmlhost";
-
-/**
- * Read the slug from .htmlhost in the given (or current) directory.
- */
+/** The slug linked by .htmlhost in the given (or current) directory. */
 function readSlugFromLink(dir = process.cwd()) {
-  const linkPath = join(dir, LINK_FILE);
-  if (!existsSync(linkPath)) return null;
-  try {
-    const data = JSON.parse(readFileSync(linkPath, "utf8"));
-    return data.multipage?.slug || data.slug || null;
-  } catch {
-    return null;
-  }
+  return readLink(dir)?.site?.slug || null;
 }
 
 /**

package/src/link.mjs

@@ -0,0 +1,95 @@
+/**
+ * The .htmlhost link file — ties a local directory to a hosted site.
+ *
+ *   {
+ *     "site": {
+ *       "slug": "my-site",
+ *       "url": "my-site.htmlhost.co",
+ *       "mode": "directory",       // how the site is deployed from here
+ *       "pageCount": 1,            // directory mode only, informational
+ *       "onRedeploy": "overwrite"  // file mode only, remembered prompt choice
+ *     },
+ *     "sync": { "version": 3, "updatedAt": "…", "pulledAt": "…", "deployedAt": "…" },
+ *     "assets": { "img/a.png": "https://…" }  // single-file asset upload cache
+ *   }
+ *
+ * `mode` records the workflow, not the page count: "directory" means the whole
+ * folder is the site (any number of pages plus assets — what `clone` and
+ * `deploy <dir>` produce); "file" means one HTML file deployed on its own.
+ *
+ * Older CLIs wrote `{ multipage: {slug, url, pageCount} }` for directory sites
+ * and a top-level `{ slug, url, onRedeploy }` otherwise — including for cloned
+ * one-page sites, so a legacy top-level link is not proof of a single-file
+ * deploy. `readLink` accepts both and always returns the current shape;
+ * `writeLink` only writes the current shape.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const LINK_FILE = ".htmlhost";
+
+/** Normalize parsed link JSON (current or legacy) to the current shape, or null. */
+export function normalizeLink(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  let site = null;
+  if (raw.site?.slug) {
+    site = { ...raw.site, mode: raw.site.mode === "file" ? "file" : "directory" };
+  } else if (raw.multipage?.slug) {
+    site = { ...raw.multipage, mode: "directory" };
+  } else if (raw.slug) {
+    site = {
+      slug: raw.slug,
+      url: raw.url || `${raw.slug}.htmlhost.co`,
+      mode: "file",
+      ...(raw.onRedeploy ? { onRedeploy: raw.onRedeploy } : {}),
+    };
+  }
+  const link = {};
+  if (site) link.site = site;
+  if (raw.sync) link.sync = raw.sync;
+  if (raw.assets) link.assets = raw.assets;
+  return link;
+}
+
+/** Read and normalize `dir/.htmlhost`, or null when absent/unreadable. */
+export function readLink(dir) {
+  const linkPath = join(dir, LINK_FILE);
+  if (!existsSync(linkPath)) return null;
+  try {
+    return normalizeLink(JSON.parse(readFileSync(linkPath, "utf8")));
+  } catch {
+    return null;
+  }
+}
+
+/** Write `dir/.htmlhost` in the current shape. */
+export function writeLink(dir, link) {
+  const out = {};
+  if (link.site) out.site = link.site;
+  if (link.sync) out.sync = link.sync;
+  if (link.assets) out.assets = link.assets;
+  writeFileSync(join(dir, LINK_FILE), JSON.stringify(out, null, 2) + "\n", "utf8");
+}
+
+/** Site metadata for a directory-mode link. */
+export function directorySite(slug, pageCount) {
+  return { slug, url: `${slug}.htmlhost.co`, mode: "directory", pageCount };
+}
+
+/**
+ * The slug a directory deploy should update. Any linked site qualifies: a
+ * directory deploy of a folder linked to a single-file site promotes it to a
+ * directory site (after the usual overwrite confirmation), matching how the
+ * platform grows a one-page project into a multi-file one.
+ */
+export function directoryDeploySlug(link) {
+  return link?.site?.slug || null;
+}
+
+/**
+ * The slug a single-file deploy may offer to overwrite. Only file-mode links:
+ * deploying one file over a directory site would replace all its pages.
+ */
+export function fileDeploySlug(link) {
+  return link?.site?.mode === "file" ? link.site.slug : null;
+}