@medeo-plugin/cli 0.7.0 → 0.8.0

package/app.mjs

@@ -35,17 +35,23 @@ export async function locate({ channel } = {}) {
 
 /** One request, one reply; Medeo's errors are thrown with its own message. */
 export async function request(op, args = {}, options = {}) {
+  const signal = options.signal;
+  signal?.throwIfAborted();
   const control = options.control ?? await locate(options);
+  signal?.throwIfAborted();
   if (control.protocol !== PROTOCOL) throw new Error(`Medeo speaks control protocol ${control.protocol}; this toolchain speaks ${PROTOCOL}. Update one of them`);
   const line = await new Promise((resolve, reject) => {
     const socket = connect(control.socket);
     let buffer = '';
-    const timer = setTimeout(() => { socket.destroy(); reject(new Error(`Medeo did not answer ${op} in ${TIMEOUT_MS / 1000}s`)); }, TIMEOUT_MS);
+    const cleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); };
+    const abort = () => { cleanup(); socket.destroy(); reject(signal.reason); };
+    const timer = setTimeout(() => { cleanup(); socket.destroy(); reject(new Error(`Medeo did not answer ${op} in ${TIMEOUT_MS / 1000}s`)); }, TIMEOUT_MS);
+    signal?.addEventListener('abort', abort, { once: true });
     socket.setEncoding('utf8');
     socket.on('connect', () => socket.write(JSON.stringify({ protocol: PROTOCOL, op, ...args }) + '\n'));
     socket.on('data', chunk => { buffer += chunk; });
-    socket.on('end', () => { clearTimeout(timer); resolve(buffer); });
-    socket.on('error', error => { clearTimeout(timer); reject(error.code === 'ENOENT' || error.code === 'ECONNREFUSED' ? new Error('Medeo is not listening; is it still running in developer mode?') : error); });
+    socket.on('end', () => { cleanup(); resolve(buffer); });
+    socket.on('error', error => { cleanup(); reject(error.code === 'ENOENT' || error.code === 'ECONNREFUSED' ? new Error('Medeo is not listening; is it still running in developer mode?') : error); });
   });
   const reply = JSON.parse(line);
   if (!reply.ok) throw new Error(reply.error);
