htmlhost-cli 2.3.0 → 2.5.0

package/README.md

@@ -131,6 +131,17 @@ push changes and `htmlhost pull` to sync remote edits.
 
 Use `--force` to overwrite an existing non-empty directory.
 
+### `htmlhost agents [dir] [options]`
+Teach your AI coding tool (Claude Code, Codex, Cursor, Copilot…) how htmlhost works: static hosting rules, this CLI, and how to build forms that deliver to your inbox. Writes a managed block into `AGENTS.md` (your own content is kept) and adds an `@AGENTS.md` import to `CLAUDE.md`. `clone` adds it automatically, and `deploy` keeps it current. Agent files are never deployed.
+
+```bash
+htmlhost agents              # add or refresh
+htmlhost agents --print      # print the guide instead
+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 📄.
 

package/package.json

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

package/src/api.mjs

@@ -112,6 +112,57 @@ export async function uploadFile(path, filePath, fileName, mimeType) {
   }, `upload ${fileName}`);
 }
 
+const DIRECT_UPLOAD_THRESHOLD = 4 * 1024 * 1024; // 4 MB
+
+/**
+ * Upload a media file. Automatically switches between multipart POST (<=4MB)
+ * and direct-to-R2 presigned upload (>4MB) to stay within Vercel body limits.
+ */
+export async function uploadMediaFile(filePath, fileName, mimeType) {
+  const { statSync, readFileSync } = await import("node:fs");
+  const stats = statSync(filePath);
+  const size = stats.size;
+
+  if (size <= DIRECT_UPLOAD_THRESHOLD) {
+    const data = await uploadFile("/api/media", filePath, fileName, mimeType);
+    return {
+      ...data,
+      fullUrl: `${getApi()}${data.url}`,
+    };
+  }
+
+  // Large file direct-to-R2 flow
+  return withRetry(async () => {
+    // 1. Get presigned upload URL
+    const presign = await post("/api/media/presign", {
+      filename: fileName,
+      mimeType,
+      size,
+    });
+
+    // 2. Direct PUT to R2
+    const fileBuffer = readFileSync(filePath);
+    const putRes = await fetch(presign.uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": mimeType },
+      body: fileBuffer,
+    });
+    if (!putRes.ok) {
+      throw new ApiError(`Direct upload failed: HTTP ${putRes.status}`, putRes.status);
+    }
+
+    // 3. Confirm upload
+    const confirmed = await post("/api/media/confirm", {
+      key: presign.key,
+    });
+
+    return {
+      ...confirmed,
+      fullUrl: `${getApi()}${confirmed.url}`,
+    };
+  }, `upload ${fileName} (direct)`);
+}
+
 /**
  * Download a file from a URL as a Buffer.
  * Used for fetching binary assets via presigned R2 download URLs.
@@ -124,3 +175,4 @@ export async function downloadBuffer(url) {
   return Buffer.from(arrayBuffer);
 }
 
+

package/src/cli.mjs

@@ -5,15 +5,17 @@ import { bold, dim, cyan, err } from "./ui.mjs";
 import { ApiError } from "./api.mjs";
 import { startUpdateCheck, applyUpdate } from "./update.mjs";
 
-const VERSION = "2.3.0";
+const VERSION = "2.5.0";
 
 const HELP = `
   ${bold("htmlhost")} ${dim(`v${VERSION}`)} — deploy HTML from the terminal
 
   ${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 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 list")}                     List your sites
     ${cyan("htmlhost delete")} <slug>            Delete a site
     ${cyan("htmlhost login")}                    Authenticate with an API token
@@ -29,10 +31,19 @@ const HELP = `
     --no-assets       Skip auto-uploading local assets (single-file only)
     --no-pull-check   Skip remote change detection before deploy
 
+  ${bold("Upload options:")}
+    --open            Open the uploaded media URL in browser
+    --no-copy         Skip copying the URL to clipboard
+    --json            Output response as JSON
+
   ${bold("Pull options:")}
     --force, -f       Pull without confirmation prompt
     --dry-run         Show what would change without writing
 
+  ${bold("Agents options:")}
+    --print           Print the guide instead of writing files
+    --no-claude       Don't add the @AGENTS.md import to CLAUDE.md
+
   ${bold("Delete options:")}
     --force, -f       Skip confirmation prompt
 
@@ -47,13 +58,11 @@ const HELP = `
     ${dim("$")} htmlhost deploy                ${dim("# deploys cwd as a site")}
     ${dim("$")} htmlhost deploy ./my-project   ${dim("# deploys a specific folder")}
     ${dim("$")} htmlhost deploy page.html      ${dim("# deploys a single file")}
-    ${dim("$")} htmlhost deploy --ttl 30d      ${dim("# deploy with 30-day TTL")}
-    ${dim("$")} htmlhost deploy --new          ${dim("# force new site")}
-    ${dim("$")} htmlhost deploy --json         ${dim("# JSON output for CI/CD")}
+    ${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 pull                  ${dim("# pull remote changes")}
-    ${dim("$")} htmlhost pull my-site --force  ${dim("# pull without prompting")}
     ${dim("$")} htmlhost clone my-site         ${dim("# clone into ./my-site/")}
-    ${dim("$")} htmlhost clone my-site ./proj  ${dim("# clone into ./proj/")}
     ${dim("$")} htmlhost delete old-project --force
 
   ${bold("Update:")}
@@ -109,6 +118,11 @@ export async function run(argv) {
         await deploy(args, { json: jsonMode });
         break;
       }
+      case "upload": {
+        const { upload } = await import("./commands/upload.mjs");
+        await upload(args, { json: jsonMode });
+        break;
+      }
       case "pull": {
         const { pull } = await import("./commands/pull.mjs");
         await pull(args);
@@ -119,6 +133,11 @@ export async function run(argv) {
         await clone(args);
         break;
       }
+      case "agents": {
+        const { agents } = await import("./commands/agents.mjs");
+        await agents(args);
+        break;
+      }
       case "list":
       case "ls": {
         const { list } = await import("./commands/list.mjs");

package/src/commands/agents.mjs

@@ -0,0 +1,95 @@
+/**
+ * htmlhost agents [dir] [--print] [--no-claude]
+ *
+ * Write htmlhost's instructions for AI coding agents (hosting rules, CLI, forms)
+ * into the project's AGENTS.md, so tools like Codex, Cursor, Copilot and Claude
+ * Code build features that work on htmlhost. The guide is fetched from
+ * https://htmlhost.co/agents.md so it's always current.
+ *
+ * Only a marked block is managed: anything else in AGENTS.md is left alone,
+ * and running the command again replaces just that block. Claude Code reads
+ * CLAUDE.md rather than AGENTS.md, so an `@AGENTS.md` import is added there too.
+ */
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getApi } from "../config.mjs";
+import { ok, err, dim, cyan } from "../ui.mjs";
+
+const START = "<!-- htmlhost:agents:start — managed by `htmlhost agents`; edits inside this block are replaced -->";
+const END = "<!-- htmlhost:agents:end -->";
+const BLOCK_RE = /<!-- htmlhost:agents:start[^>]*-->[\s\S]*?<!-- htmlhost:agents:end -->/;
+
+/** Fetch the current guide. Throws on network or HTTP failure. */
+export async function fetchAgentGuide(timeoutMs = 10000) {
+  const res = await fetch(`${getApi()}/agents.md`, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return (await res.text()).trim();
+}
+
+/** Whether a project already carries the managed block. */
+export function hasAgentGuide(dir) {
+  const path = join(dir, "AGENTS.md");
+  return existsSync(path) && BLOCK_RE.test(readFileSync(path, "utf8"));
+}
+
+/**
+ * Write (or refresh) the guide in `dir`. Returns what changed, for reporting.
+ * `claude: false` leaves CLAUDE.md untouched.
+ */
+export function writeAgentGuide(dir, guide, { claude = true } = {}) {
+  const changed = [];
+  const block = `${START}\n${guide}\n${END}`;
+
+  const agentsPath = join(dir, "AGENTS.md");
+  const before = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : null;
+  const after = before === null
+    ? `${block}\n`
+    : BLOCK_RE.test(before)
+      ? before.replace(BLOCK_RE, () => block)
+      : `${before.replace(/\s*$/, "")}\n\n${block}\n`;
+  if (after !== before) {
+    writeFileSync(agentsPath, after, "utf8");
+    changed.push(before === null ? "created AGENTS.md" : "updated AGENTS.md");
+  }
+
+  if (claude) {
+    const claudePath = join(dir, "CLAUDE.md");
+    const current = existsSync(claudePath) ? readFileSync(claudePath, "utf8") : null;
+    if (current === null) {
+      writeFileSync(claudePath, "@AGENTS.md\n", "utf8");
+      changed.push("created CLAUDE.md (imports AGENTS.md)");
+    } else if (!/@AGENTS\.md\b/.test(current)) {
+      writeFileSync(claudePath, `${current.replace(/\s*$/, "")}\n\n@AGENTS.md\n`, "utf8");
+      changed.push("added @AGENTS.md to CLAUDE.md");
+    }
+  }
+  return changed;
+}
+
+export async function agents(args) {
+  const positionals = args.filter((a) => !a.startsWith("-"));
+  const dir = resolve(positionals[0] || ".");
+  const print = args.includes("--print");
+
+  let guide;
+  try {
+    guide = await fetchAgentGuide();
+  } catch (e) {
+    err(`Couldn't download the agent guide from ${getApi()}/agents.md (${e.message}).`);
+    process.exit(1);
+  }
+
+  if (print) {
+    console.log(guide);
+    return;
+  }
+
+  const changed = writeAgentGuide(dir, guide, { claude: !args.includes("--no-claude") });
+  if (changed.length === 0) {
+    ok("AI agent instructions are already up to date.");
+  } else {
+    ok(`AI agent instructions ${changed.join(", ")}.`);
+  }
+  console.log(`   ${dim("Your AI coding tool now knows how htmlhost hosting and forms work.")}`);
+  console.log(`   ${dim("Refresh any time with")} ${cyan("htmlhost agents")}${dim(". These files are never deployed.")}`);
+}

package/src/commands/clone.mjs

@@ -9,6 +9,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { get, downloadBuffer } from "../api.mjs";
+import { fetchAgentGuide, writeAgentGuide } from "./agents.mjs";
 import {
   ok,
   err,
@@ -164,6 +165,12 @@ export async function clone(args) {
   const linkPath = join(destDir, LINK_FILE);
   writeFileSync(linkPath, JSON.stringify(linkData, null, 2) + "\n", "utf8");
 
+  // Teach the user's AI coding tool how htmlhost works. Best-effort: a
+  // failed download mustn't fail the clone.
+  const agentsWritten = await fetchAgentGuide(5000)
+    .then((guide) => writeAgentGuide(destDir, guide).length > 0)
+    .catch(() => false);
+
   // --- Done ---
   console.log("");
   console.log(`  ${green("━".repeat(40))}`);
@@ -174,5 +181,6 @@ export async function clone(args) {
   console.log("");
   console.log(`   ${dim("Deploy changes:")}  ${cyan("htmlhost deploy")}`);
   console.log(`   ${dim("Pull updates:")}    ${cyan("htmlhost pull")}`);
+  if (agentsWritten) console.log(`   ${dim("AI agent guide:")}  ${cyan("AGENTS.md")} ${dim("(not deployed)")}`);
   console.log("");
 }

package/src/commands/deploy.mjs

@@ -5,6 +5,7 @@ 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";
 
@@ -68,6 +69,15 @@ const DEFAULT_IGNORE = [
   "package-lock.json",
   "yarn.lock",
   "pnpm-lock.yaml",
+  // Instructions for AI coding tools — private to the project, never published.
+  "AGENTS.md",
+  "CLAUDE.md",
+  "GEMINI.md",
+  ".claude",
+  ".cursor",
+  ".cursorrules",
+  ".windsurfrules",
+  ".github",
 ];
 
 /**
@@ -342,6 +352,10 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
     }
   }
 
+  // Keep an existing AI agent guide current (downloaded alongside the deploy).
+  const hadAgentGuide = hasAgentGuide(dirPath);
+  const agentGuide = hadAgentGuide && !json ? fetchAgentGuide(5000).catch(() => null) : Promise.resolve(null);
+
   // Read existing link data
   const link = readLink(dirPath);
   let existingSlug = explicitSlug || (!forceNew && link?.multipage?.slug) || null;
@@ -557,6 +571,11 @@ async function deployDirectory(dirPath, { ttl, title, slug: explicitSlug, forceN
     }
     console.log("");
     console.log(`   ${dim("Linked → .htmlhost")}`);
+    const guide = await agentGuide;
+    if (guide) writeAgentGuide(dirPath, guide, { claude: false });
+    else if (!hadAgentGuide) {
+      console.log(`   ${dim("Building with AI? Run")} ${cyan("htmlhost agents")} ${dim("so your coding tool knows how htmlhost forms and hosting work.")}`);
+    }
     console.log("");
   } catch (e) {
     err(`Deploy failed: ${e.message}`);

package/src/commands/upload.mjs

@@ -0,0 +1,170 @@
+import { resolve, basename, relative } from "node:path";
+import { statSync, existsSync, readdirSync } from "node:fs";
+import { exec } from "node:child_process";
+import { uploadMediaFile } from "../api.mjs";
+import { ok, err, info, dim, cyan, bold, formatBytes, mimeFromExt } from "../ui.mjs";
+
+/**
+ * Copy text to system clipboard (cross-platform, fail-safe).
+ */
+async function copyToClipboard(text) {
+  try {
+    const { spawn } = await import("node:child_process");
+    let cmd, args;
+    if (process.platform === "darwin") {
+      cmd = "pbcopy";
+      args = [];
+    } else if (process.platform === "win32") {
+      cmd = "clip";
+      args = [];
+    } else if (process.env.WAYLAND_DISPLAY) {
+      cmd = "wl-copy";
+      args = [];
+    } else {
+      cmd = "xclip";
+      args = ["-selection", "clipboard"];
+    }
+
+    return await new Promise((res) => {
+      const proc = spawn(cmd, args, { stdio: ["pipe", "ignore", "ignore"] });
+      proc.on("error", () => res(false));
+      proc.on("close", (code) => res(code === 0));
+      proc.stdin.write(text);
+      proc.stdin.end();
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Recursively collect all files in a directory, ignoring hidden files/folders.
+ */
+function collectFiles(dir) {
+  const files = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    const full = resolve(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectFiles(full));
+    } else if (entry.isFile()) {
+      files.push(full);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * htmlhost upload <file|dir...> — upload media files and get hosted URLs.
+ */
+export async function upload(args, { json = false } = {}) {
+  const flags = new Set(args.filter((a) => a.startsWith("--")));
+  const rawPaths = args.filter((a) => !a.startsWith("--"));
+
+  const noCopy = flags.has("--no-copy");
+  const openInBrowser = flags.has("--open");
+
+  if (rawPaths.length === 0) {
+    err("Usage: htmlhost upload <file|dir...> [options]");
+    console.log(`\n  ${bold("Options:")}`);
+    console.log(`    --open       Open the uploaded media URL in your browser`);
+    console.log(`    --no-copy    Do not copy the URL to clipboard`);
+    console.log(`    --json       Output response as JSON\n`);
+    console.log(`  ${bold("Examples:")}`);
+    console.log(`    ${dim("$")} htmlhost upload assets/og-image-ambient.jpg`);
+    console.log(`    ${dim("$")} htmlhost upload photo.jpg logo.svg`);
+    console.log(`    ${dim("$")} htmlhost upload assets/`);
+    process.exit(1);
+  }
+
+  // Resolve all target files
+  const filePaths = [];
+  for (const raw of rawPaths) {
+    const absPath = resolve(process.cwd(), raw);
+    if (!existsSync(absPath)) {
+      err(`File or directory not found: ${raw}`);
+      process.exit(1);
+    }
+
+    const stat = statSync(absPath);
+    if (stat.isDirectory()) {
+      const inside = collectFiles(absPath);
+      if (inside.length === 0) {
+        if (!json) err(`No files found in directory: ${raw}`);
+        process.exit(1);
+      }
+      filePaths.push(...inside);
+    } else if (stat.isFile()) {
+      filePaths.push(absPath);
+    }
+  }
+
+  if (filePaths.length === 0) {
+    err("No files to upload.");
+    process.exit(1);
+  }
+
+  const results = [];
+
+  if (!json && filePaths.length > 1) {
+    console.log("");
+    info(`Uploading ${bold(String(filePaths.length))} files…`);
+  }
+
+  for (const filePath of filePaths) {
+    const fileName = basename(filePath);
+    const relPath = relative(process.cwd(), filePath) || fileName;
+    const stat = statSync(filePath);
+    const mime = mimeFromExt(fileName);
+
+    if (!json && filePaths.length === 1) {
+      info(`Uploading ${cyan(relPath)} ${dim(`(${formatBytes(stat.size)})`)}…`);
+    }
+
+    const uploaded = await uploadMediaFile(filePath, fileName, mime);
+    results.push({
+      ...uploaded,
+      localPath: relPath,
+    });
+
+    if (!json && filePaths.length > 1) {
+      console.log(`  ${cyan(relPath)} ${dim(`(${formatBytes(stat.size)})`)} → ${uploaded.fullUrl}`);
+    }
+  }
+
+  // JSON output
+  if (json) {
+    console.log(JSON.stringify(results.length === 1 ? results[0] : results, null, 2));
+    return;
+  }
+
+  // Single file completion UX
+  if (results.length === 1) {
+    const item = results[0];
+    let copied = false;
+    if (!noCopy) {
+      copied = await copyToClipboard(item.fullUrl);
+    }
+
+    ok(`Uploaded ${cyan(item.localPath)} ${dim(`(${formatBytes(item.size)})`)}`);
+    console.log(`  ${bold(item.fullUrl)}${copied ? dim("  (copied to clipboard)") : ""}`);
+  } else {
+    console.log("");
+    ok(`All ${bold(String(results.length))} files uploaded successfully`);
+  }
+
+  // Open in browser if requested
+  if (openInBrowser) {
+    const cmd =
+      process.platform === "darwin" ? "open" :
+      process.platform === "win32" ? "start" :
+      "xdg-open";
+
+    for (const r of results) {
+      exec(`${cmd} ${r.fullUrl}`);
+    }
+  }
+}

package/src/update.mjs

@@ -29,7 +29,7 @@ export function startUpdateCheck(currentVersion) {
   if (Date.now() - lastCheck < CHECK_INTERVAL_MS) {
     // Still within throttle window — but if we know a newer version
     // from the last check, surface it without re-fetching
-    if (config.latestVersion && config.latestVersion !== currentVersion) {
+    if (config.latestVersion && isNewer(config.latestVersion, currentVersion)) {
       return Promise.resolve({
         latest: config.latestVersion,
         current: currentVersion,