toolaby 1.4.4 → 1.5.0

package/README.md

@@ -24,6 +24,8 @@ If the extension is built with WXT, CRXJS or Plasmo, the command puts the same f
 
 **`toolaby create <tool-id>`** makes a new, minimal extension in a folder named after the tool, ready for *Load unpacked*.
 
+**`toolaby pack [folder]`** makes the zip for the Chrome Web Store from your built extension: the manifest's `key` left out (the store refuses one it did not issue), and refused if the build carries a Test key or points at `localhost`. Nothing is sent anywhere.
+
 **`toolaby tools`** lists your tools and their ids. **`toolaby whoami`** says who you are signed in as. **`toolaby logout`** signs the command out and revokes its session on the server.
 
 ## Where things live

package/bin.mjs

@@ -5,6 +5,7 @@
 //   toolaby wire <tool-id>            wire the extension in this folder to your tool — plain, WXT, CRXJS or Plasmo
 //   toolaby create <tool-id>          make a new, minimal extension for your tool in <tool-id>/
 //   toolaby tools                     your tools, with the ids the commands want
+//   toolaby pack [folder]             the zip for the Chrome Web Store: the built extension, its manifest's key left out
 //   toolaby webhooks events           the six events, with an example of each
 //   toolaby webhooks trigger <event>  send an example delivery: to your registered endpoints, or with --to straight to a local server
 //   toolaby webhooks endpoints        the workspace's endpoints
@@ -27,14 +28,15 @@
 // platform's own (wall/src/packages/wiring), carried here transpiled in lib/,
 // so this and the dashboard's Wire button never disagree.
 import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, statSync, chmodSync, unlinkSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, relative, basename } from 'node:path';
+import { deflateRawSync } from 'node:zlib';
 import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
 import { createHmac, randomBytes } from 'node:crypto';
 import { wireManifest, WORKER_LINES } from './lib/manifest.js';
-import { detectProject, CODE_FILES, filesToWrite, fillPages, scaffoldManifest, STALE_FILES, BUILD_COPY_NOTE } from './lib/project.js';
+import { detectProject, CODE_FILES, filesToWrite, fillPages, scaffoldManifest, scaffoldFilesFor, surfacesOf, hasPopup, hasSidePanel, SURFACES, STALE_FILES, BUILD_COPY_NOTE } from './lib/project.js';
 
-const VERSION = '1.4.4';
+const VERSION = '1.5.0';
 const CLIENT_ID = 'toolaby-cli';
 const argv = process.argv.slice(2);
 // `--version` and `--help` are commands of their own; every other command is the first bare word.