@@ -71,7 +77,8 @@ export async function main(args, { defaultId = false } = {}) {
   if (defaultId && ((op === 'logs' || op === 'open' || op === 'stop') && !operands.length || op === 'run' && operands.length === 1)) operands.unshift(await projectId());
   const [first, second] = operands;
   let result;
-  if (op === 'status' && !operands.length) result = await request('status', {}, options);
+  if (op === 'open-center' && !operands.length) result = await request('open-center', {}, options);
+  else if (op === 'status' && !operands.length) result = await request('status', {}, options);
   else if (op === 'logs' && operands.length === 1) result = await request('logs', { id: first, ...(options.since ? { since: options.since } : {}) }, options);
   else if ((op === 'follow' || op === 'reload' || op === 'unfollow') && operands.length === 1)
     result = await request(op === 'unfollow' ? 'unfollow' : 'follow', { file: path.resolve(first) }, options);

package/cli.mjs

@@ -17,6 +17,7 @@ const USAGE = `Usage: medeo-plugin <command>
   keygen KEY.pem                                create a release signing key (keep it outside the project)
   status | logs ID [--since MS] | run ID COMMAND | open ID | stop ID | follow PACKAGE | unfollow PACKAGE
                                                 talk to the running Medeo in developer mode (ID defaults to ./manifest.json)
+  open-center [--channel stg|prd]                open the plugin center (no project required)
   app <the same>                                older spelling of the commands above
 `;
 
@@ -30,7 +31,7 @@ export async function main(argv) {
   else if (command === 'check' && args.length === 1) console.log(JSON.stringify(await (await import('./tooling.mjs')).check(args[0]), null, 2));
   else if (command === 'dev') await (await import('./dev.mjs')).devCommand(args);
   else if (command === 'app') await (await import('./app.mjs')).main(args);
-  else if (['status', 'logs', 'run', 'open', 'stop', 'follow', 'unfollow', 'reload'].includes(command)) await (await import('./app.mjs')).main([command, ...args], { defaultId: true });
+  else if (['status', 'logs', 'run', 'open-center', 'open', 'stop', 'follow', 'unfollow', 'reload'].includes(command)) await (await import('./app.mjs')).main([command, ...args], { defaultId: true });
   else { console.error(USAGE); process.exitCode = 1; }
 }
 // Compared through realpath: npm's bin links and macOS's /var → /private/var both point here.

package/dev.mjs

@@ -39,43 +39,61 @@ export function parseDevArgs(args) {
  * and follows again when Medeo restarts (its watches live in memory).
  */
 export class Follower {
-  constructor(file, { channel, log = console.log, warn = console.error, requestFn = request, locateFn = locate } = {}) {
-    Object.assign(this, { file, channel, log, warn, requestFn, locateFn, pid: null, timer: null, hinted: false, pending: false, stopped: false });
+  constructor(file, { channel, log = console.log, warn = console.error, requestFn = request, locateFn = locate, retryMs = RETRY_MS } = {}) {
+    Object.assign(this, { file, channel, log, warn, requestFn, locateFn, retryMs, controller: new AbortController(), refused: false, pid: null, timer: null, hinted: false, pending: false, stopped: false });
   }
   async load() {
+    if (this.stopped) return;
+    if (this.inFlight) { this.reloadRequested = true; return this.inFlight; }
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.inFlight = (async () => {
+      do { this.reloadRequested = false; await this.loadOnce(); }
+      while (this.reloadRequested && !this.stopped);
+    })();
+    try { await this.inFlight; } finally { this.inFlight = null; }
+  }
+  async loadOnce() {
     if (this.stopped) return;
     this.pending = true;
     let control;
     try { control = await this.locateFn({ channel: this.channel }); }
     catch (error) {
+      if (this.stopped) return;
       if (!this.hinted) { this.warn(DEVELOPER_MODE_HINT); this.hinted = true; }
       return this.retry();
     }
+    if (this.stopped) return;
     try {
-      const result = await this.requestFn('follow', { file: this.file }, { control });
+      const result = await this.requestFn('follow', { file: this.file }, { control, signal: this.controller.signal });
+      if (this.stopped) return;
+      this.refused = Boolean(result?.error);
       this.pid = control.pid; this.hinted = false; this.pending = false;
       if (result?.error) this.warn(JSON.stringify({ event: 'medeo_refused', error: result.error, version: result.version ?? null }));
       else this.log(JSON.stringify({ event: 'medeo_loaded', version: result?.version ?? null, channel: control.channel }));
+      this.retry();
     } catch (error) {
+      if (this.stopped) return;
       this.warn(JSON.stringify({ event: 'medeo_unreachable', error: error.message }));
       this.retry();
     }
   }
   retry() {
     if (this.stopped || this.timer) return;
-    this.timer = setTimeout(() => { this.timer = null; void this.check(); }, RETRY_MS);
+    this.timer = setTimeout(() => { this.timer = null; void this.check(); }, this.retryMs);
     this.timer.unref?.();
   }
   /** Reloads when a load is still owed or Medeo was restarted since the last one. */
   async check() {
     if (this.stopped) return;
+    if (this.inFlight) { this.retry(); return; }
     if (this.pending) return this.load();
     const control = await this.locateFn({ channel: this.channel }).catch(() => null);
     if (control && control.pid !== this.pid) return this.load();
     if (!control) this.pending = true;
     this.retry();
   }
-  stop() { this.stopped = true; if (this.timer) clearTimeout(this.timer); this.timer = null; }
+  stop() { this.stopped = true; this.controller.abort(); if (this.timer) clearTimeout(this.timer); this.timer = null; }
 }
 
 export async function devCommand(args) {
@@ -92,7 +110,10 @@ export async function devCommand(args) {
     console.error(`Building ${manifest.id} from ${source}\n  key     ${key}\n  package ${output}${options.once ? '' : '\n  watching for changes (Ctrl-C to stop)'}`);
     await develop(source, key, output, { once: options.once, signal: controller.signal, onBuild: () => follower?.load() });
     // `--once` returns after the build; give the follow a chance to finish.
-    if (options.once && follower) { while (follower.pending && !follower.stopped) await new Promise(r => setTimeout(r, 200)); }
+    if (options.once && follower) {
+      while (follower.pending && !follower.stopped) await new Promise(r => setTimeout(r, 200));
+      if (follower.refused) process.exitCode = 2;
+    }
   } finally {
     process.removeListener('SIGINT', stop); process.removeListener('SIGTERM', stop);
     follower?.stop();

package/locate.mjs

@@ -3,7 +3,7 @@
 // in this repository they are read from the checkout, so tests and the release
 // script need no staging step.
 import { createRequire } from 'node:module';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -21,17 +21,44 @@ export function templatePath(name) {
   for (const candidate of [path.join(repo, TEMPLATES[name]), path.join(here, 'templates', name)]) if (existsSync(candidate)) return candidate;
   throw new Error(`Template "${name}" is missing from this installation`);
 }
-/** The `@medeo-plugin/sdk` entry esbuild bundles for a plugin in `source`:
- * the plugin's own dependency first (so a project pins its SDK), then the CLI's. */
-export function sdkEntry(source) {
+const SDK_ENTRIES = { '@medeo-plugin/sdk': 'index', '@medeo-plugin/sdk/ui': 'ui', '@medeo-plugin/sdk/ui/react': 'react', '@medeo-plugin/sdk/rpc': 'rpc', '@medeo-plugin/sdk/testing': 'testing' };
+/** Resolve only public, known entry points. Select the project's SDK package once:
+ * a missing export in its pinned version must not fall back to a different SDK. */
+export function sdkEntry(source, specifier = '@medeo-plugin/sdk') {
+  if (!Object.hasOwn(SDK_ENTRIES, specifier)) throw new Error(`Unsupported SDK entry: ${specifier}`);
   const candidates = [];
   for (const from of [path.join(source, 'package.json'), import.meta.url]) {
-    try { candidates.push(path.dirname(createRequire(from).resolve('@medeo-plugin/sdk/package.json'))); } catch {}
+    // Reading package metadata must work even when package.json itself is not
+    // exported. Public entry permissions are checked below before choosing code.
+    const roots = createRequire(from).resolve.paths('@medeo-plugin/sdk') ?? [];
+    const installed = roots.map(root => path.join(root, '@medeo-plugin/sdk')).find(dir => existsSync(path.join(dir, 'package.json')));
+    if (installed) candidates.push(installed);
   }
   candidates.push(path.join(repo, 'packages/plugin-sdk'));
-  for (const dir of candidates) {
-    // The source ships inside the package; esbuild reads TypeScript directly.
-    for (const entry of ['src/index.ts', 'dist/index.js']) if (existsSync(path.join(dir, entry))) return path.join(dir, entry);
+  const dir = candidates.find(dir => existsSync(path.join(dir, 'package.json')));
+  if (!dir) throw new Error('@medeo-plugin/sdk was not found; run npm install in the plugin project');
+  const manifest = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  const subpath = specifier === '@medeo-plugin/sdk' ? '.' : '.' + specifier.slice('@medeo-plugin/sdk'.length);
+  const exported = manifest.exports?.[subpath];
+  if (!exported) throw new Error(`${specifier} is not exported by the plugin's SDK (${manifest.version}); update its dependency`);
+  const target = typeof exported === 'string' ? exported : exported.import ?? exported.default;
+  const name = SDK_ENTRIES[specifier];
+  // Source is shipped for bundling; dist-only installations work too.
+  for (const entry of [`src/${name}.ts`, ...(typeof target === 'string' && target.startsWith('./') ? [target] : [])]) {
+    const resolved = path.resolve(dir, entry);
+    if (resolved.startsWith(dir + path.sep) && existsSync(resolved)) return resolved;
   }
-  throw new Error('@medeo-plugin/sdk was not found; run npm install in the plugin project');
+  throw new Error(`${specifier} is missing from the plugin's SDK installation`);
+}
+
+/** esbuild aliases match prefixes; an onResolve hook makes subpaths exact and
+ * prevents private paths such as sdk/src/index.ts from escaping exports. */
+export function sdkResolver(source) {
+  const resolved = new Map();
+  return { name: 'medeo-sdk', setup(build) {
+    build.onResolve({ filter: /^@medeo-plugin\/sdk(?:\/.*)?$/ }, args => {
+      if (!resolved.has(args.path)) resolved.set(args.path, sdkEntry(source, args.path));
+      return { path: resolved.get(args.path) };
+    });
+  } };
 }

package/pack.mjs

@@ -4,7 +4,7 @@ import { createHash, createPrivateKey, createPublicKey, sign } from 'node:crypto
 import { readFile, writeFile, mkdir, readdir, lstat, access } from 'node:fs/promises';
 import path from 'node:path';
 import { zip } from './zip.mjs';
-import { sdkEntry } from './locate.mjs';
+import { sdkResolver } from './locate.mjs';
 // Mirrors platform_core::mime_type: the Host refuses anything not listed there.
 // cjs/wasm/node: runtime "node" packages only.
 const TEXT=new Set(['html','js','mjs','cjs','css','json','svg','txt','md']),BINARY=new Set(['png','jpg','jpeg','gif','webp','ico','woff','woff2','ttf','otf','mp3','wav','mp4','webm','wasm','node']);
@@ -47,14 +47,14 @@ export function archive(manifest,files,privateKey){
 export async function pack(directory,keyFile,output,options={}){
  const source=path.resolve(directory),manifest=JSON.parse(await readFile(path.join(source,'manifest.json'),'utf8'));
  const {build}=await import('esbuild');
- const sdk=sdkEntry(source);
+ const sdk=sdkResolver(source);
  // runtime "node": bundled for Node (built-ins stay imports; ESM output gets a
  // `require` for bundled CommonJS dependencies). Native addons and other files
  // the code loads at run time go in `resources/`.
  const node=manifest.runtime==='node',cjs=node&&manifest.worker.endsWith('.cjs');
  const result=await build({entryPoints:[path.join(source,'worker.ts')],bundle:true,write:false,format:cjs?'cjs':'esm',platform:node?'node':'browser',target:node?'node22':'es2022',
   ...(node&&!cjs?{banner:{js:"import{createRequire as __medeoRequire}from'node:module';const require=__medeoRequire(import.meta.url);"}}:{}),
-  alias:{'@medeo-plugin/sdk':sdk},logLevel:'silent',absWorkingDir:source});
+  plugins:[sdk],logLevel:'silent',absWorkingDir:source});
  const files={[manifest.worker]:Buffer.from(result.outputFiles[0].text)};
  async function collect(dir,prefix){for(const item of await readdir(dir)){const full=path.join(dir,item),stat=await lstat(full);if(stat.isSymbolicLink())throw Error('Symlinks are not permitted');const relative=prefix+item;if(stat.isDirectory())await collect(full,relative+'/');else {if(stat.size>LIMITS.size)throw Error('File too large');const kind=assetKind(relative);if(!kind)throw Error('Unsupported asset type: '+relative);files[relative]=kind==='binary'?await readFile(full):Buffer.from((await readFile(full,'utf8')).replace(/\r\n/g,'\n'))}}}
  // ui/ also holds the pages of app_windows windows, so it is packed even without a primary window.
@@ -65,7 +65,7 @@ export async function pack(directory,keyFile,output,options={}){
   if(entries.length>1)throw Error('Keep one UI entry: ui/entry.ts or ui/entry.tsx');
   if(entries.length){
    // Imported .css files arrive as text, so a shared module can inject its own styles.
-   const ui=await build({entryPoints:[path.join(source,entries[0])],bundle:true,write:false,format:'esm',platform:'browser',loader:{'.css':'text'},jsx:'automatic',alias:{'@medeo-plugin/sdk':sdk},target:'es2022',logLevel:'silent',absWorkingDir:source});
+   const ui=await build({entryPoints:[path.join(source,entries[0])],bundle:true,write:false,format:'esm',platform:'browser',loader:{'.css':'text'},jsx:'automatic',plugins:[sdk],target:'es2022',logLevel:'silent',absWorkingDir:source});
    files['ui/index.js']=Buffer.from(ui.outputFiles[0].text);delete files[entries[0]];
   }
  }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medeo-plugin/cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Command line for Medeo desktop plugins: scaffold, build, sign, check and live-reload a plugin in a running Medeo.",
   "license": "MIT",
   "repository": {
@@ -40,7 +40,7 @@
     "prepack": "node ../../scripts/stage-cli.mjs"
   },
   "dependencies": {
-    "@medeo-plugin/sdk": "0.7.0",
+    "@medeo-plugin/sdk": "0.8.0",
     "esbuild": "^0.25.0"
   },
   "engines": {

package/templates/react/src/ui/App.tsx

@@ -1,10 +1,12 @@
 import { useEffect, useState } from 'react';
 import { commands, i18n, storage } from '@medeo-plugin/sdk';
+import { Card, Pill, EmptyState, useUIStyles } from '@medeo-plugin/sdk/ui/react';
 
 interface Copy { title: string; count: string; increment: string }
 
 /** Reads the counter and the plugin's own wording; the worker's command changes the counter. */
 export function App() {
+  useUIStyles();
   const [count, setCount] = useState<number | null>(null);
   const [copy, setCopy] = useState<Copy | null>(null);
   const [error, setError] = useState('');
@@ -19,8 +21,9 @@ export function App() {
     setCount(current);
   }
   useEffect(() => {
+    const off = i18n.onDidChangeLocale(() => void load().catch(e => setError(String(e))));
     void load().catch(e => setError(String(e)));
-    return i18n.onDidChangeLocale(() => void load().catch(e => setError(String(e))));
+    return off;
   }, []);
   async function increment() {
     setBusy(true);
@@ -30,11 +33,13 @@ export function App() {
   }
   return (
     <main>
-      <small>Medeo · React</small>
-      <h1 data-testid="drive.react.title">{copy?.title ?? ''}</h1>
-      <output data-testid="drive.react.count" aria-live="polite">{copy?.count ?? ''}</output>
-      <button className="primary" data-testid="drive.react.increment" disabled={busy || count === null} onClick={() => void increment()}>{copy?.increment ?? '+1'}</button>
-      {error && <pre role="alert">{error}</pre>}
+      {copy && <Card title={copy.title} testid="drive.react.card">
+        <output data-testid="drive.react.count" aria-live="polite">
+          <Pill label={copy.count} testid="drive.react.count-pill" />
+        </output>
+        <button className="primary" data-testid="drive.react.increment" disabled={busy || count === null} onClick={() => void increment()}>{copy.increment}</button>
+      </Card>}
+      {error && <div role="alert"><EmptyState title={error} testid="drive.react.error" /></div>}
     </main>
   );
 }

package/templates/react/ui/style.css

@@ -1 +1,3 @@
-main{max-width:560px;margin:auto;padding:32px;display:grid;gap:20px}main small{color:var(--color-schemes-primary)}h1{margin:8px 0}output{font-size:36px}pre{white-space:pre-wrap;font-size:12px;color:var(--color-surface-on-surface-variant)}button{justify-self:start}
+main{max-width:560px;margin:auto;padding:var(--space-s7);display:grid;gap:var(--space-s5)}
+main button{justify-self:start}
+main [role=alert]{overflow-wrap:anywhere}

package/tooling.mjs

@@ -64,8 +64,8 @@ export async function init(directory, id, { template = 'vanilla' } = {}) {
   const name = id.split('.').pop();
   files['package.json'] = JSON.stringify({
     name, version: '1.0.0', private: true, type: 'module',
-    medeo: { plugin: `dist/${id}-1.0.0.medeoplugin` },
-    scripts: { dev: 'medeo-plugin dev', pack: 'medeo-plugin pack --key ../' + name + '-release-key.pem', check: `medeo-plugin check dist/${id}-1.0.0.medeoplugin`, typecheck: 'tsc -p tsconfig.json', test: 'node --test tests/*.test.mjs' },
+    medeo: { plugin: `dist/${id}.medeoplugin` },
+    scripts: { dev: 'medeo-plugin dev', pack: 'medeo-plugin pack --key ../' + name + `-release-key.pem --out dist/${id}.medeoplugin`, check: `medeo-plugin check dist/${id}.medeoplugin`, typecheck: 'tsc -p tsconfig.json', test: 'node --test tests/*.test.mjs' },
     devDependencies: { '@medeo-plugin/sdk': `^${PACKAGE_VERSION}`, '@medeo-plugin/cli': `^${PACKAGE_VERSION}`, typescript: '^5.6.0', '@types/node': '^22.0.0',
       ...(react ? { react: '^19.0.0', 'react-dom': '^19.0.0', '@types/react': '^19.0.0', '@types/react-dom': '^19.0.0' } : {}) },
   }, null, 2) + '\n';
@@ -123,8 +123,11 @@ export async function develop(directory, key, output, { once = false, signal, on
   if (destination.startsWith(source + path.sep) || path.resolve(key).startsWith(source + path.sep)) throw new Error('Keep the output and signing key outside the source directory');
   await mkdir(path.dirname(destination), { recursive: true });
   const temporary = destination + `.pending-${process.pid}`;
-  let previous = '', building = false, again = false;
+  if (signal?.aborted) return;
+  let previous = '', building = false, again = false, stopped = false, active;
+  let timer = null;
   const build = async () => {
+    if (stopped || signal?.aborted) return;
     if (building) { again = true; return; }
     building = true;
     try {
@@ -134,6 +137,7 @@ export async function develop(directory, key, output, { once = false, signal, on
           await pack(source, key, temporary, { development: true });
           // Invalid builds never replace the last installable package.
           const info = await check(temporary);
+          if (stopped || signal?.aborted) return;
           if (info.digest !== previous) {
             await rename(temporary, destination);
             previous = info.digest;
@@ -146,25 +150,35 @@ export async function develop(directory, key, output, { once = false, signal, on
           if (message !== previous) console.error(message);
           previous = message;
         } finally { await rm(temporary, { force: true }); }
-      } while (again);
+      } while (again && !stopped && !signal?.aborted);
     } finally { building = false; }
   };
-  await build();
-  if (once) return;
-  // Changes arrive in bursts (editors write several files, build tools rewrite
-  // directories); one rebuild 150 ms after the last change covers them all.
-  let timer = null;
+  if (once) { await build(); return; }
+  // Watch before the initial build: confirmation dialogs may take minutes.
   const IGNORED = new Set(['node_modules', '.git', 'dist']);
+  let resolveStopped;
+  const finished = new Promise(resolve => { resolveStopped = resolve; });
   const watcher = watch(source, { recursive: true }, (_event, name) => {
     const top = name?.toString().split(/[\\/]/)[0];
     if (top && IGNORED.has(top)) return;
+    if (building) again = true;
     if (timer) clearTimeout(timer);
-    timer = setTimeout(() => { timer = null; void build(); }, 150);
-  });
-  await new Promise(resolve => {
-    const stop = () => { watcher.close(); if (timer) clearTimeout(timer); resolve(); };
-    watcher.on('error', stop);
-    if (signal?.aborted) stop(); else signal?.addEventListener('abort', stop, { once: true });
-    if (!signal) { process.once('SIGINT', stop); process.once('SIGTERM', stop); }
+    timer = setTimeout(() => { timer = null; if (building) again = true; else active = build(); }, 150);
   });
+  const stop = () => { stopped = true; watcher.close(); if (timer) clearTimeout(timer); resolveStopped(); };
+  watcher.on('error', error => { resolveStopped(error); stop(); });
+  signal?.addEventListener('abort', stop, { once: true });
+  if (!signal) { process.once('SIGINT', stop); process.once('SIGTERM', stop); }
+  try {
+    if (signal?.aborted) stop();
+    active = build();
+    await active;
+    const watchError = await finished;
+    if (watchError) throw watchError;
+  } finally {
+    stop();
+    signal?.removeEventListener('abort', stop);
+    process.removeListener('SIGINT', stop); process.removeListener('SIGTERM', stop);
+    await active;
+  }
 }