toolaby 1.0.2 → 1.1.0

package/bin.mjs

@@ -22,9 +22,9 @@ import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
 import { wireManifest, WORKER_LINES } from './lib/manifest.js';
-import { detectProject, CODE_FILES, filesToWrite } from './lib/project.js';
+import { detectProject, CODE_FILES, filesToWrite, BUILD_COPY_NOTE } from './lib/project.js';
 
-const VERSION = '1.0.2';
+const VERSION = '1.1.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.
@@ -155,10 +155,11 @@ const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8'))
 const isId = (s) => typeof s === 'string' && /^[a-z0-9][a-z0-9-]{1,118}$/.test(s);
 
 /** The tool's files from the Wall, as the signed-in developer: a tool of theirs, or a clear no. */
-async function filesFor(slug, scaffold) {
+async function filesFor(slug, scaffold, manifestKey = null) {
   const token = await tokenOrLogin();
-  const res = await api(`/api/cli/wiring/${slug}${scaffold ? '?scaffold=1' : ''}`, { token });
-  if (res.status === 401) { out('  The stored session is no longer valid; signing in again.'); await login(); return filesFor(slug, scaffold); }
+  const q = new URLSearchParams(); if (scaffold) q.set('scaffold', '1'); if (manifestKey) q.set('manifestKey', manifestKey);
+  const res = await api(`/api/cli/wiring/${slug}${q.size ? `?${q}` : ''}`, { token });
+  if (res.status === 401) { out('  The stored session is no longer valid; signing in again.'); await login(); return filesFor(slug, scaffold, manifestKey); }
   if (res.status === 404) {
     // Say who the command is: the tool may well exist — in a workspace of another account of theirs.
     const me = await api('/api/cli/me', { token }).catch(() => null);
@@ -178,16 +179,19 @@ async function wire() {
   const has = (p) => tree.has(p.replace(/\/$/, ''));
   const manifest = has('manifest.json') ? readJson(join(dir, 'manifest.json')) : null;
   if (has('manifest.json') && !manifest) fail('manifest.json could not be read as JSON.');
-  const plan = await filesFor(slug, false);
+  // A key the manifest already has is the identity the platform adopts; otherwise the platform's goes in.
+  const plan = await filesFor(slug, false, typeof manifest?.key === 'string' ? manifest.key : null);
   const site = plan.site;
+  const manifestKey = plan.identity?.manifestKey ?? null;
   const configSource = ['manifest.config.ts', 'manifest.config.js', 'manifest.ts', 'src/manifest.ts'].find(has);
-  const project = detectProject({ has, packageJson: has('package.json') ? readJson(join(dir, 'package.json')) : null, manifest, manifestSource: configSource ? readFileSync(join(dir, configSource), 'utf8') : null, site });
-  if (project.kind === 'unknown') fail(`${dir} has no manifest.json and is not a WXT, CRXJS or Plasmo project — run this inside your extension's folder, or point --into at it.`);
+  const project = detectProject({ has, packageJson: has('package.json') ? readJson(join(dir, 'package.json')) : null, manifest, manifestSource: configSource ? readFileSync(join(dir, configSource), 'utf8') : null, site, tree, manifestKey });
+  // Nothing recognised: nothing is written and nothing guessed. A manifest below the top is where to point --into; otherwise the Set up page's Do it myself has the files and the three things to paste.
+  if (project.kind === 'unknown') fail(`${dir} has no manifest.json at the top and is not a WXT, CRXJS or Plasmo project${project.foundManifest ? ` — there is one at ${project.foundManifest}: run this with --into ${dirname(project.foundManifest) || '.'}` : ''}.\n  Nothing was written. For a layout of your own, the tool's Set up page → Do it myself has the files and the three things to paste.`);
 
   // The extension's own popup: the manifest's, or — wired before — the one the existing configuration remembers.
   const configPath = join(dir, `${project.codeDir}toolaby.config.js`);
   const remembered = existsSync(configPath) ? readFileSync(configPath, 'utf8').match(/appPopup:\s*'([^']*)'/)?.[1] || null : null;
-  const wiring = project.manifestFile && manifest ? wireManifest(manifest, { site, has, remembered }) : null;
+  const wiring = project.manifestFile && manifest ? wireManifest(manifest, { site, has, remembered, manifestKey }) : null;
   const appPopup = wiring ? wiring.appPopup : project.wrapper ? (project.appPopup ?? remembered) : null;
   const targets = filesToWrite(project, appPopup);
   const present = targets.filter((f) => existsSync(join(dir, f)));
@@ -212,7 +216,8 @@ async function wire() {
   out(`  Written: ${targets.join(', ')}${did.length ? `,\n           ${did.join(',\n           ')}` : ''}.\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, ${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`);
-  out(`  Next: ${project.kind === 'plain' ? '' : '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.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) out(`  Your popup opens as before; what the Free plan holds (Pricing, in the dashboard) decides when the Wall's panel takes its place.\n`);
   else out(`  No popup to stand in front of: count a use where your feature runs — the Set up page shows the line.\n`);

package/lib/manifest.js

@@ -6,15 +6,25 @@
  * 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; and the Wall's popup in front of the extension's own, which
- * the configuration then remembers. Pure: given the manifest and what is
- * on disk, it says what to write.
+ * not there; the Wall's popup in front of the extension's own, 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
+ * the manifest has one of its own, which is then the identity the platform
+ * adopts. Pure: given the manifest and what is on disk, it says what to
+ * write.
  */
 export const WALL_POPUP = 'toolaby-popup.html';
 export const WORKER_LINES = "import { toolaby } from './toolaby.js';\n\ntoolaby.startBackground();\n";
 export function wireManifest(input, o) {
     const manifest = JSON.parse(JSON.stringify(input));
     const did = [];
+    // 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 and the platform knows it');
+    }
+    const manifestKey = own ?? o.manifestKey ?? null;
     const add = (list, value) => { const arr = Array.isArray(list) ? [...list] : []; if (!arr.includes(value))
         arr.push(value); return arr; };
     if (!(Array.isArray(manifest.permissions) && manifest.permissions.includes('storage'))) {
@@ -48,5 +58,5 @@ export function wireManifest(input, o) {
     else {
         ownWorker = { file: named, classic: manifest.background?.type !== 'module' };
     }
-    return { manifest, did, writeWorker, ownWorker, appPopup };
+    return { manifest, did, writeWorker, ownWorker, appPopup, manifestKey };
 }

package/lib/project.js

@@ -1,4 +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, toolaby-client.module.js, paywall.js, paywall.css and toolaby-popup.* — the way it copies your popup.html.';
 /** Always written, where the build imports from: the client, its config and types, and the panel a popup of the developer's own can draw. */
 export const CODE_FILES = ['toolaby.config.js', 'toolaby.js', 'toolaby-client.module.js', 'toolaby.d.ts', 'paywall.js', 'paywall.css'];
 /** The Wall's popup, where the build copies files as they are; it imports the panel beside it, so the panel goes there too when that is elsewhere. */
@@ -19,6 +21,9 @@ const dep = (pkg, name) => !!(pkg?.dependencies?.[name] || pkg?.devDependencies?
 const first = (has, candidates) => candidates.find(has) ?? null;
 export function detectProject(o) {
     const { has, packageJson: pkg, manifest, site } = o;
+    const keyLine = o.manifestKey ? `key: '${o.manifestKey}',` : null;
+    const scripts = pkg?.scripts ?? {};
+    const built = !!scripts.build || has('dist') || has('build');
     const wxt = dep(pkg, 'wxt') || !!first(has, ['wxt.config.ts', 'wxt.config.js', 'wxt.config.mts', 'wxt.config.mjs']);
     const plasmo = dep(pkg, 'plasmo');
     const crxjs = dep(pkg, '@crxjs/vite-plugin');
@@ -34,6 +39,7 @@ export function detectProject(o) {
             `// wxt.config.ts — what the Wall needs in the manifest${appPopup ? ', and its popup in front of yours' : ''}`,
             `export default defineConfig({`,
             `  manifest: {`,
+            ...(keyLine ? [`    ${keyLine} // the extension's id, known to the platform`] : []),
             `    permissions: ['storage'],`,
             `    host_permissions: ['${site}/*'],`,
             `    externally_connectable: { matches: ['${site}/*'] },`,
@@ -49,7 +55,7 @@ export function detectProject(o) {
             `});`,
         ].join('\n');
         return {
-            kind: 'wxt', label: 'WXT', codeDir: '', popupDir: `${src}public/`, manifestFile: null, wrapper: true, appPopup, worker,
+            kind: 'wxt', label: 'WXT', codeDir: '', popupDir: `${src}public/`, manifestFile: null, wrapper: true, appPopup, worker, built: false, foundManifest: null,
             createWorker: worker ? null : { file: workerFile, content: workerLines },
             workerLines, snippets: [{ file: first(has, ['wxt.config.ts', 'wxt.config.js', 'wxt.config.mts', 'wxt.config.mjs']) ?? 'wxt.config.ts', language: 'ts', code }],
         };
@@ -62,12 +68,12 @@ export function detectProject(o) {
         const worker = first(has, [`${src}background.ts`, `${src}background.js`, `${src}background/index.ts`, `${src}background/index.js`]);
         const workerFile = worker ?? `${src}background.ts`;
         const workerLines = `import { toolaby } from '${importPath(workerFile)}';\n\ntoolaby.startBackground();\n`;
-        const code = JSON.stringify({ manifest: { permissions: ['storage'], host_permissions: [`${site}/*`], externally_connectable: { matches: [`${site}/*`] } } }, null, 2).replace(/^\{\n|\n\}$/g, '');
+        const code = JSON.stringify({ manifest: { ...(o.manifestKey ? { key: o.manifestKey } : {}), permissions: ['storage'], host_permissions: [`${site}/*`], externally_connectable: { matches: [`${site}/*`] } } }, null, 2).replace(/^\{\n|\n\}$/g, '');
         return {
-            kind: 'plasmo', label: 'Plasmo', codeDir: '', popupDir: '', manifestFile: null, wrapper: false, appPopup: null, worker,
+            kind: 'plasmo', label: 'Plasmo', codeDir: '', popupDir: '', manifestFile: null, wrapper: false, appPopup: null, worker, built: false, foundManifest: null,
             createWorker: worker ? null : { file: workerFile, content: workerLines },
             workerLines, snippets: [{ file: 'package.json', language: 'json', code }],
-            note: 'Plasmo builds only the pages its manifest names, so the Wall\'s popup cannot stand in front of yours: ask the gate in your popup — the lines under Fine-tune.',
+            note: 'Plasmo builds only the pages its manifest names, so the Wall\'s popup cannot stand in front of yours: ask the gate in your popup — the lines are in the docs, under Plasmo.',
         };
     }
     if (crxjs && !has('manifest.json')) {
@@ -80,6 +86,7 @@ export function detectProject(o) {
         const workerLines = `import { toolaby } from '${importPath(workerFile)}';\n\ntoolaby.startBackground();\n`;
         const code = [
             `// ${configFile ?? 'manifest.config.ts'} — add inside defineManifest({ … })`,
+            ...(keyLine && !/\bkey:/.test(source) ? [`${keyLine} // the extension's id, known to the platform`] : []),
             `permissions: ['storage'],`,
             `host_permissions: ['${site}/*'],`,
             `externally_connectable: { matches: ['${site}/*'] },`,
@@ -96,21 +103,26 @@ export function detectProject(o) {
             `});`,
         ].join('\n');
         return {
-            kind: 'crxjs', label: 'CRXJS', codeDir: '', popupDir: '', manifestFile: null, wrapper: true, appPopup, worker: worker && has(worker) ? worker : null,
+            kind: 'crxjs', label: 'CRXJS', codeDir: '', popupDir: '', manifestFile: null, wrapper: true, appPopup, worker: worker && has(worker) ? worker : null, built: false, foundManifest: null,
             createWorker: worker && has(worker) ? null : { file: workerFile, content: workerLines },
             workerLines, snippets: [{ file: configFile ?? 'manifest.config.ts', language: 'ts', code }, ...(appPopup ? [{ file: viteFile, language: 'ts', code: vite }] : [])],
         };
     }
     if (has('manifest.json')) {
         // A plain extension, or CRXJS with a real manifest.json: the manifest is edited (wireManifest), everything at the root.
+        // A plain extension with a build (webpack, Rollup, Parcel, esbuild…) is wired the same way — the manifest is a file and
+        // the files go beside it — but only what the build copies reaches the output, so that is said.
         const declared = typeof manifest?.action?.default_popup === 'string' ? manifest.action.default_popup : null;
         const named = typeof manifest?.background?.service_worker === 'string' ? manifest.background.service_worker : 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,
+            kind: crxjs ? 'crxjs' : 'plain', label: crxjs ? 'CRXJS' : 'a plain extension', codeDir: '', popupDir: '', manifestFile: 'manifest.json', wrapper: true, built: crxjs ? false : built, foundManifest: null,
             appPopup: declared && declared !== 'toolaby-popup.html' ? declared : null, worker: named && has(named) ? named : null, createWorker: null,
             workerLines: `import { toolaby } from '${importPath(workerFile)}';\n\ntoolaby.startBackground();\n`, snippets: [],
         };
     }
-    return { kind: 'unknown', label: 'unknown', codeDir: '', popupDir: '', manifestFile: null, wrapper: false, appPopup: null, worker: null, createWorker: null, workerLines: '', snippets: [] };
+    // Nothing recognised. A manifest below the root — src/, public/, a package of a monorepo — is where the wiring should have
+    // been pointed, and is said; the shallowest one, since a fixture or a dependency may carry another.
+    const foundManifest = [...(o.tree ?? [])].filter((p) => p.endsWith('/manifest.json') && !p.includes('node_modules/')).sort((a, b) => a.split('/').length - b.split('/').length || a.localeCompare(b))[0] ?? null;
+    return { kind: 'unknown', label: 'unknown', codeDir: '', popupDir: '', manifestFile: null, wrapper: false, appPopup: null, worker: null, createWorker: null, workerLines: '', snippets: [], built, foundManifest };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolaby",
-  "version": "1.0.2",
+  "version": "1.1.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": { "toolaby": "./bin.mjs" },