htmlhost-cli 2.11.0 → 2.13.0

package/README.md

@@ -174,7 +174,7 @@ htmlhost agents --no-claude  # don't touch CLAUDE.md
 The same guide is at https://htmlhost.co/agents.md.
 
 ### `htmlhost list`
-List all your sites with titles, sizes, TTL, and expiry. Multi-page sites are marked with 📄.
+List all your sites with titles, sizes, TTL, and expiry. Multi-page sites are marked with 📄. Sites shared with you as a collaborator follow under **Shared with you**, with their owner: `clone`, `deploy` and `versions` work on them with your own sign-in; only the owner can delete them.
 
 ### `htmlhost open <slug>`
 Open a deployed site in the default browser.
@@ -223,3 +223,14 @@ MIT
 ### Free publishing allowance
 
 Free publishing is limited. Subscribe to Pro to continue creating unlimited sites at https://htmlhost.co/upgrade. See Pro benefits at https://htmlhost.co/pricing. Before your first free CLI deployment, sign in at https://htmlhost.co/new to complete browser verification. If verification is unavailable, contact hey@htmlhost.co for review.
+
+
+## Unpublished sites and drafts
+
+Unpublished websites remain private until publishing is explicitly confirmed. Collaborators can publish with confirmation; only owners can unpublish. The server also cancels deployments still running when someone unpublishes.
+
+- `htmlhost deploy --draft` saves files without changing publication.
+- `htmlhost deploy --publish` explicitly makes an unpublished website public. The same flag applies to `rollback`.
+- Interactive deploys ask a separate, default-No question when the website is unpublished. `--force` and `--json` never grant this permission. Agents must obtain the user's consent before using `--publish`.
+- `htmlhost unpublish <slug>` takes the website offline while retaining files and history. Non-interactive use requires `--yes` after owner confirmation.
+- `list` labels owned and shared drafts. `pull` / `clone` retrieve working files, including saved drafts, by default; `--published` selects the last deployed files and `--draft` requires a draft.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "htmlhost-cli",
-  "version": "2.11.0",
-  "description": "Deploy HTML files from the terminal — htmlhost.co CLI",
+  "version": "2.13.0",
+  "description": "Deploy HTML files from the terminal \u2014 htmlhost.co CLI",
   "type": "module",
   "bin": {
     "htmlhost": "bin/htmlhost.mjs"
@@ -28,6 +28,6 @@
     "url": "git+https://github.com/htmlhost/cli.git"
   },
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --experimental-test-module-mocks --test test/"
   }
 }

package/src/api.mjs

@@ -5,9 +5,10 @@ import { getToken, getApi } from "./config.mjs";
 import { dim, yellow } from "./ui.mjs";
 
 export class ApiError extends Error {
-  constructor(message, status) {
+  constructor(message, status, code) {
     super(message);
     this.status = status;
+    this.code = code;
   }
 }
 
@@ -19,9 +20,9 @@ const BASE_DELAY_MS = 500;
  * Retries on network errors ("fetch failed", ECONNRESET, etc.)
  * and 5xx server errors. Does NOT retry on 4xx client errors.
  */
-async function withRetry(fn, label = "request") {
+async function withRetry(fn, label = "request", attempts = MAX_RETRIES) {
   let lastError;
-  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+  for (let attempt = 1; attempt <= attempts; attempt++) {
     try {
       return await fn();
     } catch (e) {
@@ -30,13 +31,13 @@ async function withRetry(fn, label = "request") {
         !(e instanceof ApiError) ||
         (e.status >= 500 && e.status < 600);
 
-      if (!isNetworkError || attempt === MAX_RETRIES) {
+      if (!isNetworkError || attempt === attempts) {
         throw e;
       }
 
       const delay = BASE_DELAY_MS * Math.pow(2, attempt - 1);
       console.log(
-        `   ${yellow("↻")} ${label} failed (attempt ${attempt}/${MAX_RETRIES}), retrying in ${delay}ms… ${dim(e.message)}`
+        `   ${yellow("↻")} ${label} failed (attempt ${attempt}/${attempts}), retrying in ${delay}ms… ${dim(e.message)}`
       );
       await new Promise((r) => setTimeout(r, delay));
     }
@@ -60,7 +61,7 @@ export async function get(path) {
       headers: headers(),
     });
     const data = await res.json();
-    if (!res.ok) throw new ApiError(data.error || `HTTP ${res.status}`, res.status);
+    if (!res.ok) throw new ApiError(data.error || `HTTP ${res.status}`, res.status, data.code);
     return data;
   }, `GET ${path}`);
 }
@@ -73,9 +74,9 @@ export async function post(path, body) {
       body: JSON.stringify(body),
     });
     const data = await res.json();
-    if (!res.ok) throw new ApiError(data.error || `HTTP ${res.status}`, res.status);
+    if (!res.ok) throw new ApiError(data.error || `HTTP ${res.status}`, res.status, data.code);
     return data;
-  }, `POST ${path}`);
+  }, `POST ${path}`, body?.confirmPublish === true ? 1 : MAX_RETRIES);
 }
 
 export async function del(path) {
@@ -85,7 +86,7 @@ export async function del(path) {
       headers: headers(),
     });
     const data = await res.json();