@@ -259,20 +261,25 @@ async function create() {
   // The scaffold's own files as the Wall names them (older Walls did not, hence the list): a Wall that adds one to the
   // minimal extension is written by this command too, instead of a manifest naming a file that never arrived.
   const scaffold = Array.isArray(plan.scaffold) && plan.scaffold.length ? plan.scaffold : ['manifest.json', 'background.js', 'popup.html', 'sidepanel.html', 'popup.css', 'popup.js', 'README.md'];
-  const wanted = [...CODE_FILES, ...scaffold];
+  // Which surfaces this extension is made with: both (the default), one of them, or none at all for a tool that works
+  // from the background. Asked for once here, rather than written and then deleted by hand.
+  const asked = opt('--surfaces');
+  if (asked && !SURFACES.includes(asked)) fail(`--surfaces takes ${SURFACES.join(', ')} — not "${asked}".`);
+  const surfaces = surfacesOf(asked);
+  const wanted = [...CODE_FILES, ...scaffoldFilesFor(surfaces, scaffold)];
   const absent = wanted.filter((f) => typeof plan.files[f] !== 'string');
   if (absent.length) fail(`The Wall at ${wall} named ${absent.join(', ')} for a new extension but did not hand ${absent.length > 1 ? 'them' : 'it'} over.\n  Nothing was written. Update this command: npm install -g toolaby@latest — or run the Wall's own copy: npx --yes ${wall}/toolaby.tgz create ${slug}`);
   // Both surfaces, and the panel drawn inside them: no page of the Wall's stands in front, so both names stay empty.
   for (const f of wanted) write(f, fillPages(plan.files[f]));
   // The manifest names the side panel only now that the page is beside it — an extension whose side_panel points at a
   // missing file does not load at all, so a Wall that stops serving the page must not leave the key behind either.
-  const wroteSidePanel = wanted.includes('sidepanel.html');
-  write('manifest.json', JSON.stringify(scaffoldManifest(JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8')), { sidePanel: wroteSidePanel }), null, 2) + '\n');
+  write('manifest.json', JSON.stringify(scaffoldManifest(JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8')), { sidePanel: hasSidePanel(surfaces), popup: hasPopup(surfaces) }), null, 2) + '\n');
   for (const s of [16, 48, 128]) {
     const res = await fetch(`${wall}/boilerplate/icons/icon${s}.png`);
     write(join('icons', `icon${s}.png`), Buffer.from(await res.arrayBuffer()));
   }
-  out(`\n  ${plan.name} → ${dir}\n\n    1. chrome://extensions → Developer mode → Load unpacked → ${dir}\n    2. Click the icon: the popup shows what the Free plan holds; Buy opens ${plan.site}/tools/${slug}\n${wroteSidePanel ? "    3. Open side panel, in that popup: the same page at the panel's width (README.md says how to keep only one)\n" : ''}\n  Edit background.js: your work goes behind toolaby.gate().\n`);
+  const clicking = { both: 'Click the icon: the popup shows what the Free plan holds. Open side panel, in it, is the same page at the panel\'s width', popup: 'Click the icon: the popup shows what the Free plan holds', 'side-panel': 'Click the icon: the side panel opens — it has no popup, so the click is the panel\'s', none: 'No popup and no side panel: nothing opens on a click. Your code says when to sell — toolaby.openPaymentPage()' }[surfaces];
+  out(`\n  ${plan.name} → ${dir}${surfaces === 'both' ? '' : `  (--surfaces ${surfaces})`}\n\n    1. chrome://extensions → Developer mode → Load unpacked → ${dir}\n    2. ${clicking}; Buy opens ${plan.site}/tools/${slug}\n\n  Edit background.js: your work goes behind toolaby.gate().\n  Surfaces, and how to add or drop one later: ${plan.site}/docs/surfaces\n`);
 }
 
 // ── webhooks: the catalogue, and a delivery on demand ───────────────────────────────────────────────────────────────
@@ -359,6 +366,110 @@ async function webhooks() {
   fail('usage: toolaby webhooks events | trigger <event> [--to <url>] | endpoints | add <url> | remove <id>');
 }
 
+// ── pack: the zip the Chrome Web Store takes ──────────────────────────────────────────────────────────────────────────
+// The built extension, zipped, with the manifest's `key` left out: the store refuses a key in a new item's first
+// package and any key but the item's own in an update, and it keeps the id it gave the item either way — the Wall
+// admits that id once the listing's address is on the tool. It refuses a build that would sell on Test (a tk_test_
+// or tk_dev_ key inside) or that points at this machine (localhost in the manifest), the two mistakes a store build
+// can ship with. Nothing is sent anywhere: it reads the folder and writes one file.
+const BUILD_DIRS = ['.', '.output/chrome-mv3', 'dist', 'build/chrome-mv3-prod', 'build'];
+const TOOL_KEY = /tk_(test|live|dev)_[A-Za-z0-9_-]{20,}/g;
+const LOCAL = /^(https?|wss?):\/\/(localhost|127\.0\.0\.1|\[::1\]|[^/]*\.localhost)(:\d+)?\//i;
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; return c >>> 0; });
+const crc32 = (buf) => { let c = 0xffffffff; for (const b of buf) c = CRC_TABLE[(c ^ b) & 0xff] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };
+
+/** A zip of [name, bytes] pairs: deflated where that is smaller, stored otherwise, every entry dated 1 Jan 1980 so the same build packs to the same bytes. */
+function zipOf(entries) {
+  const locals = []; const centrals = []; let offset = 0;
+  for (const [name, data] of entries) {
+    const nameBuf = Buffer.from(name, 'utf8');
+    const deflated = deflateRawSync(data, { level: 9 });
+    const method = deflated.length < data.length ? 8 : 0;
+    const body = method === 8 ? deflated : data;
+    const crc = crc32(data);
+    const head = Buffer.alloc(30);
+    head.writeUInt32LE(0x04034b50, 0); head.writeUInt16LE(20, 4); head.writeUInt16LE(0x0800, 6); head.writeUInt16LE(method, 8);
+    head.writeUInt16LE(0, 10); head.writeUInt16LE(0x21, 12); head.writeUInt32LE(crc, 14); head.writeUInt32LE(body.length, 18);
+    head.writeUInt32LE(data.length, 22); head.writeUInt16LE(nameBuf.length, 26); head.writeUInt16LE(0, 28);
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0); central.writeUInt16LE(20, 4); central.writeUInt16LE(20, 6); central.writeUInt16LE(0x0800, 8);
+    central.writeUInt16LE(method, 10); central.writeUInt16LE(0, 12); central.writeUInt16LE(0x21, 14); central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(body.length, 20); central.writeUInt32LE(data.length, 24); central.writeUInt16LE(nameBuf.length, 28);
+    central.writeUInt32LE(offset, 42);
+    locals.push(head, nameBuf, body); centrals.push(central, nameBuf);
+    offset += head.length + nameBuf.length + body.length;
+  }
+  const cd = Buffer.concat(centrals);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0); end.writeUInt16LE(entries.length, 8); end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(cd.length, 12); end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, cd, end]);
+}
+
+function filesIn(root) {
+  const found = [];
+  const walk = (dir) => {
+    for (const name of readdirSync(dir).sort()) {
+      if (name.startsWith('.') || name === 'node_modules' || name.endsWith('.zip')) continue;
+      const p = join(dir, name);
+      if (statSync(p).isDirectory()) walk(p); else found.push(p);
+    }
+  };
+  walk(root);
+  return found;
+}
+
+function pack() {
+  const given = positional[0];
+  const folder = given ? resolve(given) : BUILD_DIRS.map((d) => resolve(d)).find((d) => existsSync(join(d, 'manifest.json')));
+  if (!folder || !existsSync(join(folder, 'manifest.json'))) fail(given ? `No manifest.json in ${given}.` : `No manifest.json here or in ${BUILD_DIRS.slice(1).join(', ')}. Build first, or name the folder: toolaby pack <folder>.`);
+  let manifest;
+  try { manifest = JSON.parse(readFileSync(join(folder, 'manifest.json'), 'utf8')); } catch (e) { fail(`manifest.json does not parse: ${e.message}`); }
+  if (!manifest.version) fail('manifest.json has no "version".');
+  const files = filesIn(folder);
+  const problems = [];
+
+  // Which side the build sells on: the tool keys inside it, wherever the bundler put them.
+  const modes = new Set(); const sites = new Set();
+  for (const f of files) {
+    if (!/\.(m?js|html|json)$/.test(f)) continue;
+    for (const [k, mode] of readFileSync(f, 'utf8').matchAll(TOOL_KEY)) {
+      modes.add(mode);
+      try { const facts = JSON.parse(Buffer.from(k.split('_')[2], 'base64url').toString('utf8')); if (typeof facts.s === 'string') sites.add(facts.s.replace(/\/$/, '')); } catch { /* not a key after all */ }
+    }
+  }
+  if ((modes.has('test') || modes.has('dev')) && !flag('--allow-test')) problems.push(`It carries a ${[...modes].filter((m) => m !== 'live').map((m) => `tk_${m}_`).join(' and ')} key: it would sell on ${modes.has('test') ? 'Test, with test cards' : 'a development Wall'}. Run \`npx toolaby wire <tool-id> --live --force\`, build again, then pack. (--allow-test packs it anyway, for a build you will not publish.)`);
+  if (modes.size === 0) out('\n  No tool key found in the build: it is not wired to the Wall, or the key is somewhere this cannot read. Packing anyway.');
+
+  // Addresses of this machine have no place in a store build.
+  const local = [...(manifest.host_permissions ?? []), ...(manifest.externally_connectable?.matches ?? [])].filter((m) => typeof m === 'string' && LOCAL.test(m));
+  if (local.length && !flag('--allow-local')) problems.push(`The manifest points at this machine: ${local.join(', ')}. A store build has no localhost in host_permissions or externally_connectable. (--allow-local packs it anyway.)`);
+
+  // The Wall the key names must be reachable from the extension, or sign-in and the purchase handoff fail.
+  for (const site of sites) {
+    const hosts = manifest.host_permissions ?? []; const ec = manifest.externally_connectable?.matches ?? [];
+    if (!hosts.includes(`${site}/*`) || !ec.includes(`${site}/*`)) problems.push(`The manifest does not name ${site}/* in both host_permissions and externally_connectable: sign-in and the purchase would not reach the extension. \`npx toolaby wire <tool-id> --live --force\` adds them.`);
+  }
+  if (problems.length) fail(`Not packed:\n\n${problems.map((p) => `  · ${p}`).join('\n\n')}`);
+
+  const hadKey = typeof manifest.key === 'string';
+  const { key: _key, ...forStore } = manifest;
+  const entries = files.map((f) => {
+    const name = relative(folder, f).split('\\').join('/');
+    return [name, name === 'manifest.json' ? Buffer.from(JSON.stringify(forStore, null, 2) + '\n') : readFileSync(f)];
+  });
+  // Named after the extension, or after its folder when the name is a __MSG_…__ placeholder.
+  const named = typeof manifest.name === 'string' && !manifest.name.startsWith('__MSG_') ? manifest.name : basename(folder);
+  const safe = named.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'extension';
+  const target = resolve(opt('--out') ?? `${safe}-${manifest.version}.zip`);
+  writeFileSync(target, zipOf(entries));
+  const kb = (statSync(target).size / 1024).toFixed(0);
+  out(`\n  ${relative(process.cwd(), target) || target}  ·  ${entries.length} files, ${kb} KB  ·  version ${manifest.version}${modes.has('live') ? '  ·  Live key' : ''}`);
+  if (hadKey) out('  The manifest\'s "key" is left out: the store keeps the id it gives the item. Your unpacked copy keeps the key and its own id; the Wall admits both once the listing\'s address is on the tool.');
+  out('  Upload it at https://chrome.google.com/webstore/devconsole — a new item, or Package → Upload new package.\n');
+}
+
 function help() {
   out(`
   toolaby — the Toolaby command line (${VERSION})
@@ -368,7 +479,10 @@ function help() {
                                        --into <folder>   another folder     --force   replace the platform's files
     toolaby upgrade <tool-id>          the platform's files replaced with the current ones — the popup, the client — yours untouched
     toolaby create <tool-id>           a new, minimal extension for your tool, in <tool-id>/   --dir <folder>
+                                       --surfaces both|popup|side-panel|none   what it opens (default: both)
     toolaby tools                      your tools, with their ids
+    toolaby pack [folder]              the zip for the Chrome Web Store: the built extension, its manifest's "key" left out;
+                                       refuses a Test key or localhost inside   --out <file.zip>
     toolaby webhooks events            the six events, with an example of each
     toolaby webhooks trigger <event>   an example delivery to your endpoints; --to <url> sends it to a local server instead
     toolaby webhooks endpoints         your endpoints; add <url> registers one (secret shown once), remove <id> removes one
@@ -379,7 +493,7 @@ function help() {
 `);
 }
 
