htmlhost-cli 2.13.0 → 2.15.0

package/README.md

@@ -173,8 +173,39 @@ htmlhost agents --no-claude  # don't touch CLAUDE.md
 
 The same guide is at https://htmlhost.co/agents.md.
 
+### `htmlhost keys [slug] [--json]`
+List what the site's owner set up for building with services and data:
+
+- **Keys** (the site's **Keys** tab): every key's name and kind, and the value of public keys. A secret key's value is never downloaded.
+- **Secure calls**: how a page uses a secret key, by name: `POST /__hh/call/<name>` with the fields listed.
+- **Collections** (the **Data** tab): the site's own data, with each collection's address, fields and read/add rules. Records aren't listed.
+
+```bash
+htmlhost keys            # in a linked project folder
+htmlhost keys my-shop    # any site you can edit
+htmlhost keys --json     # { slug, keys, calls, collections }
+```
+
+`pull` and `clone` also write the list into the project's `AGENTS.md` (its own block, separate from `htmlhost agents`), so your AI coding tool can build with them by name.
+
+### `htmlhost keys set NAME [VALUE] [options]`
+Save a key to the linked site (or `--slug SLUG`): adds it, or replaces the value of a key with that name.
+
+```bash
+htmlhost keys set STRIPE_SECRET_KEY                  # asks for the value without showing it
+echo "$KEY" | htmlhost keys set STRIPE_SECRET_KEY     # or from stdin
+htmlhost keys set GA_MEASUREMENT_ID G-ABC123 --public --note "Analytics"
+```
+
+Without `--public` or `--secret`, htmlhost works the kind out from the value (`sk_…` secret, `pk_…` public, and similar) or the name; when it can't, the CLI asks (or, without a terminal, tells your AI tool to ask you). Saving a secret-looking value as public needs `--confirm-public`. The site's owner or an Admin only, on Pro. Nothing printed contains a secret's value.
+
+### `htmlhost keys remove NAME`
+Remove a key from the linked site (or `--slug SLUG`). Refused while a secure call uses it.
+
+Secure calls and collections are set up in the dashboard. Guides: [payments](https://htmlhost.co/guides/accept-payments-on-your-website), [API keys](https://htmlhost.co/guides/use-api-keys-safely-on-your-website), [collections](https://htmlhost.co/guides/add-a-database-to-your-website).
+
 ### `htmlhost list`
-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.
+List all your sites with titles, sizes, TTL, and expiry. Multi-page sites are marked with 📄. Sites shared with you follow under **Shared with you**, with their owner and your role. Admins and Editors can `clone`, `deploy` and roll them back with their own sign-in; Contributors can `clone` and `deploy --draft`, then ask someone who can publish; Viewers only look. Only the owner can delete a site.
 
 ### `htmlhost open <slug>`
 Open a deployed site in the default browser.
@@ -227,7 +258,7 @@ Free publishing is limited. Subscribe to Pro to continue creating unlimited site
 
 ## 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.
+Unpublished websites remain private until publishing is explicitly confirmed. Admins and Editors on a shared site can publish with confirmation and unpublish; Contributors save drafts only. 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`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "htmlhost-cli",
-  "version": "2.13.0",
-  "description": "Deploy HTML files from the terminal \u2014 htmlhost.co CLI",
+  "version": "2.15.0",
+  "description": "Deploy HTML files from the terminal — htmlhost.co CLI",
   "type": "module",
   "bin": {
     "htmlhost": "bin/htmlhost.mjs"

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.13.0";
+const VERSION = "2.15.0";
 
 const HELP = `
   ${bold("htmlhost")} ${dim(`v${VERSION}`)} — deploy HTML from the terminal
@@ -17,10 +17,13 @@ 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 (owner)
+    ${cyan("htmlhost recipients")} [slug] [cmd]  Manage form notification recipients (owner, Admin)
+    ${cyan("htmlhost keys")} [slug]             List a site's keys, secure calls and collections
+    ${cyan("htmlhost keys set")} NAME [value]     Save a key (kind worked out, or --public/--secret)
+    ${cyan("htmlhost keys remove")} NAME          Remove a key
     ${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 unpublish")} [slug]       Take a site offline (owner, Admin, Editor)
     ${cyan("htmlhost rollback")} [slug] [ver]    Make an earlier version live again (Pro)
     ${cyan("htmlhost delete")} <slug>            Delete a site (owner)
     ${cyan("htmlhost login")}                    Sign in (approve in your browser)
@@ -142,6 +145,11 @@ export async function run(argv) {
         await whoami();
         break;
       }
+      case "keys": {
+        const { keys } = await import("./commands/keys.mjs");
+        await keys(args, { json: jsonMode });
+        break;
+      }
       case "unpublish": {
         const { unpublish } = await import("./commands/unpublish.mjs");
         await unpublish(args, { json: jsonMode });

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 { writeKeysGuide } from "../keys-guide.mjs";
 import { writeLink, directorySite } from "../link.mjs";
 import {
   ok,
@@ -166,6 +167,9 @@ export async function clone(args) {
     .then((guide) => writeAgentGuide(destDir, guide).length > 0)
     .catch(() => false);
 
+  // The site's keys (names, and public values) for the same tools.
+  const keysWritten = !!data.keysGuide && writeKeysGuide(destDir, data.keysGuide);
+
   // --- Done ---
   console.log("");
   console.log(`  ${green("━".repeat(40))}`);
@@ -177,5 +181,6 @@ export async function clone(args) {
   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)")}`);
+  if (keysWritten) console.log(`   ${dim("Site keys:")}       ${cyan("AGENTS.md")} ${dim(`(${data.keys.length} listed; secret values are never downloaded)`)}`);
   console.log("");
 }

package/src/commands/keys.mjs

@@ -0,0 +1,145 @@
+/**
+ * htmlhost keys [slug] [--json]
+ * htmlhost keys set NAME [VALUE] [--public|--secret] [--note TEXT] [--slug SLUG] [--confirm-public]
+ * htmlhost keys remove NAME [--slug SLUG]
+ *
+ * List a site's keys (the dashboard's Keys tab): every key's name and kind,
+ * the value of public keys only, its secure calls and collections. `set` adds
+ * or replaces a key; without --public/--secret htmlhost works the kind out
+ * from the value, and when it can't, asks (in a terminal) or says to ask the
+ * user (for an agent). A value left out is read from stdin, or typed hidden,
+ * so it stays out of shell history. Answers never print a secret's value.
+ */
+import { resolve } from "node:path";
+import { get, post, del } from "../api.mjs";
+import { readLink } from "../link.mjs";
+import { writeKeysGuide } from "../keys-guide.mjs";
+import { bold, cyan, dim, info, ok, prompt, confirm } from "../ui.mjs";
+
+const flag = (args, name) => {
+  const i = args.indexOf(name);
+  return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+};
+/** Positional arguments, leaving out flags and the values of flags that take one. */
+function positionals(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    if (["--note", "--slug"].includes(args[i])) { i++; continue; }
+    if (!args[i].startsWith("-")) out.push(args[i]);
+  }
+  return out;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+
+/** htmlhost keys set NAME [VALUE] … */
+async function setKey(args, slug, { json }) {
+  const [, name, given] = positionals(args);
+  if (!name) throw new Error("Usage: htmlhost keys set NAME [VALUE] [--public|--secret] [--note TEXT]");
+  const interactive = process.stdin.isTTY && !json;
+  let value = given;
+  if (!value) value = interactive ? await prompt(`  Value for ${name}: `, { hidden: true }) : await readStdin();
+  if (!value) throw new Error(`No value given for ${name}.`);
+  let kind = args.includes("--secret") ? "secret" : args.includes("--public") ? "public" : undefined;
+  let confirmPublic = args.includes("--confirm-public");
+  const note = flag(args, "--note");
+  const send = () => post(`/api/sites/${encodeURIComponent(slug)}/keys`, { name, value, kind, note, confirmPublic });
+
+  let data;
+  for (;;) {
+    try {
+      data = await send();
+      break;
+    } catch (e) {
+      if (e.code === "KEY_KIND_UNKNOWN" && interactive && !kind) {
+        const answer = (await prompt(`  Is ${name} public (safe to show in pages) or secret? [public/secret]: `)).trim().toLowerCase();
+        if (!["public", "secret"].includes(answer)) throw new Error("Nothing saved. Run it again with --public or --secret.");
+        kind = answer;
+        continue;
+      }
+      if (e.code === "KEY_LOOKS_SECRET" && interactive && !confirmPublic) {
+        if (!(await confirm(`  ${name} looks like a secret key. Save it as public anyway, readable by every visitor?`))) {
+          kind = "secret";
+        } else confirmPublic = true;
+        continue;
+      }
+      if (e.code === "KEY_KIND_UNKNOWN") throw new Error(`${e.message} Then run: htmlhost keys set ${name} --public or --secret`);
+      if (e.code === "KEY_LOOKS_SECRET") throw new Error(`${e.message} (CLI: add --secret, or --confirm-public once the user confirms.)`);
+      throw e;
+    }
+  }
+  if (json) return console.log(JSON.stringify({ slug, ...data.key, created: data.created }));
+  ok(`${data.created ? "Added" : "Updated"} ${bold(data.key.name)} on ${cyan(slug)} as ${data.key.kind === "secret" ? "a secret key" : "a public key"}.`);
+  console.log(`   ${dim(data.key.kind === "secret" ? "Its value is never shown again. Pages use it through a secure call." : "Pages may use its value as given.")}`);
+}
+
+/** htmlhost keys remove NAME */
+async function removeKey(args, slug, { json }) {
+  const [, name] = positionals(args);
+  if (!name) throw new Error("Usage: htmlhost keys remove NAME");
+  const data = await del(`/api/sites/${encodeURIComponent(slug)}/keys?name=${encodeURIComponent(name)}`);
+  if (json) return console.log(JSON.stringify({ slug, name, removed: data.removed }));
+  if (data.removed) ok(`Removed ${bold(name)} from ${cyan(slug)}.`);
+  else info(`${cyan(slug)} has no key named ${name}.`);
+}
+
+export async function keys(args, { json = false } = {}) {
+  const dir = resolve(".");
+  const link = readLink(dir);
+  const sub = args[0];
+  if (sub === "set" || sub === "remove") {
+    const target = (flag(args, "--slug") || link?.site?.slug)?.replace(/\.htmlhost\.co$/, "");
+    if (!target) throw new Error(`Run it in a linked project folder, or add --slug SLUG.`);
+    return sub === "set" ? setKey(args, target, { json }) : removeKey(args, target, { json });
+  }
+  const slug = (args.find((a) => !a.startsWith("-")) || link?.site?.slug)?.replace(/\.htmlhost\.co$/, "");
+  if (!slug) throw new Error("Usage: htmlhost keys <slug>");
+
+  const data = await get(`/api/sites/pull?slug=${encodeURIComponent(slug)}&meta=true`);
+  const list = data.keys || [];
+  const calls = data.calls || [];
+  const collections = data.collections || [];
+  // In the site's own folder, keep AGENTS.md's list current too.
+  if (link?.site?.slug === slug) writeKeysGuide(dir, data.keysGuide || "");
+
+  if (json) {
+    console.log(JSON.stringify({ slug, keys: list, calls, collections }));
+    return;
+  }
+  console.log("");
+  if (collections.length) {
+    console.log(`   ${bold("Collections")} ${dim("(the site's own data; records aren't listed)")}`);
+    for (const c of collections) {
+      const fields = c.fields.map((f) => `${f.name}${f.required ? "" : "?"}`).join(", ");
+      console.log(`   ${bold(c.name)}  ${c.path}  ${dim("read:")} ${c.read === "public" ? "anyone" : "site only"}  ${dim("add:")} ${c.add === "public" ? "anyone" : "site only"}  ${dim(fields)}`);
+    }
+    console.log("");
+  }
+  if (!list.length) {
+    info(`${cyan(slug)} has no keys yet.`);
+    console.log(`   ${dim("Add them in the dashboard:")} ${cyan(`https://htmlhost.co/dashboard/sites/${slug}/keys`)}`);
+    console.log("");
+    return;
+  }
+  const width = Math.max(...list.map((k) => k.name.length));
+  for (const k of list) {
+    const value = k.kind === "public" ? k.value : dim("(secret, not shown)");
+    console.log(`   ${bold(k.name.padEnd(width))}  ${dim(k.kind.padEnd(6))}  ${value}${k.note ? `  ${dim(k.note)}` : ""}`);
+  }
+  if (calls.length) {
+    console.log("");
+    console.log(`   ${bold("Secure calls")} ${dim("(how pages use a secret key)")}`);
+    for (const c of calls) {
+      const fields = c.fields.map((f) => `${f.name}${f.required ? "" : "?"}`).join(", ");
+      console.log(`   ${bold(c.name)}${c.enabled ? "" : dim(" (off)")}  ${dim("POST")} ${c.path}${fields ? `  ${dim("send")} ${fields}` : ""}`);
+    }
+  }
+  console.log("");
+  console.log(`   ${dim("A public key's value can be written into pages. A secret key's never can: pages use it through a secure call.")}`);
+  console.log(`   ${dim("Add one:")} ${cyan("htmlhost keys set NAME")} ${dim("· or in the dashboard:")} ${cyan(`https://htmlhost.co/dashboard/sites/${slug}/keys`)}`);
+  console.log("");
+}

package/src/commands/list.mjs

@@ -2,8 +2,8 @@ import { get } from "../api.mjs";
 import { dim, cyan, bold, formatBytes, yellow } from "../ui.mjs";
 
 /**
- * htmlhost list — show all sites: your own, then the ones shared with you
- * (you can clone, deploy and restore those, not delete them).
+ * htmlhost list — show all sites: your own, then the ones shared with you,
+ * with your role on each (what you can do follows it; only owners delete).
  */
 export async function list({ json = false } = {}) {
   const data = await get("/api/sites");
@@ -54,11 +54,14 @@ export async function list({ json = false } = {}) {
   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")}`);
+    console.log(`  ${bold("Shared with you")} ${dim("(what you can do follows your role; only the owner can delete)")}`);
+    console.log(`  ${dim(pad("SLUG", sharedSlugW) + pad("TITLE", 30) + pad("STATUS", 12) + pad("ROLE", 13) + "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(`  ${pad(cyan(s.slug), sharedSlugW)}${pad(dim(title), 30)}${pad(s.isPublished === false ? "Draft" : "Published", 12)}${pad(roleLabel(s.role), 13)}${dim(s.owner || "")}`);
+    }
+    if (shared.some((s) => s.canPublish === false && s.canEdit !== false)) {
+      console.log(`  ${dim("Contributors save drafts (htmlhost deploy --draft) and ask an Owner, Admin or Editor to publish.")}`);
     }
   }
 
@@ -91,3 +94,8 @@ function relTime(iso) {
   if (days === 1) return "tomorrow";
   return `${days}d`;
 }
+
+/** The server's role name, as people read it ("contributor" → "Contributor"). Older servers send "editor". */
+function roleLabel(role) {
+  return typeof role === "string" && role ? role[0].toUpperCase() + role.slice(1) : "Editor";
+}

package/src/commands/pull.mjs

@@ -9,6 +9,7 @@ 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 { writeKeysGuide } from "../keys-guide.mjs";
 import {
   ok,
   err,
@@ -201,6 +202,12 @@ export async function pull(args) {
     }
   }
 
+  // --- The site's keys, for AI tools working in this folder (AGENTS.md) ---
+  // Only in a project that's already set up for them or has keys to list.
+  if (!dryRun && typeof data.keysGuide === "string" && writeKeysGuide(projectDir, data.keysGuide)) {
+    info(`${cyan("AGENTS.md")} ${dim(data.keysGuide ? `now lists this site's ${data.keys?.length ?? ""} key${data.keys?.length === 1 ? "" : "s"}` : "no longer lists keys (the site has none)")}`);
+  }
+
   // --- Show results ---
   if (changes.length === 0) {
     ok("Already up to date — no changes to pull.");

package/src/keys-guide.mjs

@@ -0,0 +1,35 @@
+/**
+ * The site's keys in AGENTS.md, so an AI coding tool working in the folder
+ * knows which keys the site has: every key's name, and the values of public
+ * keys only (the server never sends a secret's value).
+ *
+ * A marked block of its own, separate from the `htmlhost agents` guide block,
+ * so refreshing either leaves the other alone. `pull` and `clone` write it
+ * from the server's `keysGuide`; a site without keys has no block.
+ */
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const START = "<!-- htmlhost:keys:start — this site's keys, written by `htmlhost pull`; edits inside this block are replaced -->";
+const END = "<!-- htmlhost:keys:end -->";
+const BLOCK_RE = /\n*<!-- htmlhost:keys:start[^>]*-->[\s\S]*?<!-- htmlhost:keys:end -->\n?/;
+
+/** AGENTS.md's text with the keys block set to `guide` (removed when empty). Pure. */
+export function withKeysBlock(before, guide) {
+  const text = (guide || "").trim();
+  const current = before ?? "";
+  if (!text) return BLOCK_RE.test(current) ? current.replace(BLOCK_RE, () => "\n") : current;
+  const block = `${START}\n${text}\n${END}`;
+  if (BLOCK_RE.test(current)) return current.replace(BLOCK_RE, () => `${current.search(BLOCK_RE) === 0 ? "" : "\n\n"}${block}\n`);
+  return current.trim() ? `${current.replace(/\s*$/, "")}\n\n${block}\n` : `${block}\n`;
+}
+
+/** Write (or remove) the block in `dir`'s AGENTS.md. Returns whether the file changed. */
+export function writeKeysGuide(dir, guide) {
+  const path = join(dir, "AGENTS.md");
+  const before = existsSync(path) ? readFileSync(path, "utf8") : null;
+  const after = withKeysBlock(before, guide);
+  if (after === (before ?? "")) return false;
+  writeFileSync(path, after, "utf8");
+  return true;
+}