-    if (!res.ok) throw new ApiError(data.error || `HTTP ${res.status}`, res.status);
+    if (!res.ok) throw new ApiError(data.error || `HTTP ${res.status}`, res.status, data.code);
     return data;
   }, `DELETE ${path}`);
 }
@@ -108,7 +109,7 @@ export async function uploadFile(path, filePath, fileName, mimeType) {
       body: form,
     });
     const data = await res.json();
-    if (!res.ok) throw new ApiError(data.error || `HTTP ${res.status}`, res.status);
+    if (!res.ok) throw new ApiError(data.error || `HTTP ${res.status}`, res.status, data.code);
     return data;
   }, `upload ${fileName}`);
 }

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.11.0";
+const VERSION = "2.13.0";
 
 const HELP = `
   ${bold("htmlhost")} ${dim(`v${VERSION}`)} — deploy HTML from the terminal
@@ -17,11 +17,12 @@ const HELP = `
     ${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 recipients")} [slug] [cmd]  Manage form notification recipients (owner)
+    ${cyan("htmlhost list")}                     List your sites and ones shared with you
     ${cyan("htmlhost versions")} [slug]         List a site's published versions
+    ${cyan("htmlhost unpublish")} [slug]       Take a site offline (owner only)
     ${cyan("htmlhost rollback")} [slug] [ver]    Make an earlier version live again (Pro)
-    ${cyan("htmlhost delete")} <slug>            Delete a site
+    ${cyan("htmlhost delete")} <slug>            Delete a site (owner)
     ${cyan("htmlhost login")}                    Sign in (approve in your browser)
     ${cyan("htmlhost whoami")}                   Show current user
     ${cyan("htmlhost logout")}                   Remove saved token
@@ -33,6 +34,8 @@ const HELP = `
     --title <title>   Set the site title
     --new             Force a new site (ignore .htmlhost link)
     --no-assets       Skip auto-uploading local assets (single-file only)
+    --draft          Save as a draft; leave publication unchanged
+    --publish        Explicitly make an unpublished site public
     --no-pull-check   Skip remote change detection before deploy
 
   ${bold("Upload options:")}
@@ -139,6 +142,11 @@ export async function run(argv) {
         await whoami();
         break;
       }
+      case "unpublish": {
+        const { unpublish } = await import("./commands/unpublish.mjs");
+        await unpublish(args, { json: jsonMode });
+        break;
+      }
       case "deploy": {
         const { deploy } = await import("./commands/deploy.mjs");
         await deploy(args, { json: jsonMode });

package/src/commands/clone.mjs

@@ -44,6 +44,8 @@ export async function clone(args) {
   const positionals = args.filter((a) => !a.startsWith("--"));
   const slug = positionals[0];
   const targetDir = positionals[1]; // optional — defaults to slug name
+  const source = args.includes("--published") ? "published" : args.includes("--draft") ? "draft" : "working";
+  if (args.includes("--published") && args.includes("--draft")) throw new Error("Choose --published or --draft, not both.");
   const force = args.includes("--force") || args.includes("-f");
 
   if (!slug) {
@@ -86,12 +88,14 @@ export async function clone(args) {
   // Fetch remote content
   let data;
   try {
-    data = await get(`/api/sites/pull?slug=${encodeURIComponent(cleanSlug)}`);
+    data = await get(`/api/sites/pull?slug=${encodeURIComponent(cleanSlug)}&source=${source}`);
   } catch (e) {
     err(`Failed to fetch site: ${e.message}`);
     process.exit(1);
   }
 
+  info(`${data.source === "draft" ? "Saved draft" : "Last published files"} · ${data.isPublished === false ? "website is unpublished" : "website is published"}`);
+
   const pageCount = (data.pages || []).length;
   const assetCount = (data.assets || []).length;
   const totalFiles = pageCount + assetCount;

package/src/commands/deploy.mjs

@@ -1,7 +1,8 @@
 import { readFileSync, statSync, readdirSync, existsSync } from "node:fs";
-import { basename, resolve, dirname, join } from "node:path";
+import { basename, resolve, dirname, join, sep } from "node:path";
 import { createInterface } from "node:readline";
 import { createHash } from "node:crypto";
+import { postPublication } from "../publication.mjs";
 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";
@@ -145,6 +146,9 @@ export async function deploy(args, { json = false } = {}) {
   const ttl = values["--ttl"] ?? null;
   const title = values["--title"] ?? null;
   const slug = values["--slug"] ?? null;
+  const confirmPublish = args.includes("--publish");
+  const isDraft = args.includes("--draft");
+  if (confirmPublish && isDraft) throw new Error("Choose --draft or --publish, not both.");
   const forceNew = args.includes("--new");
   const skipAssets = args.includes("--no-assets");
   const skipPullCheck = args.includes("--no-pull-check");
@@ -162,17 +166,17 @@ export async function deploy(args, { json = false } = {}) {
 
   // --- Directory deploy (default) ---
   if (stat.isDirectory()) {
-    return deployDirectory(targetPath, { ttl, title, slug, forceNew, json, skipPullCheck });
+    return deployDirectory(targetPath, { ttl, title, slug, forceNew, json, skipPullCheck, confirmPublish, isDraft });
   }
 
   // --- Single-file deploy ---
-  await deploySingleFile(target || "index.html", { ttl, title, forceNew, skipAssets, slug, json, skipPullCheck });
+  await deploySingleFile(target || "index.html", { ttl, title, forceNew, skipAssets, slug, json, skipPullCheck, confirmPublish, isDraft });
 }
 
 /**
  * Deploy a single HTML file (existing behavior preserved).
  */
-async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug, json, skipPullCheck }) {
+async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug, json, skipPullCheck, confirmPublish, isDraft }) {
   const filePath = resolve(file);
   const projectDir = dirname(filePath);
   const fileName = basename(filePath);
@@ -268,12 +272,12 @@ async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug,
     if (aborted) return;
   }
 
-  const body = { html };
+  const body = { html, confirmPublish, isDraft };
   if (ttl) body.ttl = ttl;
   if (slug) body.slug = slug;
   if (title) body.title = title;
 
-  const data = await post("/api/sites", body);
+  const data = await postPublication("/api/sites", body, { json });
 
   // Save link
   const existingLink = readLink(projectDir) || {};
@@ -299,7 +303,7 @@ async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug,
   }
 
   console.log("");
-  ok(`${bold("Live")} at ${cyan(`https://${data.url}`)}`);
+  ok(isDraft ? `${bold("Draft saved")} · ${data.isPublished === false ? "not public" : "live site unchanged"}` : `${bold("Live")} at ${cyan(`https://${data.url}`)}`);
   if (data.version > 1) {
     console.log(`   ${dim(`Version ${data.version} · ${data.ttl} TTL`)}`);
   } else {
@@ -321,7 +325,7 @@ async function deploySingleFile(file, { ttl, title, forceNew, skipAssets, slug,
  * Non-HTML files (CSS, JS, images, fonts) are uploaded via the media endpoint
  * and included as pages with their hosted URLs.
  */
-async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceNew, json, skipPullCheck }) {
+async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceNew, json, skipPullCheck, confirmPublish, isDraft }) {
   // Find all files recursively
   const allFiles = findAllFiles(dirPath, dirPath);
 
@@ -519,7 +523,7 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
   console.log("");
   info(existingSlug ? `Deploying to ${cyan(existingSlug)}…` : "Deploying new site…");
 
-  const body = { pages: pagePayloads, assets: assetPayloads };
+  const body = { pages: pagePayloads, assets: assetPayloads, confirmPublish, isDraft };
   if (redirectsText !== null) body.redirects = redirectsText;
   if (ttl) body.ttl = ttl;
   if (existingSlug) {
@@ -532,7 +536,7 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
   if (title) body.title = title;
 
   try {
-    const data = await post("/api/sites", body);
+    const data = await postPublication("/api/sites", body, { json });
 
     // Save link
     writeLink(dirPath, {
@@ -554,11 +558,11 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
     const ac = assetPayloads.length;
     console.log("");
     console.log(`  ${green("━".repeat(40))}`);
-    ok(`${bold("Live")} at ${cyan(`https://${data.url}`)}`);
+    ok(isDraft ? `${bold("Draft saved")} · ${data.isPublished === false ? "not public" : "live site unchanged"}` : `${bold("Live")} at ${cyan(`https://${data.url}`)}`);
     console.log(`   ${dim(`${pc} page${pc !== 1 ? "s" : ""} · ${ac} asset${ac !== 1 ? "s" : ""} · ${data.ttl} TTL`)}`);
     console.log("");
 
-    for (const { path: pagePath } of pagePayloads) {
+    for (const { path: pagePath } of (isDraft ? [] : pagePayloads)) {
       const urlPath = pagePath === "/" ? "" : pagePath;
       console.log(`   ${cyan(`https://${data.url}${urlPath}`)}`);
     }
@@ -666,7 +670,9 @@ export function findAllFiles(baseDir, currentDir) {
     if (entry.isDirectory()) {
       results.push(...findAllFiles(baseDir, fullPath));
     } else if (entry.isFile()) {
-      const relativePath = fullPath.slice(baseDir.length + 1);
+      // Always with "/": on Windows the path has "\", which would publish
+      // assets\logo.png, an address no browser can ask for.
+      const relativePath = fullPath.slice(baseDir.length + 1).split(sep).join("/");
       let size;
       try {
         size = statSync(fullPath).size;

package/src/commands/list.mjs

@@ -2,7 +2,8 @@ import { get } from "../api.mjs";
 import { dim, cyan, bold, formatBytes, yellow } from "../ui.mjs";
 
 /**
- * htmlhost list — show all sites.
+ * htmlhost list — show all sites: your own, then the ones shared with you
+ * (you can clone, deploy and restore those, not delete them).
  */
 export async function list({ json = false } = {}) {
   const data = await get("/api/sites");
@@ -13,8 +14,9 @@ export async function list({ json = false } = {}) {
   }
 
   const sites = data.sites || [];
+  const shared = data.shared || [];
 
-  if (sites.length === 0) {
+  if (sites.length === 0 && shared.length === 0) {
     console.log("");
     console.log(`  ${dim("No sites yet.")} Deploy one with: ${cyan("htmlhost deploy index.html")}`);
     console.log("");
@@ -33,6 +35,7 @@ export async function list({ json = false } = {}) {
     pad("TITLE", clampedTitleW),
     pad("SIZE", 10),
     pad("TTL", 8),
+    pad("STATUS", 12),
     pad("EXPIRES", 14),
   ].join("");
   console.log(`  ${dim(hdr)}`);
@@ -44,10 +47,21 @@ export async function list({ json = false } = {}) {
     const multiIndicator = s.isMultiPage ? "📄 " : "";
     const title = truncate(s.title && s.title !== s.slug ? s.title : "", clampedTitleW - 2);
     console.log(
-      `  ${pad(cyan(multiIndicator + s.slug), slugW + (multiIndicator ? 2 : 0))}${pad(dim(title), clampedTitleW)}${pad(s.size, 10)}${pad(s.ttl, 8)}${expiresColor(expires)}`
+      `  ${pad(cyan(multiIndicator + s.slug), slugW + (multiIndicator ? 2 : 0))}${pad(dim(title), clampedTitleW)}${pad(s.size, 10)}${pad(s.ttl, 8)}${pad(s.isPublished === false ? "Draft" : "Published", 12)}${expiresColor(expires)}`
     );
   }
 
+  if (shared.length) {
+    const sharedSlugW = Math.max(14, ...shared.map((s) => s.slug.length)) + 2;
+    console.log("");
+    console.log(`  ${bold("Shared with you")} ${dim("(clone, deploy and restore; only the owner can delete)")}`);
+    console.log(`  ${dim(pad("SLUG", sharedSlugW) + pad("TITLE", 30) + pad("STATUS", 12) + "OWNER")}`);
+    for (const s of shared) {
+      const title = truncate(s.title && s.title !== s.slug ? s.title : "", 28);
+      console.log(`  ${pad(cyan(s.slug), sharedSlugW)}${pad(dim(title), 30)}${pad(s.isPublished === false ? "Draft" : "Published", 12)}${dim(s.owner || "")}`);
+    }
+  }
+
   console.log("");
   console.log(
     `  ${bold(String(sites.length))} sites · ${formatBytes(data.usage.totalBytes)} used` +

package/src/commands/pull.mjs

@@ -58,6 +58,8 @@ function diffFile(localPath, remoteContent) {
  */
 export async function pull(args) {
   const slugArg = args.find((a) => !a.startsWith("--"));
+  const source = args.includes("--published") ? "published" : args.includes("--draft") ? "draft" : "working";
+  if (args.includes("--published") && args.includes("--draft")) throw new Error("Choose --published or --draft, not both.");
   const force = args.includes("--force") || args.includes("-f");
   const dryRun = args.includes("--dry-run");
 
@@ -90,12 +92,14 @@ export async function pull(args) {
   // Fetch remote content
   let data;
   try {
-    data = await get(`/api/sites/pull?slug=${encodeURIComponent(slug)}`);
+    data = await get(`/api/sites/pull?slug=${encodeURIComponent(slug)}&source=${source}`);
   } catch (e) {
     err(`Failed to fetch site: ${e.message}`);
     process.exit(1);
   }
 
+  info(`${data.source === "draft" ? "Saved draft" : "Last published files"} · ${data.isPublished === false ? "website is unpublished" : "website is published"}`);
+
   console.log(`  ${dim(`Version ${data.version} · Updated ${relTime(data.updatedAt)}`)}`);
   console.log("");
 

package/src/commands/unpublish.mjs

@@ -0,0 +1,15 @@
+import { post } from "../api.mjs";
+import { readLink } from "../link.mjs";
+import { confirm, ok } from "../ui.mjs";
+
+export async function unpublish(args, { json = false } = {}) {
+  const slug = (args.find(a => !a.startsWith("-")) || readLink(process.cwd())?.site?.slug)?.replace(/\.htmlhost\.co$/, "");
+  if (!slug) throw new Error("Usage: htmlhost unpublish <slug> [--yes]");
+  if (!args.includes("--yes")) {
+    if (json || !process.stdin.isTTY) throw new Error("Unpublishing takes the website offline. Re-run with --yes after confirming with the owner.");
+    if (!await confirm(`Take ${slug}.htmlhost.co and its connected domains offline? Files will be kept as a draft.`)) return;
+  }
+  const result = await post(`/api/sites/${encodeURIComponent(slug)}/unpublish`, {});
+  if (json) console.log(JSON.stringify(result));
+  else ok(`${slug} is unpublished. Files, drafts and history are kept.`);
+}

package/src/commands/versions.mjs

@@ -1,3 +1,4 @@
+import { postPublication } from "../publication.mjs";
 import { get, post } from "../api.mjs";
 import { ok, err, info, warn, dim, cyan, bold, confirm, formatBytes } from "../ui.mjs";
 import { readLink } from "../link.mjs";
@@ -117,7 +118,7 @@ export async function rollback(args, { json = false } = {}) {
     }
   }
 
-  const result = await post(`/api/sites/${encodeURIComponent(data.slug)}/versions/${target.version}/restore`, {});
+  const result = await postPublication(`/api/sites/${encodeURIComponent(data.slug)}/versions/${target.version}/restore`, { confirmPublish: args.includes("--publish") }, { json });
   if (json) {
     console.log(JSON.stringify(result, null, 2));
     return;

package/src/publication.mjs

@@ -0,0 +1,21 @@
+import { createInterface } from "node:readline/promises";
+import { post } from "./api.mjs";
+
+/** Never let --force, --json or a general deployment confirmation publish a draft. */
+export async function postPublication(path, body, { json = false } = {}) {
+  try {
+    return await post(path, body);
+  } catch (error) {
+    if (error.code !== "PUBLICATION_CONFIRMATION_REQUIRED") throw error;
+    if (json || !process.stdin.isTTY || !process.stdout.isTTY) {
+      error.message += " Ask the user first, then re-run with --publish to confirm making it public; use deploy --draft to keep it private.";
+      throw error;
+    }
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    let answer;
+    try { answer = await prompt.question("This website is unpublished. Make it publicly accessible now? (y/N) "); }
+    finally { prompt.close(); }
+    if (!/^y(es)?$/i.test(answer.trim())) throw new Error("Publishing cancelled. The website remains unpublished.");
+    return post(path, { ...body, confirmPublish: true });
+  }
+}