toolaby 1.6.5 → 1.7.0

package/README.md

@@ -20,8 +20,11 @@ Every command acts on the test Wall (`test.toolaby.app`) unless told `--live` (`
 
 - it adds the Wall's files — a small client library, a config with your tool's id and public key, and the Wall's popup, which stands in front of yours;
 - it adds three lines to your `manifest.json` (a permission and your Wall address) and creates a background file if you have none;
+- it puts the Wall's background in front of yours, `toolaby.background.js`: yours runs as it did — a classic one's `importScripts()` included — and the Wall starts with it;
 - your own code does not change. When your popup opens, the Wall's page checks what the Free plan holds and either sends the person straight to your popup or shows sign-in, the free-use meter or the plans.
 
+It prints what it did in a few rows — `✓` done, `!` worth a look, `→` a step for you, with the exact code — and what to do next, in colour in a terminal (`NO_COLOR` turns it off). When your code sets or reads the popup itself (`chrome.action.setPopup()`, `getPopup()`), it says where; `--own-popup` keeps your popup in front.
+
 If the extension is built with WXT, CRXJS or Plasmo, the command puts the same files where that build expects them and prints the few lines to paste into the framework's config, because the framework generates the manifest itself. Nothing is installed from npm.
 
 **`toolaby create <tool-id>`** makes a new, minimal extension in a folder named after the tool, ready for *Load unpacked*.

package/bin.mjs

@@ -37,13 +37,14 @@ import { deflateRawSync } from 'node:zlib';
 import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
 import { createHmac, randomBytes } from 'node:crypto';
-import { wireManifest, drawsItself, WORKER_LINES } from './lib/manifest.js';
+import { wireManifest, drawsItself, WORKER_LINES, wallWorkerSource, configValues, wrappedBy, namedWorker as workerIn, startsPlatform as startsWall, CLASSIC_CLIENT } from './lib/manifest.js';
+import { wiringSummary, popupSwapIn, ownCode } from './lib/summary.js';
 import { detectProject, CODE_FILES, POPUP_FILES, SIDE_PANEL_FILES, filesToWrite, fillPages, scaffoldManifest, scaffoldFilesFor, surfacesOf, hasPopup, hasSidePanel, SURFACES, STALE_FILES, BUILD_COPY_NOTE, AGENT_FILES, AGENT_ENTRY_FILES } from './lib/project.js';
 import { runMcp } from './lib/mcp.js';
 import { runCheck } from './lib/check.js';
 import { inside, signInPage, devicePolling, opener, privateKind, privateContent, privateCopies, googleKey, projectRoot, gitDirectory, gitObject, gitObjects, gitFile, notAnImage, unpacked, COMPRESSED, publicLinks, privateLinks, oneLine, fetchBounded, fetchHere, readBounded, readText, SCAFFOLD_FILES } from './lib/safe.js';
 
-const VERSION = '1.6.5';
+const VERSION = '1.7.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.
@@ -66,7 +67,13 @@ const side = wall === WALLS.live ? 'Live' : wall === WALLS.test ? 'Test' : wall;
 // nor any character that shows nothing — a zero width, a mark of direction, a filler — which could hide a word.
 const plain = (s) => String(s).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u115f\u1160\u200b-\u200f\u2028-\u202e\u2060-\u2069\u2800\u3164\ufeff\uffa0]/g, '');
 const out = (s = '') => console.log(plain(s));
-const fail = (s) => { console.error(`\n  ${plain(s)}\n`); process.exit(1); };
+// Colour, the command's own: put on after a piece is made plain, never taken from what it prints; off when the output is
+// not a terminal, and when NO_COLOR asks (FORCE_COLOR turns it on). A line of tinted pieces goes out through `say`.
+const colour = !process.env.NO_COLOR && (process.env.FORCE_COLOR ? process.env.FORCE_COLOR !== '0' : !!process.stdout.isTTY && process.env.TERM !== 'dumb');
+const tint = (code) => (s) => (colour ? `\x1b[${code}m${plain(s)}\x1b[0m` : plain(s));
+const [green, yellow, red, cyan, bold, dim] = ['32', '33', '31', '36', '1', '2'].map(tint);
+const say = (s = '') => console.log(s);
+const fail = (s) => { console.error(`\n  ${red('✗')} ${plain(s)}\n`); process.exit(1); };
 
 // ── The session: one per Wall, in the user's config, readable by them alone ─────────────────────────────────────────
 const CONFIG_DIR = join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'toolaby');
@@ -224,7 +231,7 @@ const readJson = (path) => { try { return JSON.parse(readText(path)); } catch {
 /** A project file's text, or `none` where it is no file to read (lib/safe.js readText): a link to a device reads as nothing. */
 const readOr = (path, none = null) => { try { return readText(path); } catch { return none; } };
 /** Whether a background already starts the platform, outside its comments: then it needs no lines added. */
-const startsPlatform = (path) => { try { return /\bstartBackground\s*\(/.test(readText(path).replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, '')); } catch { return false; } };
+const startsPlatform = (path) => { try { return startsWall(readText(path)); } catch { return false; } };
 const isId = (s) => typeof s === 'string' && /^[a-z0-9][a-z0-9-]{1,118}$/.test(s);
 /** Whether anything is at the path, a link to nowhere included (existsSync follows a link, and says no for a dangling one). */
 const there = (path) => { try { lstatSync(path); return true; } catch { return false; } };
@@ -290,9 +297,13 @@ async function wire() {
   const oldConfig = existsSync(configPath) ? readOr(configPath, '') : '';
   const remembered = oldConfig.match(/appPopup:\s*'([^']*)'/)?.[1] || null;
   const rememberedSidePanel = oldConfig.match(/appSidePanel:\s*'([^']*)'/)?.[1] || null;
-  // An extension whose own pages draw the panel — what `create` makes, or "your popup first" — keeps them in front.
-  const ownInFront = drawsItself(manifest, oldConfig);
-  const wiring = project.manifestFile && manifest ? wireManifest(manifest, { site, has, remembered, rememberedSidePanel, manifestKey, ownInFront }) : null;
+  // An extension whose own pages draw the panel — what `create` makes, "your popup first", or asked with --own-popup —
+  // keeps them in front.
+  const ownInFront = flag('--own-popup') || drawsItself(manifest, oldConfig);
+  // The background the manifest names, read from inside the folder only: whether it starts the Wall, or is the Wall's.
+  const namedWorker = workerIn(manifest) ?? '';
+  const workerSource = namedWorker && has(namedWorker) && !inside(dir, namedWorker).why ? readOr(join(dir, namedWorker), '') : null;
+  const wiring = project.manifestFile && manifest ? wireManifest(manifest, { site, has, remembered, rememberedSidePanel, manifestKey, ownInFront, workerSource }) : null;
   const appPopup = wiring ? wiring.appPopup : project.wrapper ? (project.appPopup ?? remembered) : null;
   const appSidePanel = wiring ? wiring.appSidePanel : project.wrapper ? (project.appSidePanel ?? rememberedSidePanel) : null;
   const targets = filesToWrite(project, appPopup, appSidePanel, { popup: !!wiring?.ownPopup, sidePanel: !!wiring?.ownSidePanel });
@@ -301,8 +312,13 @@ async function wire() {
   // What an earlier wiring wrote and this one does not, wherever it put them: taken away, so nothing stale is shipped.
   const stale = [...new Set([project.codeDir, project.popupDir, 'public/', 'src/public/'])].flatMap((under) => STALE_FILES.map((f) => `${under}${f}`)).filter((p) => existsSync(join(dir, p)));
   // The background a manifest names and that is not there is written — at the name the manifest gives, which is the repository's to choose.
-  const worker = wiring ? wiring.writeWorker : project.createWorker?.file ?? null;
-  const at = placesIn(dir, [...targets, ...entries, ...stale, ...(worker ? [worker] : []), ...(wiring?.did.length ? ['manifest.json'] : [])], worker ? { [worker]: 'the background the manifest names' } : {});
+  const worker = wiring ? (wiring.background.kind === 'new' ? wiring.background.file : null) : project.createWorker?.file ?? null;
+  // The extension's own background, with the Wall's in front of it — and, for a classic one, the client as a script.
+  const wrap = wiring?.background.kind === 'wrap' ? wiring.background : null;
+  const classicClient = wrap?.classic ? `${project.codeDir}${CLASSIC_CLIENT}` : null;
+  const at = placesIn(dir, [...targets, ...entries, ...stale, ...(worker ? [worker] : []), ...(wrap ? [wrap.file] : []), ...(classicClient ? [classicClient] : []), ...(wiring?.changed ? ['manifest.json'] : [])], { ...(worker ? { [worker]: 'the background the manifest names' } : {}), ...(wrap ? { [wrap.file]: "the Wall's background, beside yours" } : {}) });
+  // A file of the developer's own where the Wall's background goes is never replaced: only one the Wall wrote.
+  if (wrap && wrap.file !== namedWorker && there(at[wrap.file]) && !wrappedBy(readOr(at[wrap.file], ''))) fail(`${wrap.file} is already in ${dir}, and it is not the Wall's. Rename it, then run this again. Nothing was written.`);
   // Taken for missing, it may only be out of the listing's sight — spelt "./background.js", in dist/, or deeper down:
   // the developer's own background is never replaced by two lines of ours.
   if (worker && there(at[worker])) fail(`${JSON.stringify(worker)}, the background the manifest names, is already in ${dir}; it would have been replaced. Nothing was written.\n  Name it in the manifest as the folder spells it — or, if a build writes it, run this with --into the folder whose manifest.json names it.`);
@@ -312,41 +328,40 @@ async function wire() {
   // A command older than the Wall asks for files the Wall no longer hands out: said, with the way to the current one, rather than a crash.
   // The agent files come from Walls that write them; one that does not is older, not newer, than this command.
   const agentPaths = new Set(AGENT_FILES.map((f) => f.path));
-  const missing = targets.filter((p) => !agentPaths.has(p)).map((p) => p.split('/').pop()).filter((name) => typeof plan.files[name] !== 'string');
+  const missing = [...targets, ...(classicClient ? [classicClient] : [])].filter((p) => !agentPaths.has(p)).map((p) => p.split('/').pop()).filter((name) => typeof plan.files[name] !== 'string');
   if (missing.length) fail(`This command (${VERSION}) is older than the Wall at ${wall}: it expects ${missing.join(', ')}, which the Wall no longer hands out.\n  Update it: npm install -g toolaby@latest — or run the Wall's own copy: npx --yes ${wall}/toolaby.tgz ${command} ${slug}`);
   const wrote = targets.filter((path) => typeof plan.files[path.split('/').pop()] === 'string');
   for (const path of wrote) write(path, fillPages(plan.files[path.split('/').pop()], { appPopup, appSidePanel }));
   for (const f of entries) { write(f, plan.files[f]); wrote.push(f); }
   const ownAgents = has('AGENTS.md') && !readOr(join(dir, 'AGENTS.md'), '').includes('TOOLABY.md');
   for (const p of stale) unlinkSync(at[p]);
-  const did = [];
-  let ownWorker = null;
   if (wiring) {
-    if (wiring.writeWorker) write(wiring.writeWorker, WORKER_LINES);
-    if (wiring.did.length) write('manifest.json', JSON.stringify(wiring.manifest, null, 2) + '\n');
-    did.push(...wiring.did);
-    if (wiring.ownWorker && !startsPlatform(join(dir, wiring.ownWorker.file))) ownWorker = wiring.ownWorker;
+    if (wiring.background.kind === 'new') write(wiring.background.file, WORKER_LINES);
+    // The Wall's background in front of theirs, with what toolaby.config.js starts the Wall with (a classic one carries it).
+    if (wrap) write(wrap.file, wallWorkerSource(wrap, wrap.classic ? configValues(fillPages(plan.files['toolaby.config.js'], { appPopup, appSidePanel })) : null));
+    if (classicClient) write(classicClient, plan.files[CLASSIC_CLIENT]);
+    if (wiring.changed) write('manifest.json', JSON.stringify(wiring.manifest, null, 2) + '\n');
   } else if (project.createWorker) {
     write(project.createWorker.file, project.createWorker.content);
-    did.push(`a background entry, ${project.createWorker.file} (it starts the platform)`);
-  } else if (project.worker && !project.extraFiles && !startsPlatform(join(dir, project.worker))) {
-    // A framework with its own extension point (WXT's module) starts the platform in the background itself.
-    ownWorker = { file: project.worker, classic: false };
   }
-
-  out(`\n  ${oneLine(plan.name)} → ${dir}${project.kind === 'plain' ? '' : `  (${project.label})`}  ·  ${side}${side === 'Test' ? ' (the tk_test_ key; `--live` for the store build)' : ''}\n`);
-  // Each thing done is a line, and names what the manifest and the Wall named: the popup, the background, the address.
-  out(`  Written: ${wrote.join(', ')}${did.length ? `,\n           ${did.map(oneLine).join(',\n           ')}` : ''}.\n`);
-  if (ownAgents) out('  Your AGENTS.md is your own: add a line so coding agents find the Wall\'s guide — "Before changing anything paid, read TOOLABY.md."\n');
-  if (stale.length) out(`  Removed: ${stale.join(', ')} — earlier files, now inside toolaby.js.\n`);
-  for (const sn of project.snippets) out(`  Add to ${sn.file} — yours to paste, the manifest being generated:\n\n${sn.code.split('\n').map((l) => `     ${l}`).join('\n')}\n`);
-  if (ownWorker) out(`  Your background, ${oneLine(ownWorker.file)}: add${ownWorker.classic ? ' — after giving "background" a "type": "module" in manifest.json (importScripts() is not available in a module worker)' : ''}:\n\n${project.workerLines.trimEnd().split('\n').map((l) => `     ${l}`).join('\n')}\n`);
-  if (project.built) out(`  ${BUILD_COPY_NOTE}\n`);
-  out(`  Next: ${project.kind === 'plain' && !project.built ? '' : 'build or start the dev server, then '}chrome://extensions → reload it. The tool's Set up page says "checked in" the moment it starts.`);
-  if (project.note) out(`  ${project.note}\n`);
-  else if (appPopup || appSidePanel) out(`  Your ${appPopup && appSidePanel ? 'popup and side panel open' : appSidePanel ? 'side panel opens' : 'popup opens'} as before; what the Free plan holds (Pricing, in the dashboard) decides when the Wall's panel takes its place.\n`);
-  else if (ownInFront && (wiring?.ownPopup || wiring?.ownSidePanel)) out(`  Your ${wiring.ownPopup && wiring.ownSidePanel ? 'popup and side panel stay' : wiring.ownSidePanel ? 'side panel stays' : 'popup stays'} in front and draw${wiring.ownPopup && wiring.ownSidePanel ? '' : 's'} the panel, as before; toolaby.showPaywall() opens the Wall's page beside it.\n`);
-  else out(`  No popup or side panel to stand in front of: count a use where your feature runs — the Set up page shows the line.\n`);
+  // The extension's own code, read for a popup it swaps while it runs: the Wall's in front of it could be skipped then.
+  const code = appPopup ? [...tree].filter(ownCode).slice(0, 400).map((path) => { let text = ''; try { if (statSync(join(dir, path)).size < 512_000) text = readOr(join(dir, path), ''); } catch { /* gone */ } return { path, text }; }) : [];
+  const summary = wiringSummary({ project, wiring, appPopup, appSidePanel, workerStarts: !!project.worker && startsPlatform(join(dir, project.worker)), popupSwap: popupSwapIn(code) });
+
+  // Wired again, a folder takes `upgrade` (wire, replacing the platform's files): the command, ready to paste.
+  const into = opt('--into');
+  const again = `npx -y toolaby@latest upgrade ${slug}${live ? ' --live' : ''}${into ? ` --into ${/^[\w@%+=:,./-]+$/.test(into) ? into : `'${into.replace(/'/g, "'\\''")}'`}` : ''}`;
+  say(`\n  ${summary.todo ? `${yellow('!')} ${bold('Almost wired')}` : `${green('✓')} ${bold('Wired')}`}  ${plain(oneLine(plan.name))} → ${plain(basename(dir))}  ${dim(`· ${side}${project.kind === 'plain' ? '' : ` · ${project.label}`}`)}\n`);
+  const width = Math.max(...summary.rows.map((r) => r.label.length));
+  for (const r of summary.rows) {
+    const mark = r.tone === 'ok' ? green('✓') : r.tone === 'warn' ? yellow('!') : cyan('→');
+    say(`    ${mark} ${bold(r.label.padEnd(width))}  ${plain(oneLine(r.text))}`);
+    if (r.fix === 'own-popup') say(`      ${' '.repeat(width)}  ${cyan(`${again} --own-popup`)}`);
+    if (r.code) say(`\n${r.code.split('\n').map((l) => `        ${cyan(l)}`).join('\n')}\n`);
+  }
+  if (ownAgents) say(`    ${dim('Your AGENTS.md is your own: add "Before changing anything paid, read TOOLABY.md."')}`);
+  if (stale.length) say(`    ${dim(`Removed: ${stale.join(', ')} (now inside toolaby.js)`)}`);
+  say(`\n  ${bold('Next')}  ${summary.rows.some((r) => r.again) ? `${plain(summary.next.replace(/wire again\.$/, 'run'))} ${cyan(again)}` : plain(summary.next)}\n`);
 }
 
 async function create() {
@@ -756,7 +771,7 @@ function mcp() {
 }
 
 async function check() {
-  const passed = await runCheck({ dir: opt('--into') ?? positional[0] ?? '.', out, api: (path, o = {}) => api(path, o), token: storedToken, detectProject, wireManifest, listTree, readJson, browser: flag('--browser') });
+  const passed = await runCheck({ mark: (tone, text) => say(`  ${tone === 'ok' ? green('✓') : tone === 'warn' ? yellow('!') : red('✗')} ${plain(text)}`), dir: opt('--into') ?? positional[0] ?? '.', out, api: (path, o = {}) => api(path, o), token: storedToken, detectProject, wireManifest, listTree, readJson, browser: flag('--browser') });
   if (!passed) process.exit(1);
 }
 
@@ -767,6 +782,7 @@ function help() {
     toolaby wire <tool-id>             wire the extension in this folder to your tool, on Test
     toolaby wire <tool-id> --live      the same, on Live: the store build
                                        --into <folder>   another folder     --force   replace the platform's files
+                                       --own-popup       keep your popup in front (the Wall's opens from toolaby.showPaywall())
     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)

package/lib/check.js

@@ -8,6 +8,8 @@ import { join, relative, resolve } from 'node:path';
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { oneLine, keySite, fetchBounded, readText } from './safe.js';
+import { wrappedBy, namedWorker, startsPlatform as startsWall } from './manifest.js';
+import { popupSwapIn, ownCode } from './summary.js';
 
 const KEY = /tk_(test|live|dev)_[A-Za-z0-9_-]{20,}/;
 /** A tool id as the Wall makes them (lib/mcp.js has the same): the only thing the check puts after a Wall's address. */
@@ -53,12 +55,14 @@ export function featuresUsed(source) {
   return keys;
 }
 
-export async function runCheck({ dir: given, out, api, token, detectProject, wireManifest, listTree, readJson, browser }) {
+export async function runCheck({ dir: given, out, api, token, detectProject, wireManifest, listTree, readJson, browser, mark = null }) {
   const dir = resolve(given ?? '.');
   const results = [];
-  const ok = (s) => { results.push('ok'); out(`  ✓ ${s}`); };
-  const warn = (s) => { results.push('warn'); out(`  ! ${s}`); };
-  const bad = (s) => { results.push('bad'); out(`  ✗ ${s}`); };
+  // `mark` prints a line with the command's own coloured mark (bin.mjs); without it, the plain one.
+  const line = (tone, sign, s) => { results.push(tone); if (mark) mark(tone, s); else out(`  ${sign} ${s}`); };
+  const ok = (s) => line('ok', '✓', s);
+  const warn = (s) => line('warn', '!', s);
+  const bad = (s) => line('bad', '✗', s);
   out(`\n  Checking ${dir}\n`);
 
   // 1. What the folder is.
@@ -105,14 +109,46 @@ export async function runCheck({ dir: given, out, api, token, detectProject, wir
 
   // 4. The manifest, against the platform's own wiring rules: what wiring it again would add.
   if (project.manifestFile && manifest) {
-    const again = wireManifest(manifest, { site: key.site, has, remembered: null, rememberedSidePanel: null, manifestKey: typeof manifest.key === 'string' ? manifest.key : null });
-    const needed = (again.did ?? []).filter((d) => !/popup|side panel/i.test(d));
+    const named = namedWorker(manifest) ?? '';
+    const workerText = named && has(named) ? readOr(join(dir, named), null) : null;
+    const again = wireManifest(manifest, { site: key.site, has, remembered: null, rememberedSidePanel: null, manifestKey: typeof manifest.key === 'string' ? manifest.key : null, workerSource: workerText });
+    // The background is said below, in a line of its own.
+    const needed = (again.did ?? []).filter((d) => !/popup|side panel|service worker/i.test(d));
     if (needed.length) bad(`The manifest lacks what the Wall needs: ${needed.map(oneLine).join('; ')}. \`npx -y toolaby@latest upgrade ${key.slug}\` adds it.`);
     else ok('The manifest has the permissions and host permissions the Wall needs.');
     // The identity: without the `key`, each copy's id follows its folder, and once the extension is named the tool key refuses every copy not chosen.
     if (typeof manifest.key !== 'string' && /manifestKey:\s*'[A-Za-z0-9+/]{100,}={0,2}'/.test(configText)) warn(`manifest.json has no "key": each copy's id then depends on its folder, and once your extension is named the tool key refuses any copy you did not choose on the Keys page. \`npx -y toolaby@latest upgrade ${key.slug}\` adds it.`);
   } else warn(`The manifest is generated by ${project.label}: build, then check the built manifest has ${key.site}/* in host_permissions and externally_connectable.`);
 
+  // 4b. The background starts the Wall: the popup and every page ask it everything, so without it nothing answers.
+  const upgrade = `\`npx -y toolaby@latest upgrade ${key.slug}\``;
+  if (project.manifestFile && manifest) {
+    const named = namedWorker(manifest) ?? '';
+    const text = named && has(named) ? readOr(join(dir, named), null) : null;
+    const wraps = wrappedBy(text);
+    // What wiring again would do with it, by the same rules (wiring/manifest).
+    const b = wireManifest(manifest, { site: key.site, has, workerSource: text }).background;
+    if (!named || text === null) bad(`Nothing starts the Wall: the manifest names no background${named ? ` it can find (${oneLine(named)})` : ''}. ${upgrade} adds one.`);
+    else if (b.kind === 'gone') bad(`${oneLine(named)} runs ${oneLine(b.wraps)}, which is no longer in the folder. Put your background's file name in manifest.json, then ${upgrade}.`);
+    else if (b.kind === 'rename') bad(`The Wall can't load a file named ${JSON.stringify(oneLine(b.file))}. Rename it to ${oneLine(b.to)}, put that in manifest.json, then ${upgrade}.`);
+    else if (b.kind === 'lines') bad(`${oneLine(b.file)} never starts the Wall, so the popup cannot reach it. Add at its top: ${oneLine(project.workerLines.trim().replace(/\n+/g, ' '))}`);
+    else if (wraps) {
+      // A classic one carries the key it starts with: the one in toolaby.config.js, or the background starts with an old one.
+      const carried = text.match(/"key":"([^"]+)"/)?.[1];
+      if (carried && carried !== keyText) bad(`${oneLine(named)} starts the Wall with another key than toolaby.config.js. \`npx -y toolaby@latest upgrade ${key.slug}\` writes both again.`);
+      else ok(`The background starts the Wall, and runs yours (${oneLine(wraps)}).`);
+    } else if (startsWall(text)) ok(`The background (${oneLine(named)}) starts the Wall.`);
+    else bad(`${oneLine(named)} never starts the Wall, so the popup cannot reach it. ${upgrade} puts the Wall's in front of it; yours stays as it is.`);
+  } else if (project.worker && !project.extraFiles) {
+    if (startsWall(readOr(join(dir, project.worker), ''))) ok(`The background (${oneLine(project.worker)}) starts the Wall.`);
+    else bad(`${oneLine(project.worker)} never starts the Wall, so the popup cannot reach it. Add at its top: ${oneLine(project.workerLines.trim().replace(/\n+/g, ' '))}`);
+  }
+  // A popup the code swaps while it runs: the Wall's in front of it can be skipped.
+  if (project.manifestFile && manifest?.action?.default_popup === 'toolaby-popup.html') {
+    const swap = popupSwapIn(sourceFiles(dir).map((f) => relative(dir, f).split('\\').join('/')).filter(ownCode).map((path) => ({ path, text: readOr(join(dir, path), '') })));
+    if (swap) warn(`Your code handles the popup itself (${oneLine(swap.call)} in ${oneLine(swap.file)}): \`npx -y toolaby@latest upgrade ${key.slug} --own-popup\` keeps yours in front.`);
+  }
+
   // 5. The client, as fresh as the Wall's.
   const client = await fetchBounded(`${key.site}/client/toolaby.js`).then((r) => (r.ok && r.body ? r.body.toString('utf8') : null)).catch(() => null);
   if (client === null) warn('The Wall\'s current client could not be read to compare.');

package/lib/manifest.js

@@ -6,7 +6,9 @@
  * the storage permission; the platform's address as a host permission and
  * for externally_connectable (the site's sign-in and purchase handoffs); a
  * module service worker when the manifest names none, or names one that is
- * not there; the Wall's popup in front of the extension's own — and its
+ * not there — and in front of the extension's own background, the Wall's,
+ * which runs it and then starts the platform (wallWorkerSource), so nothing
+ * of theirs is edited; the Wall's popup in front of the extension's own — and its
  * side panel in front of the extension's side panel — which the
  * configuration then remembers; and the extension's identity — the `key`
  * that fixes its id, which the tool key is bound to (identity.ts) — unless
@@ -18,6 +20,55 @@
 export const WALL_POPUP = 'toolaby-popup.html';
 export const WALL_SIDE_PANEL = 'toolaby-sidepanel.html';
 export const WORKER_LINES = "import { toolaby } from './toolaby.js';\n\ntoolaby.startBackground();\n";
+/** The Wall's background: the one it writes when the manifest names none, and the one it stands in front of theirs. */
+export const WALL_WORKER = 'toolaby.background.js';
+/** The client as a classic script (a global `Toolaby`): what a classic background loads with importScripts(). */
+export const CLASSIC_CLIENT = 'toolaby-client.js';
+/** The line in the Wall's background that names the extension's own, which it runs: read back when wired again. */
+const WRAPS = /^\/\/ toolaby-wraps: (.+)$/m;
+/** A background the Wall's can name in the code it writes: a path inside the folder, plain characters, a script. */
+const SCRIPT_PATH = /^(?!.*\.\.)(?!.*\/\/)[A-Za-z0-9_][A-Za-z0-9_\-./]*\.m?js$/;
+/** Code without its comments, strings kept whole, so a `//` inside one is not taken for a comment. */
+export function withoutComments(text) {
+    return text.replace(/("(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|`(?:[^`\\]|\\.)*`)|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, (m, str) => (str ? m : ''));
+}
+/** Whether a background already starts the Wall itself: then it is left as it is. */
+export const startsPlatform = (source) => /\b(?:startBackground|ensureBackground)\s*\(/.test(withoutComments(source));
+/** The extension's own background the Wall's runs, read from the Wall's; null for any other file. */
+export const wrappedBy = (source) => source?.match(WRAPS)?.[1]?.trim() || null;
+/**
+ * The Wall's background in front of the extension's own (`file`, beside `wraps`, so a relative importScripts() of
+ * theirs still finds its files): it runs theirs as before, then starts the Wall unless theirs did — ensureBackground(),
+ * so a background that starts it with handlers of its own keeps them. A module background gets a module; a classic
+ * one a classic script, which loads the client as one (CLASSIC_CLIENT), so its importScripts() work as they did. The
+ * classic one carries the configuration it starts with — the key and the pages of toolaby.config.js — which wiring
+ * again rewrites with it.
+ */
+export function wallWorkerSource(b, config) {
+    const depth = b.file.split('/').length - 1;
+    const up = '../'.repeat(depth);
+    const own = b.wraps.slice(b.wraps.lastIndexOf('/') + 1);
+    const head = `// The Wall's background, in front of yours: ${b.wraps} runs as it did, then the Wall starts.\n// Written by the Wall's wiring (toolaby wire): keep it, never edit it. Your code stays in ${b.wraps}.\n// toolaby-wraps: ${b.wraps}\n`;
+    if (!b.classic)
+        return `${head}import { toolaby } from '${up || './'}toolaby.js';\nimport './${own}';\n\ntoolaby.ensureBackground();\n`;
+    const c = config ?? { key: '', appPopup: '', appSidePanel: '' };
+    return `${head}importScripts('${up}${CLASSIC_CLIENT}');\nself.toolaby = Toolaby(${JSON.stringify({ key: c.key, appPopup: c.appPopup, appSidePanel: c.appSidePanel })});\nimportScripts('${own}');\ntoolaby.ensureBackground();\n`;
+}
+/** What toolaby.config.js starts the Wall with, read from its text: what a classic background of the Wall's carries. */
+export function configValues(text) {
+    const code = withoutComments(text);
+    const get = (name) => code.match(new RegExp(`${name}:\\s*'([^']*)'`))?.[1];
+    const key = get('key');
+    return key ? { key, appPopup: get('appPopup') ?? '', appSidePanel: get('appSidePanel') ?? '' } : null;
+}
+/** A name a background can be loaded by, for one that has none: its characters kept where they can be, the rest a dash. */
+export const loadableName = (file) => {
+    const clean = file.split('/').filter((p) => p && p !== '.' && p !== '..').map((p) => p.replace(/[^A-Za-z0-9_\-.]+/g, '-').replace(/^[^A-Za-z0-9_]+/, '')).filter(Boolean).join('/');
+    const js = /\.m?js$/.test(clean) ? clean : `${clean.replace(/\.[^./]*$/, '') || 'background'}.js`;
+    return js.replace(/-+(?=\.m?js$)/, '');
+};
+/** The background the manifest names, as the folder spells it: "./background.js" is background.js. */
+export const namedWorker = (manifest) => typeof manifest?.background?.service_worker === 'string' ? manifest.background.service_worker.trim().replace(/^(\.\/)+/, '') || null : null;
 /**
  * Whether an earlier wiring left the extension's own pages drawing the panel: a configuration that says '' for both
  * pages while the manifest names none of the Wall's. That is what `create` makes, and the "your popup first" shape
@@ -37,11 +88,19 @@ export function drawsItself(manifest, oldConfig) {
 export function wireManifest(input, o) {
     const manifest = JSON.parse(JSON.stringify(input));
     const did = [];
+    const added = [];
+    const host = (() => { try {
+        return new URL(o.site).host;
+    }
+    catch {
+        return o.site;
+    } })();
     // The identity: the manifest's own key stays (the platform adopts it); otherwise the platform's goes in, and the unpacked extension's id is known before it loads.
     const own = typeof manifest.key === 'string' && manifest.key.trim() ? manifest.key.trim() : null;
     if (!own && o.manifestKey) {
         manifest.key = o.manifestKey;
         did.push('a "key", so the extension keeps one id across reloads and machines');
+        added.push('key');
     }
     const manifestKey = own ?? o.manifestKey ?? null;
     const add = (list, value) => { const arr = Array.isArray(list) ? [...list] : []; if (!arr.includes(value))
@@ -49,15 +108,20 @@ export function wireManifest(input, o) {
     if (!(Array.isArray(manifest.permissions) && manifest.permissions.includes('storage'))) {
         manifest.permissions = add(manifest.permissions, 'storage');
         did.push('the "storage" permission');
+        added.push('storage');
     }
     if (!(Array.isArray(manifest.host_permissions) && manifest.host_permissions.includes(`${o.site}/*`))) {
         manifest.host_permissions = add(manifest.host_permissions, `${o.site}/*`);
         did.push(`a host permission for ${o.site}`);
+        if (!added.includes(host))
+            added.push(host);
     }
     const ec = manifest.externally_connectable ?? {};
     if (!(Array.isArray(ec.matches) && ec.matches.includes(`${o.site}/*`))) {
         manifest.externally_connectable = { ...ec, matches: add(ec.matches, `${o.site}/*`) };
         did.push(`externally_connectable for ${o.site}`);
+        if (!added.includes(host))
+            added.push(host);
     }
     // The extension's own popup: the manifest's, or the one remembered when the manifest already names the Wall's.
     const declared = typeof manifest.action?.default_popup === 'string' ? manifest.action.default_popup : null;
@@ -67,6 +131,11 @@ export function wireManifest(input, o) {
         manifest.action = { ...manifest.action, default_popup: WALL_POPUP };
         did.push(`the Wall's popup in front of ${appPopup}: it opens on to yours while the device may, and shows the panel when it may not`);
     }
+    // Asked to keep the extension's own in front after a wiring stood the Wall's there: theirs goes back.
+    if (o.ownInFront && declared === WALL_POPUP && ownPopup) {
+        manifest.action = { ...manifest.action, default_popup: ownPopup };
+        did.push(`${ownPopup} back in front: toolaby.showPaywall() opens the Wall's popup`);
+    }
     // The extension's own side panel, the same way: the Wall's in front, with the permission a side panel needs.
     // Chrome spells it side_panel.default_path, Firefox sidebar_action.default_panel; a manifest may carry both.
     const theirs = (v) => (typeof v === 'string' && v !== WALL_SIDE_PANEL ? v : null);
@@ -75,7 +144,15 @@ export function wireManifest(input, o) {
     const ours = declaredPanel === WALL_SIDE_PANEL || declaredSidebar === WALL_SIDE_PANEL;
     const ownSidePanel = theirs(declaredPanel) ?? theirs(declaredSidebar) ?? (ours ? o.rememberedSidePanel || null : null);
     const appSidePanel = o.ownInFront ? null : ownSidePanel;
-    if (o.ownInFront) { /* the extension's own side panel stays in front, as its popup does */ }
+    if (o.ownInFront) {
+        // The extension's own side panel stays in front, as its popup does — and goes back there after a wiring put the Wall's.
+        if (declaredPanel === WALL_SIDE_PANEL && ownSidePanel) {
+            manifest.side_panel = { ...manifest.side_panel, default_path: ownSidePanel };
+            did.push(`${ownSidePanel} back in front: toolaby.showPaywall() opens the Wall's side panel`);
+        }
+        if (declaredSidebar === WALL_SIDE_PANEL && ownSidePanel)
+            manifest.sidebar_action = { ...manifest.sidebar_action, default_panel: ownSidePanel };
+    }
     else if (theirs(declaredPanel)) {
         manifest.side_panel = { ...manifest.side_panel, default_path: WALL_SIDE_PANEL };
         if (!(Array.isArray(manifest.permissions) && manifest.permissions.includes('sidePanel')))
@@ -87,16 +164,40 @@ export function wireManifest(input, o) {
         manifest.sidebar_action = { ...manifest.sidebar_action, default_panel: WALL_SIDE_PANEL };
         did.push(`the Wall's side panel in front of ${declaredSidebar} in Firefox's sidebar_action too`);
     }
-    const named = typeof manifest.background?.service_worker === 'string' && manifest.background.service_worker.trim() ? manifest.background.service_worker.trim() : null;
-    let writeWorker = null;
-    let ownWorker = null;
+    // The background. None named, or named and not there: one of the Wall's alone, a module. The extension's own: left as
+    // it is, and the Wall's stood in front of it — beside it, a module for a module and a classic script for a classic
+    // one — unless it starts the Wall already. Wired again, the Wall's is written again for the one it names.
+    const named = namedWorker(manifest);
+    let background;
+    let workerMoved = false;
     if (!named || !o.has(named)) {
-        writeWorker = named ?? (o.has('background.js') ? 'toolaby.background.js' : 'background.js');
-        manifest.background = { service_worker: writeWorker, type: 'module' };
-        did.push(`a service worker, ${writeWorker} (two lines: it starts the platform)`);
+        const file = named ?? (o.has('background.js') ? WALL_WORKER : 'background.js');
+        manifest.background = { service_worker: file, type: 'module' };
+        did.push(`a service worker, ${file} (two lines: it starts the platform)`);
+        background = { kind: 'new', file };
     }
     else {
-        ownWorker = { file: named, classic: manifest.background?.type !== 'module' };
+        const source = o.workerSource ?? '';
+        const wraps = wrappedBy(source);
+        const theirs = wraps ?? named;
+        const classic = manifest.background?.type !== 'module';
+        if (!wraps && startsPlatform(source))
+            background = { kind: 'started', file: named };
+        else if (wraps && !o.has(wraps))
+            background = { kind: 'gone', file: named, wraps };
+        else if (/\.(ts|tsx|mts|cts|jsx)$/.test(theirs))
+            background = { kind: 'lines', file: theirs };
+        else if (!SCRIPT_PATH.test(theirs))
+            background = { kind: 'rename', file: theirs, to: loadableName(theirs) };
+        else {
+            const file = wraps ? named : `${theirs.includes('/') ? theirs.slice(0, theirs.lastIndexOf('/') + 1) : ''}${WALL_WORKER}`;
+            if (!wraps) {
+                manifest.background = { ...manifest.background, service_worker: file };
+                workerMoved = true;
+            }
+            background = { kind: 'wrap', file, wraps: theirs, classic };
+        }
     }
-    return { manifest, did, writeWorker, ownWorker, appPopup, appSidePanel, manifestKey, ownPopup, ownSidePanel };
+    const changed = did.length > 0 || workerMoved;
+    return { manifest, did, added, changed, background, appPopup, appSidePanel, manifestKey, ownPopup, ownSidePanel };
 }

package/lib/project.js

@@ -1,6 +1,6 @@
 // Generated from wall/src/packages/wiring/project.ts by wall/scripts/pack-create.mjs — edit there.
 /** What to tell a developer whose build ships the extension — the Wire button, the command and the Set up page all say it in these words. */
-export const BUILD_COPY_NOTE = 'A build ships this extension: make sure it copies the platform\'s files to its output — toolaby.js, toolaby.config.js and toolaby-popup.html (toolaby-sidepanel.html too, with a side panel) — the way it copies your popup.html.';
+export const BUILD_COPY_NOTE = 'A build ships this extension: make sure it copies every toolaby* file to its output — toolaby.js, toolaby.config.js, toolaby-popup.html and the rest — the way it copies your popup.html.';
 /** Always written, where the build imports from: the platform as one file (the client and the popup UI), its config, its types. */
 export const CODE_FILES = ['toolaby.config.js', 'toolaby.js', 'toolaby.d.ts'];
 /** Beside the client when the build generates the manifest: the fragment it spreads in, derived from the key (boilerplate/toolaby.manifest.js). */
@@ -161,7 +161,7 @@ export function detectProject(o) {
         const declared = typeof manifest?.action?.default_popup === 'string' ? manifest.action.default_popup : null;
         // Chrome's side_panel, else Firefox's sidebar_action: the same page, two spellings.
         const declaredPanel = typeof manifest?.side_panel?.default_path === 'string' ? manifest.side_panel.default_path : typeof manifest?.sidebar_action?.default_panel === 'string' ? manifest.sidebar_action.default_panel : null;
-        const named = typeof manifest?.background?.service_worker === 'string' ? manifest.background.service_worker : null;
+        const named = typeof manifest?.background?.service_worker === 'string' ? manifest.background.service_worker.trim().replace(/^(\.\/)+/, '') || null : null;
         const workerFile = named && has(named) ? named : 'background.js';
         return {
             kind: crxjs ? 'crxjs' : 'plain', label: crxjs ? 'CRXJS' : 'a plain extension', codeDir: '', popupDir: '', manifestFile: 'manifest.json', wrapper: true, built: crxjs ? false : built, foundManifest: null,

package/lib/summary.js

@@ -0,0 +1,73 @@
+// Generated from wall/src/packages/wiring/summary.ts by wall/scripts/pack-create.mjs — edit there.
+import { withoutComments } from './manifest.js';
+import { importPath } from './project.js';
+export function popupSwapIn(files) {
+    for (const f of files) {
+        const m = withoutComments(f.text).match(/\b(chrome|browser)\.(action|browserAction)\.(setPopup|getPopup)\s*\(/);
+        if (m)
+            return { file: f.path, call: `${m[1]}.${m[2]}.${m[3]}()` };
+    }
+    return null;
+}
+/** Whether a path is the extension's own code, for popupSwapIn: a script, not the Wall's, not a dependency's or a build's. */
+export const ownCode = (path) => /\.(m?js|jsx|ts|tsx)$/.test(path) && !/(^|\/)toolaby[^/]*$/.test(path) && !/(^|\/)(node_modules|dist|build|\.output|\.wxt|\.plasmo)\//.test(path);
+export function wiringSummary(o) {
+    const { project: p, wiring: w } = o;
+    const rows = [];
+    // The popup: the Wall's in front of the extension's, or theirs in front and the Wall's beside it, or none at all.
+    const ownPopup = w?.ownPopup ?? null;
+    if (o.appPopup) {
+        rows.push(o.popupSwap
+            ? { tone: 'warn', label: 'Popup', text: `Your code handles the popup itself (${o.popupSwap.call} in ${o.popupSwap.file}), so keep yours in front`, fix: 'own-popup' }
+            : { tone: 'ok', label: 'Popup', text: `The Wall checks first, then opens ${o.appPopup}` });
+    }
+    else if (ownPopup)
+        rows.push({ tone: 'ok', label: 'Popup', text: `Yours stays in front; toolaby.showPaywall() opens the Wall's` });
+    else if (p.note)
+        rows.push({ tone: 'warn', label: 'Popup', text: p.note });
+    else if (!o.appSidePanel && !w?.ownSidePanel)
+        rows.push({ tone: 'ok', label: 'Popup', text: 'None: the Wall steps in where your code calls toolaby.gate()' });
+    if (o.appSidePanel)
+        rows.push({ tone: 'ok', label: 'Side panel', text: `The Wall checks first, then opens ${o.appSidePanel}` });
+    else if (w?.ownSidePanel)
+        rows.push({ tone: 'ok', label: 'Side panel', text: `Yours stays in front; toolaby.showPaywall() opens the Wall's` });
+    // The background: what starts the Wall.
+    if (w) {
+        const b = w.background;
+        if (b.kind === 'new')
+            rows.push({ tone: 'ok', label: 'Background', text: `${b.file} starts the Wall` });
+        else if (b.kind === 'wrap')
+            rows.push({ tone: 'ok', label: 'Background', text: `${b.wraps} runs as before, and the Wall starts with it` });
+        else if (b.kind === 'started')
+            rows.push({ tone: 'ok', label: 'Background', text: `${b.file} starts the Wall` });
+        else if (b.kind === 'lines')
+            rows.push({ tone: 'todo', label: 'Background', text: `Add these 2 lines to the top of ${b.file}:`, code: `import { toolaby } from '${importPath(b.file)}';\n\ntoolaby.startBackground();` });
+        else if (b.kind === 'gone')
+            rows.push({ tone: 'todo', label: 'Background', text: `${b.wraps} is no longer in the folder. Put your background's file name in manifest.json:`, code: '"background": { "service_worker": "your-background.js" }', again: true });
+        else
+            rows.push({ tone: 'todo', label: 'Background', text: `The Wall can't load a file named "${b.file}". Rename it to ${b.to}, and in manifest.json:`, code: `"background": { "service_worker": "${b.to}" }`, again: true });
+    }
+    else if (p.extraFiles?.length)
+        rows.push({ tone: 'ok', label: 'Background', text: `${p.label} starts the Wall (${p.extraFiles.map((f) => f.to).join(', ')})` });
+    else if (p.createWorker)
+        rows.push({ tone: 'ok', label: 'Background', text: `${p.createWorker.file} starts the Wall` });
+    else if (p.worker && !o.workerStarts)
+        rows.push({ tone: 'todo', label: 'Background', text: `Add these 2 lines to the top of ${p.worker}:`, code: p.workerLines.trim() });
+    else if (p.worker)
+        rows.push({ tone: 'ok', label: 'Background', text: `${p.worker} starts the Wall` });
+    // The manifest: what it gained, or, generated by a framework, what its config needs.
+    if (w)
+        rows.push({ tone: 'ok', label: 'Manifest', text: w.added.length ? w.added.join(' · ') : 'Has what the Wall needs' });
+    for (const sn of p.snippets)
+        rows.push({ tone: 'todo', label: 'Manifest', text: `Add to ${sn.file}:`, code: sn.code.trim() });
+    if (p.built)
+        rows.push({ tone: 'warn', label: 'Build', text: 'Your build must copy every toolaby* file into its output' });
+    const steps = rows.filter((r) => r.tone === 'todo').length;
+    const todo = steps > 0;
+    const doThem = steps > 1 ? 'Do the steps above' : 'Do the step above';
+    const reload = p.kind === 'plain' && !p.built ? 'reload it in chrome://extensions' : 'build it (or start the dev server), then reload it in chrome://extensions';
+    const next = rows.some((r) => r.again)
+        ? `${doThem}, then wire again.`
+        : `${todo ? `${doThem}, then ${reload}` : reload.charAt(0).toUpperCase() + reload.slice(1)}. The Set up page turns green when it checks in.`;
+    return { rows, todo, next };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolaby",
-  "version": "1.6.5",
+  "version": "1.7.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; check it, and give coding agents the Wall as an MCP server.",
   "type": "module",
   "bin": {