@medeo-plugin/cli 0.0.0-stage → 0.8.0

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @medeo-plugin/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`medeo-plugin` builds, signs, checks and live-reloads [Medeo desktop plugins](https://github.com/one2x-ai/medeo-desktop-plugin-sdk).
+
+```sh
+npm create medeo-plugin@latest my-plugin -- --id com.example.my-plugin
+cd my-plugin && npm install
+npm run dev            # build on every change and load it into a Medeo in developer mode
+```
+
+| Command | What it does |
+| --- | --- |
+| `medeo-plugin init DIR --id ID [--template vanilla\|react]` | Scaffold a project (also `npm create medeo-plugin`) |
+| `medeo-plugin dev [DIR] [--once] [--no-follow] [--channel stg\|prd]` | Rebuild a signed development package on change and have Medeo load it |
+| `medeo-plugin pack [DIR] --key KEY.pem [--out FILE]` | Build and sign a release package |
+| `medeo-plugin check PACKAGE` | Verify a package with Medeo's own rules (bundled WebAssembly verifier) |
+| `medeo-plugin keygen KEY.pem` | Create a release signing key (keep it outside the project) |
+| `medeo-plugin status \| logs \| run \| open \| stop [ID …]` | Talk to the running Medeo's developer channel |
+
+Development builds are signed with a per-machine key in `~/.medeo/plugin-dev/dev-key.pem`; releases use your own key.

package/app.mjs

@@ -0,0 +1,91 @@
+import { connect } from 'node:net';
+import { readdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+// Talks to a Medeo started with MEDEO_PLUGIN_DEV=1 (its developer-mode control
+// channel): what it did with a development build, its logs, reloads and commands.
+// Medeo writes <app data>/medeo-desktop-electron-<channel>/plugin-dev/control.json
+// naming a socket only this user can open. MEDEO_PLUGIN_DEV_CONTROL names one directly.
+export const PROTOCOL = 1;
+const TIMEOUT_MS = 60_000;
+
+function appData() {
+  if (process.platform === 'darwin') return path.join(homedir(), 'Library/Application Support');
+  if (process.platform === 'win32') return process.env.APPDATA ?? path.join(homedir(), 'AppData/Roaming');
+  return process.env.XDG_CONFIG_HOME ?? path.join(homedir(), '.config');
+}
+const alive = pid => { try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } };
+
+/** The running Medeo to talk to; `channel` picks one when STG and a local build both run. */
+export async function locate({ channel } = {}) {
+  const read = async file => JSON.parse(await readFile(file, 'utf8'));
+  if (process.env.MEDEO_PLUGIN_DEV_CONTROL) return read(process.env.MEDEO_PLUGIN_DEV_CONTROL);
+  const root = appData();
+  const names = (await readdir(root).catch(() => [])).filter(n => n.startsWith('medeo-desktop-electron-'));
+  const found = [];
+  for (const name of names) {
+    const control = await read(path.join(root, name, 'plugin-dev/control.json')).catch(() => null);
+    if (control && alive(control.pid) && (!channel || control.channel === channel)) found.push(control);
+  }
+  if (found.length === 1) return found[0];
+  if (!found.length) throw new Error('No Medeo in developer mode is running. Turn on Developer mode on the Developers page of the plugin center, or start Medeo with MEDEO_PLUGIN_DEV=1' + (channel ? ` (channel ${channel})` : ''));
+  throw new Error(`Several Medeo apps are in developer mode (${found.map(c => c.channel).join(', ')}); pass --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 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', () => { 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);
+  return reply.result;
+}
+
+/** `cli.mjs app …`: prints the reply as JSON, the form a coding agent reads. */
+/** The plugin ID of the project in the current directory, for the direct commands (`medeo-plugin logs`). */
+async function projectId() {
+  try { return JSON.parse(await readFile(path.join(process.cwd(), 'manifest.json'), 'utf8')).id; }
+  catch { throw new Error('Pass the plugin ID, or run this inside a plugin project (no manifest.json here)'); }
+}
+export async function main(args, { defaultId = false } = {}) {
+  const options = {};
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--channel') options.channel = args[++i];
+    else if (args[i] === '--since') options.since = Number(args[++i]);
+    else rest.push(args[i]);
+  }
+  const [op, ...operands] = rest;
+  // `medeo-plugin logs` / `run COMMAND` / `open` / `stop` inside a project name the plugin themselves.
+  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 === '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);
+  else if (op === 'run' && operands.length === 2) result = await request('run', { id: first, command: second }, options);
+  else if ((op === 'open' || op === 'stop') && operands.length === 1) result = await request(op, { id: first }, options);
+  else throw new Error('Usage: medeo-plugin status | logs [ID] [--since MS] | follow PACKAGE | reload PACKAGE | unfollow PACKAGE | run [ID] COMMAND | open [ID] | stop [ID]  [--channel stg|prd]');
+  console.log(JSON.stringify(result, null, 2));
+  // A build Medeo refused is a failure the caller should see in the exit code.
+  if ((op === 'follow' || op === 'reload') && result?.error) process.exitCode = 2;
+}

package/cli.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// `medeo-plugin`: scaffold, build, sign, check and live-reload Medeo desktop plugins.
+import { generateKeyPairSync } from 'node:crypto';
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+export { pack } from './pack.mjs';
+
+const USAGE = `Usage: medeo-plugin <command>
+
+  init DIR --id ID [--template vanilla|react]   scaffold a plugin project (also: npm create medeo-plugin)
+  dev [DIR] [--once] [--no-follow] [--key K] [--out F] [--channel stg|prd]
+                                                build a signed development package on every change and load it into Medeo
+  pack [DIR] --key KEY.pem [--out FILE]         build and sign a release package (default dist/<id>-<version>.medeoplugin)
+  check PACKAGE                                 verify a package with Medeo's rules; prints its manifest, publisher and digest
+  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
+`;
+
+export async function main(argv) {
+  const [command, ...args] = argv;
+  if (command === 'keygen' && args.length === 1) {
+    const { privateKey } = generateKeyPairSync('ed25519');
+    await writeFile(args[0], privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600, flag: 'wx' });
+  } else if (command === 'pack') console.error(await (await import('./pack.mjs')).packCommand(args));
+  else if (command === 'init') await (await import('./tooling.mjs')).initCommand(args);
+  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-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.
+const invoked = p => { try { return realpathSync(p); } catch { return path.resolve(p); } };
+if (process.argv[1] && invoked(process.argv[1]) === invoked(fileURLToPath(import.meta.url))) {
+  await main(process.argv.slice(2)).catch(error => { console.error(error.message); process.exitCode = process.exitCode || 1; });
+}

package/dev.mjs

@@ -0,0 +1,121 @@
+// `medeo-plugin dev [DIR]`: one command for the whole loop. Builds a signed
+// development package whenever the source changes and asks the running Medeo
+// (developer mode) to load it. Nothing here bypasses Medeo: a new plugin or
+// changed permissions still wait for the user's confirmation in Medeo's dialog.
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { develop } from './tooling.mjs';
+import { ensureDevKey, devBuildPath } from './keys.mjs';
+import { locate, request } from './app.mjs';
+
+const RETRY_MS = 5000;
+export const DEVELOPER_MODE_HINT = 'Medeo is not in developer mode. In Medeo: menu bar icon → Plugin entry → Developers → turn on Developer mode (or start Medeo with MEDEO_PLUGIN_DEV=1). Waiting…';
+
+/** `dev [DIR] [--once] [--no-follow] [--key K] [--out F] [--channel C]`; the older `dev DIR KEY OUT [--once]` still works. */
+export function parseDevArgs(args) {
+  const options = { directory: process.cwd(), key: null, output: null, channel: undefined, once: false, follow: true };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--once') options.once = true;
+    else if (arg === '--no-follow') options.follow = false;
+    else if (arg === '--key' || arg === '--out' || arg === '--channel') {
+      const value = args[++i];
+      if (value === undefined || value.startsWith('--')) throw new Error(`${arg} needs a value`);
+      options[arg === '--key' ? 'key' : arg === '--out' ? 'output' : 'channel'] = value;
+    }
+    else if (arg.startsWith('--')) throw new Error(`Unknown option ${arg}`);
+    else positional.push(arg);
+  }
+  if (positional.length === 3 && !options.key && !options.output) { [options.directory, options.key, options.output] = positional; options.follow = false; }
+  else if (positional.length === 1) options.directory = positional[0];
+  else if (positional.length) throw new Error('Usage: medeo-plugin dev [DIR] [--once] [--no-follow] [--key KEY.pem] [--out FILE] [--channel stg|prd]');
+  return options;
+}
+
+/**
+ * Keeps one development package followed by Medeo. `load()` after each build;
+ * the follower retries every 5 s while no Medeo in developer mode is running,
+ * 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, 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, 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(); }, 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; this.controller.abort(); if (this.timer) clearTimeout(this.timer); this.timer = null; }
+}
+
+export async function devCommand(args) {
+  const options = parseDevArgs(args);
+  const source = path.resolve(options.directory);
+  const manifest = JSON.parse(await readFile(path.join(source, 'manifest.json'), 'utf8').catch(() => { throw new Error(`No manifest.json in ${source}; run medeo-plugin dev inside a plugin project or pass its directory`); }));
+  const key = options.key ? path.resolve(options.key) : await ensureDevKey();
+  const output = path.resolve(options.output ?? devBuildPath(manifest.id));
+  const follower = options.follow ? new Follower(output, { channel: options.channel }) : null;
+  const controller = new AbortController();
+  const stop = () => { controller.abort(); follower?.stop(); };
+  process.once('SIGINT', stop); process.once('SIGTERM', stop);
+  try {
+    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 (follower.refused) process.exitCode = 2;
+    }
+  } finally {
+    process.removeListener('SIGINT', stop); process.removeListener('SIGTERM', stop);
+    follower?.stop();
+  }
+}

package/keys.mjs

@@ -0,0 +1,30 @@
+// The per-machine development key. `dev` signs with it, and so does Medeo's
+// "Install from folder", so a plugin keeps one publisher (and its data) however a
+// development build reaches Medeo. Development packages are never distributed;
+// releases are signed with a key the developer creates (`keygen`).
+import { generateKeyPairSync } from 'node:crypto';
+import { mkdir, writeFile, access, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+/** `~/.medeo` (MEDEO_HOME overrides it, for tests and unusual setups). */
+export function medeoHome() { return process.env.MEDEO_HOME || path.join(homedir(), '.medeo'); }
+export function devDirectory() { return path.join(medeoHome(), 'plugin-dev'); }
+export function devKeyPath() { return path.join(devDirectory(), 'dev-key.pem'); }
+/** Where `dev` writes its packages: `~/.medeo/plugin-dev/builds/<id>.medeoplugin`. */
+export function devBuildPath(id) { return path.join(devDirectory(), 'builds', `${id}.medeoplugin`); }
+
+/** Creates the development key on first use (0600, directory 0700) and returns its path. */
+export async function ensureDevKey() {
+  const file = devKeyPath();
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  if (await access(file).then(() => true, () => false)) return file;
+  const { privateKey } = generateKeyPairSync('ed25519');
+  try {
+    await writeFile(file, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600, flag: 'wx' });
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error; // another process won the race; its key is as good
+  }
+  if (process.platform !== 'win32') await chmod(file, 0o600).catch(() => {});
+  return file;
+}

package/locate.mjs

@@ -0,0 +1,64 @@
+// Where the CLI finds its own files. Installed from npm, the verifier and the
+// templates sit inside the package (`scripts/stage-cli.mjs` puts them there);
+// 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, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repo = path.resolve(here, '../..');
+const TEMPLATES = { vanilla: 'examples/i18n-demo', react: 'examples/react-demo' };
+
+export function verifierPath() {
+  // In this repository the checkout's copy is the current one; a published package only has its own.
+  for (const candidate of [path.join(repo, 'verifier/medeo-verify.wasm'), path.join(here, 'verifier/medeo-verify.wasm')]) if (existsSync(candidate)) return candidate;
+  throw new Error('The package verifier (verifier/medeo-verify.wasm) is missing from this installation');
+}
+export function templatePath(name) {
+  if (!Object.hasOwn(TEMPLATES, name)) throw new Error(`Unknown template "${name}"; use ${Object.keys(TEMPLATES).join(' or ')}`);
+  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`);
+}
+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]) {
+    // 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'));
+  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(`${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

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// Built artifacts only: no npm/install hooks ever execute during plugin installation.
+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 { 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']);
+// Already compressed; deflating them only costs time.
+const STORED=new Set(['png','jpg','jpeg','gif','webp','woff','woff2','mp3','mp4','webm']);
+// Mirrors platform_contract: archive and unpacked size, file count, index entry.
+export const LIMITS={size:256*1024*1024,files:4096},INDEX_ENTRY='_package.json';
+// Mirrors platform_core::ICON_PATHS / MAX_ICON / validate_icon.
+export const ICON_PATHS=['icon.svg','icon.png'],MAX_ICON=256*1024;const PNG=Buffer.from([0x89,0x50,0x4e,0x47,0x0d,0x0a,0x1a,0x0a]);
+const UI_ENTRIES=['ui/entry.ts','ui/entry.tsx'];
+function assetKind(file){const ext=file.split('.').pop().toLowerCase();return TEXT.has(ext)?'text':BINARY.has(ext)?'binary':UI_ENTRIES.includes(file)?'text':null}
+const sha256=bytes=>createHash('sha256').update(bytes).digest('hex');
+
+/** JSON with object keys sorted at every level: the same text Medeo's Host produces for the same manifest. */
+export function canonicalJSON(value){
+ if(Array.isArray(value))return '['+value.map(canonicalJSON).join(',')+']';
+ if(value&&typeof value==='object')return '{'+Object.keys(value).sort().map(k=>JSON.stringify(k)+':'+canonicalJSON(value[k])).join(',')+'}';
+ return JSON.stringify(value);
+}
+/** `x.y.z-dev.h<16 hex>` from the manifest and every file; identical content gives an identical version, here and in Medeo's "Install from folder". */
+export function developmentVersion(manifest,files){
+ const hash=createHash('sha256').update(canonicalJSON(manifest));
+ for(const p of Object.keys(files).sort())hash.update(p).update(sha256(files[p]));
+ return manifest.version.split(/[-+]/)[0]+`-dev.h${hash.digest('hex').slice(0,16)}`;
+}
+/** Signs `files` (path → Buffer) with `manifest` into a format-2 archive: `{bytes, digest}`. */
+export function archive(manifest,files,privateKey){
+ if(privateKey.asymmetricKeyType!=='ed25519')throw Error('An Ed25519 key is required');
+ const paths=Object.keys(files).sort();
+ if(paths.length>LIMITS.files)throw Error('Too many files');
+ if(paths.reduce((total,p)=>total+files[p].length,0)>LIMITS.size)throw Error('Package too large');
+ const index=JSON.stringify({manifest,files:Object.fromEntries(paths.map(p=>[p,{size:files[p].length,sha256:sha256(files[p])}]))});
+ const der=createPublicKey(privateKey).export({type:'spki',format:'der'});
+ const signed=JSON.stringify({format:2,public_key:der.subarray(-32).toString('hex'),signature:sign(null,Buffer.from(index),privateKey).toString('hex'),index});
+ const bytes=zip([{name:INDEX_ENTRY,data:Buffer.from(signed),compress:true},...paths.map(p=>({name:p,data:files[p],compress:!STORED.has(p.split('.').pop().toLowerCase())}))]);
+ if(bytes.length>LIMITS.size)throw Error('Package too large');
+ return {bytes,digest:sha256(index)};
+}
+
+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=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);"}}:{}),
+  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.
+ if(manifest.ui||await access(path.join(source,'ui')).then(()=>true,()=>false)){
+  await collect(path.join(source,'ui'),'ui/');
+  // ui/entry.ts or ui/entry.tsx (React and other JSX, automatic runtime) is the one compiled UI entry.
+  const entries=UI_ENTRIES.filter(e=>e in files);
+  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',plugins:[sdk],target:'es2022',logLevel:'silent',absWorkingDir:source});
+   files['ui/index.js']=Buffer.from(ui.outputFiles[0].text);delete files[entries[0]];
+  }
+ }
+ // The icon sits at the package root (`icon.svg` or `icon.png`), checked as Medeo will.
+ if(manifest.icon!==undefined){
+  if(!ICON_PATHS.includes(manifest.icon))throw Error('icon must be icon.svg or icon.png');
+  const full=path.join(source,manifest.icon),stat=await lstat(full).catch(()=>null);
+  if(!stat?.isFile()||stat.size>MAX_ICON)throw Error('Missing icon file or larger than 256 KiB: '+manifest.icon);
+  const bytes=await readFile(full);
+  if(manifest.icon==='icon.png'?!bytes.subarray(0,8).equals(PNG):!bytes.toString('utf8').includes('<svg'))throw Error('icon does not match its type: '+manifest.icon);
+  files[manifest.icon]=bytes;
+ }
+ if(node&&await access(path.join(source,'resources')).then(()=>true,()=>false))await collect(path.join(source,'resources'),'resources/');
+ if(manifest.localization){
+  for(const relative of Object.values(manifest.localization.catalogs??{})){
+   if(typeof relative!=='string'||!/^locales\/[A-Za-z0-9_-]+\.json$/.test(relative))throw Error('Invalid catalog path');
+   const directory=path.join(source,'locales');if((await lstat(directory)).isSymbolicLink())throw Error('Symlinks are not permitted');
+   const full=path.join(source,relative),stat=await lstat(full);if(!stat.isFile()||stat.isSymbolicLink()||stat.size>256*1024)throw Error('Invalid catalog file');files[relative]=await readFile(full);
+  }
+ }
+ if(options.development)manifest.version=developmentVersion(manifest,files);
+ const {bytes}=archive(manifest,files,createPrivateKey(await readFile(keyFile)));
+ await mkdir(path.dirname(path.resolve(output)),{recursive:true});await writeFile(output,bytes);
+}
+
+/** `medeo-plugin pack [DIR] --key KEY.pem [--out FILE]` (or the older `pack DIR KEY.pem OUT`). Returns the output path. */
+export async function packCommand(args){
+ const positional=[];let key,out;
+ for(let i=0;i<args.length;i++){const a=args[i];if(a==='--key')key=args[++i];else if(a==='--out')out=args[++i];else if(a.startsWith('--'))throw Error(`Unknown option ${a}`);else positional.push(a)}
+ if(positional.length===3&&!key&&!out)[,key,out]=positional;
+ else if(positional.length>1)throw Error('Usage: medeo-plugin pack [DIR] --key KEY.pem [--out FILE.medeoplugin]');
+ const directory=path.resolve(positional[0]??'.');
+ if(!key)throw Error('A signing key is required: --key KEY.pem (create one with `medeo-plugin keygen`). For development builds use `medeo-plugin dev`, which signs with the development key');
+ if(!out){const m=JSON.parse(await readFile(path.join(directory,'manifest.json'),'utf8'));out=path.join(directory,'dist',`${m.id}-${m.version}.medeoplugin`)}
+ await pack(directory,key,out);
+ return path.resolve(out);
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@medeo-plugin/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/one2x-ai/medeo-desktop-plugin-sdk.git",
+    "directory": "packages/plugin-devtools"
+  },
+  "homepage": "https://github.com/one2x-ai/medeo-desktop-plugin-sdk#readme",
+  "keywords": [
+    "medeo",
+    "plugin",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "medeo-plugin": "./cli.mjs"
+  },
+  "exports": {
+    ".": "./cli.mjs",
+    "./pack": "./pack.mjs",
+    "./tooling": "./tooling.mjs",
+    "./app": "./app.mjs",
+    "./dev": "./dev.mjs",
+    "./keys": "./keys.mjs",
+    "./zip": "./zip.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "*.mjs",
+    "!*.test.mjs",
+    "verifier/",
+    "templates/",
+    "README.md"
+  ],
+  "scripts": {
+    "stage": "node ../../scripts/stage-cli.mjs",
+    "prepack": "node ../../scripts/stage-cli.mjs"
+  },
+  "dependencies": {
+    "@medeo-plugin/sdk": "0.8.0",
+    "esbuild": "^0.25.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/templates/react/README.md

@@ -0,0 +1,4 @@
+# React counter
+
+The `init --template react` template: the same counter as `i18n-demo`, with the window written in React.
+`ui/entry.tsx` is the only compiled UI entry; components live in `src/ui/` so nothing unbuilt is packaged.

package/templates/react/icon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#7d8bff"/>
+      <stop offset="1" stop-color="#4b50e0"/>
+    </linearGradient>
+  </defs>
+  <rect width="256" height="256" fill="url(#bg)"/>
+  <circle cx="200" cy="52" r="70" fill="#ffffff" opacity="0.08"/>
+  <rect x="52" y="64" width="96" height="76" rx="18" fill="#ffffff"/>
+  <path d="M76 140v26l26-26z" fill="#ffffff"/>
+  <text x="100" y="117" text-anchor="middle" font-family="Helvetica, Arial, sans-serif" font-size="44" font-weight="700" fill="#4b50e0">A</text>
+  <rect x="112" y="112" width="96" height="76" rx="18" fill="#ffffff" opacity="0.92"/>
+  <path d="M184 188v26l-26-26z" fill="#ffffff" opacity="0.92"/>
+  <text x="160" y="166" text-anchor="middle" font-family="PingFang SC, Hiragino Sans GB, sans-serif" font-size="42" font-weight="700" fill="#4b50e0">文</text>
+</svg>

package/templates/react/locales/en.json

@@ -0,0 +1,7 @@
+{
+  "plugin.name": "React counter",
+  "plugin.description": "The counter, written in React: a window, a command and storage.",
+  "count": "Count: {count}",
+  "increment": "+1",
+  "command.counter.increment": "Increment"
+}

package/templates/react/locales/zh-CN.json

@@ -0,0 +1,7 @@
+{
+  "plugin.name": "React 计数器",
+  "plugin.description": "用 React 写的计数器：一个窗口、一条命令、一份存储。",
+  "count": "计数：{count}",
+  "increment": "+1",
+  "command.counter.increment": "加一"
+}

package/templates/react/manifest.json

@@ -0,0 +1,26 @@
+{
+  "id": "app.medeo.react-demo",
+  "name": "React counter",
+  "description": "The counter, written in React: a window, a command and storage.",
+  "icon": "icon.svg",
+  "version": "1.0.0",
+  "api_version": 1,
+  "worker": "worker.js",
+  "ui": "ui/index.html",
+  "permissions": [
+    "storage"
+  ],
+  "commands": [
+    {
+      "id": "counter.increment",
+      "title": "Increment"
+    }
+  ],
+  "localization": {
+    "default_locale": "en",
+    "catalogs": {
+      "en": "locales/en.json",
+      "zh-CN": "locales/zh-CN.json"
+    }
+  }
+}

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

@@ -0,0 +1,45 @@
+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('');
+  const [busy, setBusy] = useState(false);
+  async function load() {
+    const [state, value] = await Promise.all([i18n.state(), storage.get<number>('counter')]);
+    const current = value ?? 0;
+    const [countText, increment] = await Promise.all([i18n.t('count', { count: current }), i18n.t('increment')]);
+    document.documentElement.lang = state.catalog_locale ?? state.locale;
+    document.title = state.name;
+    setCopy({ title: state.name, count: countText, increment });
+    setCount(current);
+  }
+  useEffect(() => {
+    const off = i18n.onDidChangeLocale(() => void load().catch(e => setError(String(e))));
+    void load().catch(e => setError(String(e)));
+    return off;
+  }, []);
+  async function increment() {
+    setBusy(true);
+    try { await commands.run('counter.increment'); await load(); }
+    catch (e) { setError(String(e)); }
+    finally { setBusy(false); }
+  }
+  return (
+    <main>
+      {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/entry.tsx

@@ -0,0 +1,5 @@
+// `pack` bundles this file (and React) into ui/index.js. Components live in
+// src/ui so that only built files are packaged.
+import { createRoot } from 'react-dom/client';
+import { App } from '../src/ui/App.tsx';
+createRoot(document.getElementById('root')!).render(<App />);

package/templates/react/ui/index.html

@@ -0,0 +1 @@
+<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="/_medeo/theme.css"><link rel="stylesheet" href="style.css"><title>Medeo</title></head><body><div id="root"></div><script type="module" src="index.js"></script></body></html>

package/templates/react/ui/style.css

@@ -0,0 +1,3 @@
+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/templates/react/worker.ts

@@ -0,0 +1,12 @@
+import { definePlugin, storage, i18n } from '@medeo-plugin/sdk';
+// The worker owns the data; the window only asks it to act (commands) and reads.
+export const { activate, deactivate } = definePlugin({
+  activate(context) {
+    context.commands.register('counter.increment', async () => {
+      const previous = await storage.get<number>('counter');
+      const count = (typeof previous === 'number' ? previous : 0) + 1;
+      await storage.set('counter', count);
+      return { count, message: await i18n.t('count', { count }) };
+    });
+  },
+});

package/templates/vanilla/icon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#7d8bff"/>
+      <stop offset="1" stop-color="#4b50e0"/>
+    </linearGradient>
+  </defs>
+  <rect width="256" height="256" fill="url(#bg)"/>
+  <circle cx="200" cy="52" r="70" fill="#ffffff" opacity="0.08"/>
+  <rect x="52" y="64" width="96" height="76" rx="18" fill="#ffffff"/>
+  <path d="M76 140v26l26-26z" fill="#ffffff"/>
+  <text x="100" y="117" text-anchor="middle" font-family="Helvetica, Arial, sans-serif" font-size="44" font-weight="700" fill="#4b50e0">A</text>
+  <rect x="112" y="112" width="96" height="76" rx="18" fill="#ffffff" opacity="0.92"/>
+  <path d="M184 188v26l-26-26z" fill="#ffffff" opacity="0.92"/>
+  <text x="160" y="166" text-anchor="middle" font-family="PingFang SC, Hiragino Sans GB, sans-serif" font-size="42" font-weight="700" fill="#4b50e0">文</text>
+</svg>

package/templates/vanilla/locales/de.json

@@ -0,0 +1,8 @@
+{
+  "name_label": "Dein Name",
+  "plugin.name": "Mehrsprachiger Zähler",
+  "plugin.description": "Ein Zähler, der neun Sprachen spricht.",
+  "hello": "Hallo, {name}!",
+  "count": "Zähler: {count}",
+  "command.counter.increment": "Erhöhen"
+}

package/templates/vanilla/locales/en.json

@@ -0,0 +1,8 @@
+{
+  "name_label": "Your name",
+  "plugin.name": "Multilingual counter",
+  "plugin.description": "A counter that speaks nine languages.",
+  "hello": "Hello, {name}!",
+  "count": "Count: {count}",
+  "command.counter.increment": "Increment"
+}

package/templates/vanilla/locales/es.json

@@ -0,0 +1,8 @@
+{
+  "name_label": "Tu nombre",
+  "plugin.name": "Contador multilingüe",
+  "plugin.description": "Un contador que habla nueve idiomas.",
+  "hello": "¡Hola, {name}!",
+  "count": "Recuento: {count}",
+  "command.counter.increment": "Incrementar"
+}

package/templates/vanilla/locales/fr.json

@@ -0,0 +1,8 @@
+{
+  "name_label": "Votre nom",
+  "plugin.name": "Compteur multilingue",
+  "plugin.description": "Un compteur qui parle neuf langues.",
+  "hello": "Bonjour, {name} !",
+  "count": "Compteur : {count}",
+  "command.counter.increment": "Incrémenter"
+}

package/templates/vanilla/locales/ja.json

@@ -0,0 +1,8 @@
+{
+  "name_label": "お名前",
+  "plugin.name": "多言語カウンター",
+  "plugin.description": "9 か国語を話すカウンター。",
+  "hello": "こんにちは、{name}！",
+  "count": "カウント：{count}",
+  "command.counter.increment": "増やす"
+}

package/templates/vanilla/locales/ko.json

@@ -0,0 +1,8 @@
+{
+  "name_label": "이름",
+  "plugin.name": "다국어 카운터",
+  "plugin.description": "9개 언어를 말하는 카운터.",
+  "hello": "안녕하세요, {name}!",
+  "count": "횟수: {count}",
+  "command.counter.increment": "증가"
+}

package/templates/vanilla/locales/pt-BR.json

@@ -0,0 +1,8 @@
+{
+  "name_label": "Seu nome",
+  "plugin.name": "Contador multilíngue",
+  "plugin.description": "Um contador que fala nove idiomas.",
+  "hello": "Olá, {name}!",
+  "count": "Contagem: {count}",
+  "command.counter.increment": "Incrementar"
+}

package/templates/vanilla/locales/zh-CN.json

@@ -0,0 +1,8 @@
+{
+  "name_label": "你的名字",
+  "plugin.name": "多语言计数器",
+  "plugin.description": "一个会说九种语言的计数器。",
+  "hello": "你好，{name}！",
+  "count": "计数：{count}",
+  "command.counter.increment": "加一"
+}

package/templates/vanilla/locales/zh-TW.json

@@ -0,0 +1,8 @@
+{
+  "name_label": "你的名字",
+  "plugin.name": "多語言計數器",
+  "plugin.description": "一個會說九種語言的計數器。",
+  "hello": "你好，{name}！",
+  "count": "計數：{count}",
+  "command.counter.increment": "加一"
+}

package/templates/vanilla/manifest.json

@@ -0,0 +1,33 @@
+{
+  "id": "app.medeo.i18n-demo",
+  "name": "Multilingual counter",
+  "description": "A counter that speaks nine languages.",
+  "icon": "icon.svg",
+  "version": "1.0.0",
+  "api_version": 1,
+  "worker": "worker.js",
+  "ui": "ui/index.html",
+  "permissions": [
+    "storage"
+  ],
+  "commands": [
+    {
+      "id": "counter.increment",
+      "title": "Increment"
+    }
+  ],
+  "localization": {
+    "default_locale": "en",
+    "catalogs": {
+      "en": "locales/en.json",
+      "zh-CN": "locales/zh-CN.json",
+      "zh-TW": "locales/zh-TW.json",
+      "ja": "locales/ja.json",
+      "ko": "locales/ko.json",
+      "pt-BR": "locales/pt-BR.json",
+      "es": "locales/es.json",
+      "de": "locales/de.json",
+      "fr": "locales/fr.json"
+    }
+  }
+}

package/templates/vanilla/ui/entry.ts

@@ -0,0 +1,12 @@
+import {i18n,capabilities,commands,storage} from '@medeo-plugin/sdk';
+const get=<T extends HTMLElement>(key:string)=>document.querySelector<T>(`[data-testid="drive.i18n.${key}"]`)!;
+const language=get<HTMLSelectElement>('language'),name=get<HTMLInputElement>('name'),increment=get<HTMLButtonElement>('increment');let revision=0;
+async function render(){document.body.setAttribute('aria-busy','true');const mine=++revision;const state=await i18n.state();const count=await storage.get<number>('counter')??0;const [hello,text,copy,nameLabel]=await Promise.all([i18n.t('hello',{name:name.value}),i18n.t('count',{count}),capabilities.labels(),i18n.t('name_label')]);if(mine!==revision)return;
+ document.documentElement.lang=state.catalog_locale??state.locale;document.documentElement.dir=state.direction;document.title=state.name;get('title').textContent=state.name;get('hello').textContent=hello;get('name-label').textContent=nameLabel;get('count').textContent=text;get('language-label').textContent=copy.plugin_language;
+ const options=['system',...state.supported_locales];language.replaceChildren(...options.map(value=>{const option=document.createElement('option');option.value=value;option.textContent=copy['language.'+value];return option}));language.value=state.preference;
+ increment.textContent=state.commands['counter.increment'];get('status').textContent=JSON.stringify({locale:state.locale,fallback:state.fallback_locale},null,2);document.body.setAttribute('aria-busy','false');}
+function showError(error:unknown){get('status').textContent=String(error);document.body.setAttribute('aria-busy','false')}
+const unsubscribe=i18n.onDidChangeLocale(()=>void render().catch(showError));window.addEventListener('pagehide',unsubscribe,{once:true});
+language.onchange=()=>{const value=language.value;void i18n.setLocale(value).then(render).catch(showError)};name.oninput=()=>void render().catch(showError);
+increment.onclick=async()=>{increment.disabled=true;try{await commands.run('counter.increment');await render()}catch(e){showError(e)}finally{increment.disabled=false}};
+void render().catch(showError);

package/templates/vanilla/ui/index.html

@@ -0,0 +1 @@
+<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="/_medeo/theme.css"><link rel="stylesheet" href="style.css"><title>Medeo</title></head><body><main><header><small>Medeo · i18n</small><h1 data-testid="drive.i18n.title"></h1></header><label><span data-testid="drive.i18n.language-label"></span><select data-testid="drive.i18n.language"></select></label><label><span data-testid="drive.i18n.name-label"></span><input data-testid="drive.i18n.name" value="Medeo" autocomplete="off"></label><p data-testid="drive.i18n.hello"></p><output data-testid="drive.i18n.count" aria-live="polite"></output><button class="primary" data-testid="drive.i18n.increment"></button><pre data-testid="drive.i18n.status" aria-live="polite"></pre></main><script type="module" src="index.js"></script></body></html>

package/templates/vanilla/ui/style.css

@@ -0,0 +1 @@
+main{max-width:680px;margin:auto;padding:32px;display:grid;gap:20px}header small{color:var(--color-schemes-primary)}h1{margin:8px 0}label{display:grid;gap:8px}input,select{font:inherit;padding:12px;border:1px solid var(--color-surface-outline-variant);border-radius:10px;color:inherit;background:var(--color-surface-surface-container-lowest)}output{font-size:36px}pre{white-space:pre-wrap;font-size:12px;color:var(--color-surface-on-surface-variant)}button{justify-self:start}input:focus-visible,select:focus-visible{outline:2px solid var(--color-schemes-primary);outline-offset:2px}

package/templates/vanilla/worker.ts

@@ -0,0 +1,2 @@
+import {definePlugin,storage,i18n} from '@medeo-plugin/sdk';
+export const {activate,deactivate}=definePlugin({activate(context){context.commands.register('counter.increment',async()=>{const previous=await storage.get<unknown>('counter');const count=(typeof previous==='number'?previous:0)+1;await storage.set('counter',count);return {count,message:await i18n.t('count',{count})}})}});

package/tooling.mjs

@@ -0,0 +1,184 @@
+import { mkdir, readFile, writeFile, rename, rm, access } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { pack } from './pack.mjs';
+import { watch } from 'node:fs';
+import { verifierPath, templatePath } from './locate.mjs';
+
+// The bundled WebAssembly verifier runs the installer's own rules, so checking
+// needs neither Rust nor Medeo. Set MEDEO_PLATFORM_HOST to ask a built Host.
+let verifier;
+export async function inspect(bytes) {
+  verifier ??= (await WebAssembly.instantiate(await readFile(verifierPath()))).instance.exports;
+  const input = verifier.alloc(bytes.length);
+  new Uint8Array(verifier.memory.buffer, input, bytes.length).set(bytes);
+  const packed = BigInt(verifier.inspect_package(input, bytes.length));
+  verifier.dealloc(input, bytes.length);
+  const pointer = Number(packed >> 32n), length = Number(packed & 0xffffffffn);
+  const text = new TextDecoder().decode(new Uint8Array(verifier.memory.buffer, pointer, length));
+  verifier.dealloc(pointer, length);
+  return JSON.parse(text);
+}
+export async function check(file) {
+  const host = process.env.MEDEO_PLATFORM_HOST;
+  if (!host) {
+    const result = await inspect(await readFile(path.resolve(file)));
+    if (!result.ok) throw new Error(result.error);
+    return result.package;
+  }
+  if (!await access(host).then(() => true, () => false)) throw new Error('MEDEO_PLATFORM_HOST does not exist');
+  const result = spawnSync(host, ['--inspect-package', path.resolve(file)], { encoding: 'utf8', timeout: 15_000, maxBuffer: 64 * 1024, windowsHide: true });
+  if (result.error) throw new Error('Package verifier could not run');
+  if (result.status !== 0) throw new Error(result.stderr.trim().replace(/^platform-host: /, '').slice(0, 200) || 'Package verification failed');
+  return JSON.parse(result.stdout);
+}
+
+const PACKAGE_VERSION = JSON.parse(await readFile(new URL('./package.json', import.meta.url), 'utf8')).version;
+const PROJECT_TSCONFIG = {
+  compilerOptions: { target: 'ES2022', module: 'ESNext', moduleResolution: 'Bundler', strict: true, noEmit: true, allowImportingTsExtensions: true,
+    resolveJsonModule: true, skipLibCheck: true, jsx: 'react-jsx', lib: ['ES2022', 'DOM', 'DOM.Iterable'], types: ['node'] },
+  include: ['*.ts', 'ui/**/*.ts', 'ui/**/*.tsx', 'src/**/*.ts', 'src/**/*.tsx', 'tests/**/*.ts'],
+};
+
+/**
+ * A complete plugin project in `directory`: the template's files, a manifest for
+ * `id`, and the `package.json` / `tsconfig.json` that give it the SDK, the CLI
+ * and editor types from npm. `template`: `vanilla` (nine-language counter) or `react`.
+ */
+export async function init(directory, id, { template = 'vanilla' } = {}) {
+  if (!/^[a-z0-9-]+(?:\.[a-z0-9-]+)*$/.test(id) || id.length < 3 || id.length > 96) throw new Error('Invalid plugin ID: lowercase letters, digits, "-" and ".", 3-96 characters, e.g. com.example.my-plugin');
+  const root = path.resolve(directory), source = templatePath(template);
+  const demoManifest = JSON.parse(await readFile(path.join(source, 'manifest.json'), 'utf8'));
+  // Never overwrite an existing project or generate a signing key into its UI assets.
+  await mkdir(root);
+  const manifest = { ...demoManifest, id, name: id, description: 'Describe what this plugin does in one sentence.', version: '1.0.0' };
+  const files = { 'manifest.json': JSON.stringify(manifest, null, 2) + '\n', '.gitignore': '*.pem\n*.medeoplugin\nnode_modules/\ndist/\n' };
+  // A generated app has its own signed catalogs; it does not need host copy edits.
+  for (const relative of Object.values(demoManifest.localization?.catalogs ?? {})) {
+    const catalog = JSON.parse(await readFile(path.join(source, relative), 'utf8'));
+    delete catalog['plugin.name']; delete catalog['plugin.description'];
+    files[relative] = JSON.stringify(catalog, null, 2) + '\n';
+  }
+  await copyTree(source, root, files, ['manifest.json', 'locales', 'README.md', 'tests', 'dist', 'node_modules', 'package.json', 'tsconfig.json']);
+  const react = template === 'react';
+  const name = id.split('.').pop();
+  files['package.json'] = JSON.stringify({
+    name, version: '1.0.0', private: true, type: 'module',
+    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';
+  files['tsconfig.json'] = JSON.stringify(PROJECT_TSCONFIG, null, 2) + '\n';
+  files['README.md'] = `# ${id}\n\nA Medeo desktop plugin.\n\n\`\`\`sh\nnpm install\nnpm run dev        # build on every change and load it into a Medeo in developer mode\nnpm run typecheck\n\`\`\`\n\nRelease: \`medeo-plugin keygen ../${name}-release-key.pem\` once (keep the key outside the project and out of version control; the same key must sign every later version), then \`npm run pack && npm run check\` and install \`dist/*.medeoplugin\` through Medeo's plugin center.\n\nAll wording lives in \`locales/\` and ships signed with the plugin; keep \`{placeholders}\` identical across languages. Replace \`icon.svg\` (or ship \`icon.png\`, 256×256). Docs: https://github.com/one2x-ai/medeo-desktop-plugin-sdk\n`;
+  for (const [relative, content] of Object.entries(files)) {
+    await mkdir(path.dirname(path.join(root, relative)), { recursive: true });
+    await writeFile(path.join(root, relative), content, { flag: 'wx' });
+  }
+  return root;
+}
+async function copyTree(source, root, files, skip) {
+  const { readdir, lstat } = await import('node:fs/promises');
+  const walk = async (dir, prefix) => {
+    for (const item of await readdir(dir)) {
+      if (!prefix && skip.includes(item)) continue;
+      const full = path.join(dir, item), stat = await lstat(full);
+      if (stat.isSymbolicLink()) continue;
+      if (stat.isDirectory()) await walk(full, prefix + item + '/');
+      else files[prefix + item] = await readFile(full);
+    }
+  };
+  await walk(source, '');
+}
+
+/** `medeo-plugin init DIR --id ID [--template vanilla|react]`; asks for the ID on a terminal. */
+export async function initCommand(args) {
+  let directory, id, template = 'vanilla';
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--id') id = args[++i]; else if (a === '--template') template = args[++i];
+    else if (a.startsWith('--')) throw new Error(`Unknown option ${a}`);
+    else if (!directory) directory = a; else if (!id) id = a; else throw new Error(`Unexpected argument ${a}`);
+  }
+  if (!directory) throw new Error('Usage: medeo-plugin init DIR --id com.example.my-plugin [--template vanilla|react]');
+  if (!id && process.stdin.isTTY) {
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try { id = (await rl.question('Plugin ID (reverse domain, e.g. com.example.my-plugin): ')).trim(); } finally { rl.close(); }
+  }
+  if (!id) throw new Error('Pass the plugin ID: --id com.example.my-plugin');
+  const root = await init(directory, id, { template });
+  console.error(`Created ${root}\n\n  cd ${path.relative(process.cwd(), root) || '.'}\n  npm install\n  npm run dev\n`);
+  return root;
+}
+
+/**
+ * Builds a signed development package of `directory` into `output`, then again
+ * whenever a source file changes (`once`: build one and return). A build that
+ * fails to pack or verify never replaces the last good package. `onBuild(info)`
+ * runs after each new package; `signal` stops the watch.
+ */
+export async function develop(directory, key, output, { once = false, signal, onBuild } = {}) {
+  const source = path.resolve(directory), destination = path.resolve(output);
+  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}`;
+  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 {
+      do {
+        again = false;
+        try {
+          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;
+            console.log(JSON.stringify({ event: 'package_ready', id: info.manifest.id, version: info.manifest.version, digest: info.digest, output: destination }));
+            await onBuild?.(info);
+          }
+        } catch (error) {
+          if (once) throw error;
+          const message = String(error);
+          if (message !== previous) console.error(message);
+          previous = message;
+        } finally { await rm(temporary, { force: true }); }
+      } while (again && !stopped && !signal?.aborted);
+    } finally { building = false; }
+  };
+  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; 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;
+  }
+}

package/zip.mjs

@@ -0,0 +1,57 @@
+// Minimal ZIP writer for .medeoplugin archives: stored or deflated entries,
+// UTF-8 names, fixed timestamps (the same input always gives the same bytes),
+// no ZIP64 (packages are far below 4 GiB).
+import { deflateRawSync } from 'node:zlib';
+import * as zlib from 'node:zlib';
+
+let table;
+function crc32(bytes) {
+  if (zlib.crc32) return zlib.crc32(bytes);
+  table ??= Array.from({ length: 256 }, (_, n) => { for (let k = 0; k < 8; k++) n = n & 1 ? 0xedb88320 ^ (n >>> 1) : n >>> 1; return n >>> 0; });
+  let crc = 0xffffffff;
+  for (const byte of bytes) crc = table[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** entries: [{ name, data: Buffer, compress: boolean }] in archive order. */
+export function zip(entries) {
+  const locals = [], centrals = [];
+  let offset = 0;
+  for (const { name, data, compress } of entries) {
+    const deflated = compress ? deflateRawSync(data, { level: 9 }) : null;
+    const method = deflated && deflated.length < data.length ? 8 : 0;
+    const body = method ? deflated : data, nameBytes = Buffer.from(name, 'utf8'), crc = crc32(data);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0); local.writeUInt16LE(20, 4); local.writeUInt16LE(0x0800, 6); local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(0, 10); local.writeUInt16LE(0x21, 12); local.writeUInt32LE(crc, 14); local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(data.length, 22); local.writeUInt16LE(nameBytes.length, 26); local.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(nameBytes.length, 28);
+    central.writeUInt32LE(offset, 42);
+    locals.push(local, nameBytes, body); centrals.push(central, nameBytes);
+    offset += local.length + nameBytes.length + body.length;
+  }
+  const directory = Buffer.concat(centrals), end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0); end.writeUInt16LE(entries.length, 8); end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(directory.length, 12); end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, directory, end]);
+}
+
+/** Entries of an archive this module (or any plain ZIP) wrote: name → Buffer. */
+export function unzip(archive) {
+  const at = archive.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
+  if (at < 0) throw Error('Not a ZIP archive');
+  const count = archive.readUInt16LE(at + 10), entries = new Map();
+  let position = archive.readUInt32LE(at + 16);
+  for (let i = 0; i < count; i++) {
+    const method = archive.readUInt16LE(position + 10), size = archive.readUInt32LE(position + 20);
+    const nameLength = archive.readUInt16LE(position + 28), extra = archive.readUInt16LE(position + 30), comment = archive.readUInt16LE(position + 32);
+    const local = archive.readUInt32LE(position + 42), name = archive.subarray(position + 46, position + 46 + nameLength).toString('utf8');
+    const start = local + 30 + archive.readUInt16LE(local + 26) + archive.readUInt16LE(local + 28), body = archive.subarray(start, start + size);
+    entries.set(name, method === 8 ? zlib.inflateRawSync(body) : Buffer.from(body));
+    position += 46 + nameLength + extra + comment;
+  }
+  return entries;
+}