-const commands = { login: async () => { await login(); }, logout, whoami, tools, wire, upgrade: wire, create, webhooks, help, '--help': help, '-h': help, '--version': () => out(VERSION), '-v': () => out(VERSION) };
+const commands = { login: async () => { await login(); }, logout, whoami, tools, wire, upgrade: wire, create, webhooks, pack, help, '--help': help, '-h': help, '--version': () => out(VERSION), '-v': () => out(VERSION) };
 const run = commands[command];
 if (!run) { console.error(`\n  Unknown command "${command}".`); help(); process.exit(1); }
 Promise.resolve().then(run).catch((e) => fail(e.message));

package/lib/project.js

@@ -19,18 +19,32 @@ export const filesToWrite = (p, appPopup, appSidePanel = null) => [
     ...(appSidePanel ? SIDE_PANEL_FILES.map((f) => `${p.popupDir}${f}`) : []),
     ...(p.extraFiles ?? []).map((f) => f.to),
 ];
+export const SURFACES = ['both', 'popup', 'side-panel', 'none'];
+export const surfacesOf = (v) => SURFACES.includes(v ?? '') ? v : 'both';
+export const hasPopup = (s) => s === 'both' || s === 'popup';
+export const hasSidePanel = (s) => s === 'both' || s === 'side-panel';
+/** The scaffold's own files for those surfaces: the manifest and the background always, the pages as asked for. */
+export const scaffoldFilesFor = (s, all) => all.filter((f) => (f === 'popup.html' ? hasPopup(s) : f === 'sidepanel.html' ? hasSidePanel(s) : f === 'popup.js' || f === 'popup.css' ? s !== 'none' : true));
 /**
  * The scaffold's manifest, once it is known which pages were really written. Chrome refuses to load an extension
  * whose `side_panel.default_path` names a file that is not there — the whole extension, not just the panel — so the
- * minimal extension ships a manifest that names only its popup, and whatever writes the side panel adds it here.
+ * minimal extension ships a manifest that names only its popup, and whatever writes the pages settles it here: the
+ * side panel added with its page, the popup taken out when there is none (the icon stays; the click then opens the
+ * side panel, or nothing, which is what a background-only tool wants).
  */
 export function scaffoldManifest(manifest, wrote) {
+    const out = { ...manifest };
+    if (wrote.popup === false) {
+        const action = { ...out.action };
+        delete action.default_popup;
+        out.action = action;
+    }
     if (!wrote.sidePanel)
-        return manifest;
-    const permissions = Array.isArray(manifest.permissions) ? [...manifest.permissions] : [];
+        return out;
+    const permissions = Array.isArray(out.permissions) ? [...out.permissions] : [];
     if (!permissions.includes('sidePanel'))
         permissions.push('sidePanel');
-    return { ...manifest, permissions, side_panel: { default_path: 'sidepanel.html' } };
+    return { ...out, permissions, side_panel: { default_path: 'sidepanel.html' } };
 }
 /**
  * The last two placeholders in a handed-out file — the extension's own popup and side panel, which only the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolaby",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "description": "The Toolaby command line: sign in once, then wire any Chrome extension to your tool on the Wall — sign-in, the Free plan, licences and subscriptions — or start a new one.",
   "type": "module",
   "bin": {