francois 0.12.0-dev.30

package/README.md

@@ -0,0 +1,63 @@
+# francois
+
+**Mission control for your Claude Code fleet** — installed without an installer.
+
+```sh
+npm i -g francois       # stable
+npm i -g francois@dev   # rolling build of main
+```
+
+Then launch it **from the Start Menu, Launchpad or your applications menu** like
+any other app — or type `francois` in a terminal, whichever you prefer.
+
+This package ships no binaries. Its postinstall downloads the platform build from
+the matching [GitHub release](https://github.com/antoine-gmnz/francois/releases),
+verifies it against a sha256 digest baked in at publish time, and registers it
+with your desktop.
+
+## What gets installed where
+
+| | |
+|---|---|
+| **Windows** | a Start Menu shortcut, plus an entry in Settings → Installed apps |
+| **macOS** | the app bundle in `~/Applications` — Spotlight, Launchpad and the Dock all find it |
+| **Linux** | a `.desktop` launcher and icon under `~/.local/share` |
+
+All per-user: no administrator rights, no elevation prompt. `npm uninstall -g
+francois` removes them again, and `francois shortcut --remove` is the manual
+escape hatch.
+
+## Why install this way
+
+Windows SmartScreen and macOS Gatekeeper key off the Mark-of-the-Web /
+`com.apple.quarantine` attribute that a **browser** attaches at download time.
+Binaries fetched by a CLI never carry one — so the same unsigned build that gets
+blocked when downloaded as a `.dmg` or `.exe` launches clean from here. No
+certificate, no *More info → Run anyway*, no right-click → Open.
+
+## Requirements
+
+- Node 18+
+- [Claude Code](https://claude.com/claude-code) on your `PATH`, authenticated — Francois spawns `claude` per session
+- `git` on your `PATH` — powers the DIFF tab
+- Windows only: the [WebView2 runtime](https://developer.microsoft.com/microsoft-edge/webview2/) (preinstalled on Windows 11 and current Windows 10)
+
+Prebuilt for macOS (universal), Windows x64 and Linux x64. On anything else,
+[build from source](https://github.com/antoine-gmnz/francois#build-from-source).
+
+## Usage
+
+| Command | Effect |
+|---|---|
+| `francois` | launch the app and return to the shell |
+| `francois --attach` | launch it in the foreground with its output attached |
+| `francois --version` | print the app + package versions |
+| `francois shortcut` | re-register the desktop entry (after deleting it, or a headless install) |
+| `francois shortcut --remove` | unregister it |
+| `francois --help` | usage |
+
+Environment: `FRANCOIS_SKIP_DOWNLOAD=1` skips the postinstall download,
+`FRANCOIS_DOWNLOAD_BASE` overrides the release host (mirrors, air-gapped setups).
+
+[Full documentation](https://github.com/antoine-gmnz/francois) ·
+[AGPL-3.0](https://github.com/antoine-gmnz/francois/blob/main/LICENSE)

package/bin/francois.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * `francois` — launch the desktop app that install.js unpacked into vendor/.
+ *
+ * Unrecognised arguments are forwarded to the app binary, so this stays
+ * forward-compatible with the read-only CLI companion (specs/cli-companion.md)
+ * once that ships.
+ */
+
+const { spawn, spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const desktop = require('../lib/desktop.js');
+const {
+  assetKey,
+  readInstallRecord,
+  readManifest,
+  resolveExecutable,
+  supportedList,
+} = require('../lib/platform.js');
+
+const USAGE = `francois — mission control for your Claude Code fleet
+
+Usage
+  francois                     launch the app (returns to the shell immediately)
+  francois --attach            launch it in the foreground, keeping its output attached
+  francois --version           print the app + package versions
+  francois shortcut            re-register the Start Menu / Launchpad / menu entry
+  francois shortcut --remove   unregister it
+  francois --help              this message
+
+Anything else is forwarded to the app.
+`;
+
+function die(message) {
+  process.stderr.write(`\nfrancois: ${message}\n\n`);
+  process.exit(1);
+}
+
+/**
+ * Tauri renders through the system webview, which on Windows means the WebView2
+ * runtime. It ships with Windows 11 and current Windows 10, but a bare machine
+ * can be missing it — and the app then fails with nothing useful on screen.
+ * A warning only: a false negative here must not block a working launch.
+ */
+function warnIfWebView2Missing() {
+  if (process.platform !== 'win32') return;
+  const guid = '{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}';
+  const roots = [
+    `HKLM\\SOFTWARE\\WOW6432Node\\Microsoft\\EdgeUpdate\\Clients\\${guid}`,
+    `HKCU\\SOFTWARE\\Microsoft\\EdgeUpdate\\Clients\\${guid}`,
+  ];
+  const found = roots.some(
+    (key) => spawnSync('reg', ['query', key, '/v', 'pv'], { stdio: 'ignore' }).status === 0,
+  );
+  if (!found) {
+    process.stderr.write(
+      'francois: the Microsoft Edge WebView2 runtime was not found — the window may fail to open.\n' +
+        '          Install it from https://developer.microsoft.com/microsoft-edge/webview2/\n',
+    );
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+
+  if (argv[0] === '--help' || argv[0] === '-h') {
+    process.stdout.write(USAGE);
+    return;
+  }
+
+  if (argv[0] === '--version' || argv[0] === '-v') {
+    const manifest = readManifest();
+    const pkg = require('../package.json');
+    process.stdout.write(`francois ${manifest ? manifest.appVersion : 'unknown'} (npm ${pkg.version})\n`);
+    return;
+  }
+
+  // Re-runnable on demand: a shortcut can be deleted, or the postinstall can have
+  // run somewhere the desktop wasn't reachable (SSH, a container, a CI image).
+  if (argv[0] === 'shortcut') {
+    const record = readInstallRecord();
+    if (!record) die('nothing is installed yet — run `npm i -g francois` first.');
+
+    if (argv.includes('--remove')) {
+      desktop.remove(record);
+      process.stdout.write(`francois: removed the ${record.productName} shortcut.\n`);
+      return;
+    }
+
+    const { notes } = desktop.install(record);
+    for (const note of notes) process.stdout.write(`francois: ${note}\n`);
+    return;
+  }
+
+  const executable = resolveExecutable();
+  if (!executable) {
+    if (!assetKey()) {
+      die(
+        `no prebuilt app for ${process.platform}/${process.arch} (published: ${supportedList()}).\n` +
+          'Build from source: https://github.com/antoine-gmnz/francois#build-from-source',
+      );
+    }
+    die('the app payload is missing — reinstall with `npm i -g francois`.');
+  }
+
+  warnIfWebView2Missing();
+
+  const attach = argv[0] === '--attach';
+  const forwarded = attach ? argv.slice(1) : argv;
+
+  if (attach) {
+    const result = spawnSync(executable, forwarded, { stdio: 'inherit' });
+    process.exit(result.status === null ? 1 : result.status);
+  }
+
+  const child = spawn(executable, forwarded, {
+    detached: true,
+    stdio: 'ignore',
+    cwd: process.cwd(),
+  });
+  child.on('error', (error) => die(`could not launch ${path.basename(executable)}: ${error.message}`));
+  child.unref();
+}
+
+main();

package/install.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * postinstall — fetch this platform's Francois build from its GitHub release and
+ * unpack it into vendor/.
+ *
+ * Why this package exists at all: Windows SmartScreen and macOS Gatekeeper key
+ * off the Mark-of-the-Web / com.apple.quarantine attribute that a *browser*
+ * attaches at download time. A binary fetched by npm never carries one, so the
+ * same unsigned build that gets blocked when downloaded as a .dmg or .exe
+ * launches clean from here — no code-signing certificate involved.
+ *
+ * Dependency-free by necessity: this runs during `npm install`, so nothing but
+ * Node's standard library is available.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const http = require('node:http');
+const https = require('node:https');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const desktop = require('./lib/desktop.js');
+const {
+  VENDOR_DIR,
+  assetKey,
+  readManifest,
+  resolveExecutable,
+  supportedList,
+  writeInstallRecord,
+} = require('./lib/platform.js');
+
+/**
+ * The .app bundle an executable lives in (…/Francois.app/Contents/MacOS/francois
+ * → …/Francois.app), or null on platforms that ship a bare binary.
+ */
+function bundleOf(executable) {
+  const marker = `${path.sep}Contents${path.sep}MacOS${path.sep}`;
+  const at = executable.indexOf(marker);
+  return at === -1 ? null : executable.slice(0, at);
+}
+
+const DOWNLOAD_BASE = process.env.FRANCOIS_DOWNLOAD_BASE || 'https://github.com';
+const MAX_ATTEMPTS = 3;
+const REQUEST_TIMEOUT_MS = 60_000;
+
+function log(message) {
+  process.stdout.write(`francois: ${message}\n`);
+}
+
+function fail(message) {
+  process.stderr.write(`\nfrancois: ${message}\n\n`);
+  process.exit(1);
+}
+
+/**
+ * GitHub redirects release downloads to a CDN, so redirects must be followed.
+ * http is honoured alongside https only so that a self-hosted
+ * FRANCOIS_DOWNLOAD_BASE works; the default base is https.
+ */
+function download(url, dest, redirectsLeft = 5) {
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith('http://') ? http : https;
+    const request = client.get(url, { headers: { 'user-agent': 'francois-npm-installer' } }, (res) => {
+      const { statusCode, headers } = res;
+
+      if (statusCode >= 300 && statusCode < 400 && headers.location) {
+        res.resume();
+        if (redirectsLeft === 0) return reject(new Error('too many redirects'));
+        return resolve(download(new URL(headers.location, url).toString(), dest, redirectsLeft - 1));
+      }
+
+      if (statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${statusCode} for ${url}`));
+      }
+
+      const file = fs.createWriteStream(dest);
+      res.pipe(file);
+      file.on('error', reject);
+      file.on('finish', () => file.close(() => resolve()));
+    });
+
+    request.setTimeout(REQUEST_TIMEOUT_MS, () => request.destroy(new Error('download timed out')));
+    request.on('error', reject);
+  });
+}
+
+async function downloadWithRetries(url, dest) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      await download(url, dest);
+      return;
+    } catch (error) {
+      fs.rmSync(dest, { force: true });
+      if (attempt === MAX_ATTEMPTS) throw error;
+      log(`download failed (${error.message}) — retrying ${attempt}/${MAX_ATTEMPTS - 1}`);
+      await new Promise((r) => setTimeout(r, attempt * 1000));
+    }
+  }
+}
+
+function sha256(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, { stdio: 'ignore' });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${command} exited ${result.status}`);
+}
+
+/**
+ * .tar.gz everywhere except Windows, which gets a .zip. Windows 10 1803+ ships
+ * bsdtar as tar.exe (it reads zip too); Expand-Archive covers anything older.
+ */
+function extract(archive, dest) {
+  if (archive.endsWith('.zip')) {
+    try {
+      run('tar', ['-xf', archive, '-C', dest]);
+    } catch {
+      run('powershell', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        `Expand-Archive -LiteralPath '${archive}' -DestinationPath '${dest}' -Force`,
+      ]);
+    }
+  } else {
+    // System tar on macOS/Linux preserves the bundle's symlinks and exec bits.
+    run('tar', ['-xzf', archive, '-C', dest]);
+  }
+}
+
+async function main() {
+  if (process.env.FRANCOIS_SKIP_DOWNLOAD) {
+    log('FRANCOIS_SKIP_DOWNLOAD set — skipping the app download.');
+    return;
+  }
+
+  const key = assetKey();
+  if (!key) {
+    fail(
+      `no prebuilt app for ${process.platform}/${process.arch}.\n` +
+        `Published builds: ${supportedList()}.\n` +
+        'Build from source instead: https://github.com/antoine-gmnz/francois#build-from-source',
+    );
+  }
+
+  const manifest = readManifest();
+  if (!manifest || !manifest.assets || !manifest.assets[key]) {
+    fail(
+      'this package has no release manifest, so there is nothing to download.\n' +
+        'That means it was not built by CI — install the published package with `npm i -g francois`.',
+    );
+  }
+
+  const asset = manifest.assets[key];
+  const url = `${DOWNLOAD_BASE}/${manifest.repo}/releases/download/${manifest.tag}/${asset.name}`;
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'francois-install-'));
+  const archive = path.join(staging, asset.name);
+  // On the exit hook rather than in a finally, so that fail()'s process.exit()
+  // — which skips finally blocks — still clears the staging directory.
+  process.on('exit', () => fs.rmSync(staging, { recursive: true, force: true }));
+
+  try {
+    log(`downloading Francois ${manifest.appVersion} (${key})…`);
+    await downloadWithRetries(url, archive);
+
+    const actual = sha256(archive);
+    if (actual !== asset.sha256) {
+      fail(
+        `checksum mismatch for ${asset.name}.\n` +
+          `  expected ${asset.sha256}\n  actual   ${actual}\n` +
+          (manifest.channel === 'dev'
+            ? 'The rolling `dev` release is replaced on every push to main, so an older\n' +
+              'dev package points at binaries that no longer exist. Install the current\n' +
+              'one: npm i -g francois@dev'
+            : 'Refusing to install a binary that does not match the published release.'),
+      );
+    }
+
+    fs.rmSync(VENDOR_DIR, { recursive: true, force: true });
+    fs.mkdirSync(VENDOR_DIR, { recursive: true });
+    extract(archive, VENDOR_DIR);
+
+    if (process.platform === 'darwin') {
+      // Belt and braces: npm downloads never carry com.apple.quarantine, but a
+      // user-supplied FRANCOIS_DOWNLOAD_BASE or a proxy could. Best-effort.
+      spawnSync('xattr', ['-dr', 'com.apple.quarantine', VENDOR_DIR], { stdio: 'ignore' });
+    }
+
+    const unpacked = resolveExecutable();
+    if (!unpacked) fail(`the ${asset.name} archive did not contain the app.`);
+
+    // Register with the OS so Francois launches from the Start Menu / Launchpad /
+    // Applications menu like any installed app, not just from a terminal. This
+    // can relocate the payload (macOS moves the bundle to ~/Applications), so
+    // the returned paths — not the ones passed in — are what gets recorded.
+    const productName = manifest.productName || 'Francois';
+    const integration = desktop.install({
+      executable: unpacked,
+      bundle: bundleOf(unpacked),
+      productName,
+      channel: manifest.channel,
+      appVersion: manifest.appVersion,
+    });
+
+    writeInstallRecord({
+      executable: integration.executable,
+      bundle: integration.bundle,
+      productName,
+      channel: manifest.channel,
+      appVersion: manifest.appVersion,
+      tag: manifest.tag,
+    });
+
+    log('installed.');
+    for (const note of integration.notes) log(`  ${note}`);
+    log('  terminal: francois');
+  } catch (error) {
+    fail(`install failed: ${error.message}`);
+  }
+}
+
+main();

package/lib/desktop.js

@@ -0,0 +1,254 @@
+'use strict';
+
+/**
+ * Desktop integration: make an npm-installed Francois behave like an app you
+ * installed, not like a CLI you have to remember the name of.
+ *
+ * npm delivers the bytes (which is what dodges SmartScreen and Gatekeeper —
+ * see install.js) but it only ever puts a command on PATH. Everything the OS
+ * needs to show the app in its own launchers is written here, per-user, with no
+ * elevation and no signature:
+ *
+ *   Windows  Start Menu .lnk + an HKCU uninstall entry (Settings > Installed apps)
+ *   macOS    the .app lives in ~/Applications, so Spotlight/Launchpad/Dock see it
+ *   Linux    a .desktop file + a hicolor icon in ~/.local/share
+ *
+ * Every step is best-effort: a machine with an unusual shell, a locked-down
+ * registry or no desktop environment at all must still end up with a working
+ * `francois` command. Failures are reported, never thrown.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const ICON_SOURCE = path.join(__dirname, '..', 'assets', 'icon.png');
+
+/**
+ * Stable per-channel slug. The dev channel is a separate app with its own data
+ * dir, so its shortcuts must not collide with a stable install's.
+ */
+function appId(channel) {
+  return channel === 'dev' ? 'francois-dev' : 'francois';
+}
+
+function startMenuShortcut(productName, appData = process.env.APPDATA) {
+  if (!appData) return null;
+  return path.join(appData, 'Microsoft', 'Windows', 'Start Menu', 'Programs', `${productName}.lnk`);
+}
+
+function uninstallRegistryKey(channel) {
+  return `HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\${appId(channel)}`;
+}
+
+function desktopEntryPath(channel, home = os.homedir()) {
+  return path.join(home, '.local', 'share', 'applications', `${appId(channel)}.desktop`);
+}
+
+function desktopIconPath(channel, home = os.homedir()) {
+  return path.join(home, '.local', 'share', 'icons', 'hicolor', '128x128', 'apps', `${appId(channel)}.png`);
+}
+
+function applicationsDir(home = os.homedir()) {
+  return path.join(home, 'Applications');
+}
+
+/**
+ * A freedesktop.org .desktop entry. Exec is quoted because the AppImage sits
+ * under npm's global prefix, which on many systems contains spaces.
+ * StartupWMClass lets the shell group the running window under this launcher
+ * instead of showing a second, icon-less entry.
+ */
+function desktopEntry({ productName, exec, icon }) {
+  return [
+    '[Desktop Entry]',
+    'Type=Application',
+    `Name=${productName}`,
+    'Comment=Mission control for your Claude Code fleet',
+    `Exec="${exec}" %U`,
+    `Icon=${icon}`,
+    'Terminal=false',
+    'Categories=Development;Utility;',
+    'StartupWMClass=francois',
+    '',
+  ].join('\n');
+}
+
+/** Run a command purely for its side effect; never let a missing tool throw. */
+function attempt(command, args) {
+  try {
+    return spawnSync(command, args, { stdio: 'ignore' }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// ── Windows ─────────────────────────────────────────────────────────────────
+
+function installWindows({ executable, productName, channel, appVersion, notes }) {
+  const shortcut = startMenuShortcut(productName);
+  if (!shortcut) {
+    notes.push('APPDATA is not set — skipped the Start Menu shortcut.');
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(shortcut), { recursive: true });
+  // WScript.Shell is the only supported way to author a .lnk; there is no
+  // Node API for it and no plain-text equivalent of the format.
+  const ok = attempt('powershell', [
+    '-NoProfile',
+    '-NonInteractive',
+    '-Command',
+    [
+      '$s = (New-Object -ComObject WScript.Shell).CreateShortcut(' + psQuote(shortcut) + ');',
+      '$s.TargetPath = ' + psQuote(executable) + ';',
+      '$s.WorkingDirectory = ' + psQuote(path.dirname(executable)) + ';',
+      "$s.Description = 'Mission control for your Claude Code fleet';",
+      '$s.Save()',
+    ].join(' '),
+  ]);
+  notes.push(ok ? `Start Menu: ${productName}` : 'could not create the Start Menu shortcut.');
+
+  // Makes it appear in Settings > Installed apps like any other program. HKCU
+  // only, so this never needs elevation.
+  const key = uninstallRegistryKey(channel);
+  const values = [
+    ['DisplayName', 'REG_SZ', productName],
+    ['DisplayVersion', 'REG_SZ', appVersion],
+    ['Publisher', 'REG_SZ', 'Antoine Gimenez'],
+    ['DisplayIcon', 'REG_SZ', executable],
+    ['InstallLocation', 'REG_SZ', path.dirname(executable)],
+    ['UninstallString', 'REG_SZ', 'cmd.exe /c npm uninstall -g francois'],
+    ['NoModify', 'REG_DWORD', '1'],
+    ['NoRepair', 'REG_DWORD', '1'],
+  ];
+  const wrote = values.every(([name, type, data]) =>
+    attempt('reg', ['add', key, '/v', name, '/t', type, '/d', data, '/f']),
+  );
+  if (!wrote) notes.push('could not register the uninstall entry.');
+}
+
+function removeWindows({ productName, channel }) {
+  const shortcut = startMenuShortcut(productName);
+  if (shortcut) fs.rmSync(shortcut, { force: true });
+  attempt('reg', ['delete', uninstallRegistryKey(channel), '/f']);
+}
+
+/** Single-quoted PowerShell literal — no expansion, '' escapes a quote. */
+function psQuote(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+// ── macOS ───────────────────────────────────────────────────────────────────
+
+/**
+ * Move the bundle into ~/Applications. A .app buried in node_modules is invisible
+ * to Spotlight and Launchpad; in ~/Applications it is simply an installed Mac
+ * app. Returns the new bundle path.
+ */
+function installMacos({ bundle, home, notes }) {
+  const target = path.join(applicationsDir(home), path.basename(bundle));
+  // Already in place — `francois shortcut` re-runs this, and blindly rm'ing the
+  // target would delete the very bundle we are about to move.
+  if (path.resolve(bundle) !== path.resolve(target)) {
+    fs.mkdirSync(applicationsDir(home), { recursive: true });
+    fs.rmSync(target, { recursive: true, force: true });
+    fs.renameSync(bundle, target);
+  }
+
+  // Nudge LaunchServices so Spotlight sees it now rather than whenever it next
+  // rescans. Absent or relocated on some systems, hence best-effort.
+  attempt(
+    '/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister',
+    ['-f', target],
+  );
+  notes.push(`Applications: ${path.basename(target)}`);
+  return target;
+}
+
+/** Scoped to ~/Applications so a hand-moved bundle elsewhere is never deleted. */
+function removeMacos({ bundle, home }) {
+  if (bundle && path.resolve(bundle).startsWith(path.resolve(applicationsDir(home)))) {
+    fs.rmSync(bundle, { recursive: true, force: true });
+  }
+}
+
+// ── Linux ───────────────────────────────────────────────────────────────────
+
+function installLinux({ executable, productName, channel, home, notes }) {
+  const icon = desktopIconPath(channel, home);
+  const entry = desktopEntryPath(channel, home);
+  fs.mkdirSync(path.dirname(icon), { recursive: true });
+  fs.mkdirSync(path.dirname(entry), { recursive: true });
+  fs.copyFileSync(ICON_SOURCE, icon);
+  fs.writeFileSync(entry, desktopEntry({ productName, exec: executable, icon }));
+  attempt('update-desktop-database', [path.dirname(entry)]);
+  notes.push(`Applications menu: ${productName}`);
+}
+
+function removeLinux({ channel, home }) {
+  const entry = desktopEntryPath(channel, home);
+  fs.rmSync(entry, { force: true });
+  fs.rmSync(desktopIconPath(channel, home), { force: true });
+  attempt('update-desktop-database', [path.dirname(entry)]);
+}
+
+// ── entry points ────────────────────────────────────────────────────────────
+
+/**
+ * Register the app with the OS. Returns { executable, bundle, notes } — the
+ * paths may differ from what went in (macOS relocates the bundle), so the
+ * caller must persist what it gets back.
+ */
+function install({
+  executable,
+  bundle,
+  productName,
+  channel,
+  appVersion,
+  platform = process.platform,
+  home = os.homedir(),
+}) {
+  const notes = [];
+  try {
+    if (platform === 'win32') {
+      installWindows({ executable, productName, channel, appVersion, notes });
+    } else if (platform === 'darwin') {
+      const moved = installMacos({ bundle, home, notes });
+      // The bundle moved, so the executable path inside it moved with it.
+      executable = path.join(moved, path.relative(bundle, executable));
+      bundle = moved;
+    } else if (platform === 'linux') {
+      installLinux({ executable, productName, channel, home, notes });
+    }
+  } catch (error) {
+    notes.push(`desktop integration failed (${error.message}) — the \`francois\` command still works.`);
+  }
+  return { executable, bundle, notes };
+}
+
+/** Undo install(). Safe to call when nothing was ever registered. */
+function remove({ bundle, productName, channel, platform = process.platform, home = os.homedir() }) {
+  try {
+    if (platform === 'win32') removeWindows({ productName, channel });
+    else if (platform === 'darwin') removeMacos({ bundle, home });
+    else if (platform === 'linux') removeLinux({ channel, home });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  ICON_SOURCE,
+  appId,
+  applicationsDir,
+  desktopEntry,
+  desktopEntryPath,
+  desktopIconPath,
+  install,
+  remove,
+  startMenuShortcut,
+  uninstallRegistryKey,
+};

package/lib/platform.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * Platform resolution shared by the postinstall (install.js) and the launcher
+ * (bin/francois.js): which release asset this machine needs, and where the
+ * unpacked executable ends up.
+ *
+ * Plain CommonJS with no dependencies — this runs during `npm install`, before
+ * anything else is guaranteed to exist.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** `${process.platform}:${process.arch}` → release asset key. */
+const SUPPORTED = {
+  // One universal .app covers both Macs, so both arches map to the same asset.
+  'darwin:x64': 'darwin-universal',
+  'darwin:arm64': 'darwin-universal',
+  'win32:x64': 'win32-x64',
+  'linux:x64': 'linux-x64',
+};
+
+const PACKAGE_ROOT = path.join(__dirname, '..');
+const VENDOR_DIR = path.join(PACKAGE_ROOT, 'vendor');
+const MANIFEST_PATH = path.join(PACKAGE_ROOT, 'manifest.json');
+const INSTALL_RECORD = 'install.json';
+
+/** The asset key for a platform/arch pair, or null when unsupported. */
+function assetKey(platform = process.platform, arch = process.arch) {
+  return SUPPORTED[`${platform}:${arch}`] || null;
+}
+
+/** Human-readable list of what we do ship, for the unsupported-platform error. */
+function supportedList() {
+  return [...new Set(Object.values(SUPPORTED))].sort().join(', ');
+}
+
+/**
+ * The manifest is written by CI at publish time (it pins the release tag and the
+ * per-asset sha256). A package built any other way won't have one.
+ */
+function readManifest(manifestPath = MANIFEST_PATH) {
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What the postinstall actually did: where the payload ended up and what it
+ * registered with the OS. macOS moves the bundle out to ~/Applications, so this
+ * is the only reliable way to find it afterwards.
+ */
+function readInstallRecord(vendorDir = VENDOR_DIR) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(vendorDir, INSTALL_RECORD), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeInstallRecord(record, vendorDir = VENDOR_DIR) {
+  fs.writeFileSync(path.join(vendorDir, INSTALL_RECORD), `${JSON.stringify(record, null, 2)}\n`);
+}
+
+/**
+ * Locate the runnable binary. Prefers what the postinstall recorded; falls back
+ * to scanning vendor/ so a payload unpacked by hand still runs.
+ *
+ * The macOS bundle name tracks Tauri's productName and so differs between the
+ * stable ("Francois.app") and dev ("Francois Dev.app") channels — hence the
+ * glob rather than a hardcoded name. Its inner executable is likewise named by
+ * the bundler, so we take whatever is in Contents/MacOS.
+ */
+function resolveExecutable(vendorDir = VENDOR_DIR, platform = process.platform) {
+  const record = readInstallRecord(vendorDir);
+  if (record && record.executable && fs.existsSync(record.executable)) return record.executable;
+
+  if (!fs.existsSync(vendorDir)) return null;
+
+  if (platform === 'win32') {
+    const exe = path.join(vendorDir, 'francois.exe');
+    return fs.existsSync(exe) ? exe : null;
+  }
+
+  if (platform === 'linux') {
+    const appimage = path.join(vendorDir, 'francois.AppImage');
+    return fs.existsSync(appimage) ? appimage : null;
+  }
+
+  if (platform === 'darwin') {
+    const bundle = fs
+      .readdirSync(vendorDir)
+      .filter((entry) => entry.endsWith('.app'))
+      .sort()[0];
+    if (!bundle) return null;
+    const macos = path.join(vendorDir, bundle, 'Contents', 'MacOS');
+    if (!fs.existsSync(macos)) return null;
+    const binary = fs.readdirSync(macos).sort()[0];
+    return binary ? path.join(macos, binary) : null;
+  }
+
+  return null;
+}
+
+module.exports = {
+  INSTALL_RECORD,
+  MANIFEST_PATH,
+  PACKAGE_ROOT,
+  SUPPORTED,
+  VENDOR_DIR,
+  assetKey,
+  readInstallRecord,
+  readManifest,
+  resolveExecutable,
+  supportedList,
+  writeInstallRecord,
+};

package/manifest.json

@@ -0,0 +1,12 @@
+{
+  "repo": "antoine-gmnz/francois",
+  "tag": "dev",
+  "channel": "dev",
+  "appVersion": "0.12.0",
+  "productName": "Francois Dev",
+  "assets": {
+    "darwin-universal": { "name": "francois-darwin-universal.tar.gz", "sha256": "069ede3611b4353b89a529ad4a2601590f90340753f24627351b49d58c795bff" },
+    "linux-x64": { "name": "francois-linux-x64.tar.gz", "sha256": "6a57e3c38afce1537affdfd389d3452b926542fa31704c08ec89ae68aeca42af" },
+    "win32-x64": { "name": "francois-win32-x64.zip", "sha256": "e8e735c18e595ea16ac401722cffe95051592b82a9a0032c0e9afffa1d349428" }
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "francois",
+  "version": "0.12.0-dev.30",
+  "description": "Mission control for your Claude Code fleet — installs the Francois desktop app without an installer.",
+  "license": "AGPL-3.0-only",
+  "author": "Antoine Gimenez",
+  "homepage": "https://github.com/antoine-gmnz/francois#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antoine-gmnz/francois.git",
+    "directory": "packaging/npm"
+  },
+  "bugs": "https://github.com/antoine-gmnz/francois/issues",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "terminal",
+    "tauri",
+    "desktop"
+  ],
+  "bin": {
+    "francois": "bin/francois.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js",
+    "preuninstall": "node uninstall.js"
+  },
+  "files": [
+    "assets/icon.png",
+    "bin/",
+    "lib/desktop.js",
+    "lib/platform.js",
+    "install.js",
+    "uninstall.js",
+    "manifest.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "win32",
+    "linux"
+  ]
+}

package/uninstall.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * preuninstall — unregister the desktop integration before npm deletes the
+ * package directory.
+ *
+ * This matters most on macOS, where the .app was moved out to ~/Applications and
+ * would otherwise survive `npm uninstall -g francois` as an orphan.
+ *
+ * npm's uninstall lifecycle does not fire in every situation (a manually deleted
+ * global folder, some CI teardowns), so `francois shortcut --remove` exists as
+ * the explicit escape hatch. Never fails the uninstall.
+ */
+
+const desktop = require('./lib/desktop.js');
+const { readInstallRecord } = require('./lib/platform.js');
+
+try {
+  const record = readInstallRecord();
+  if (record) desktop.remove(record);
+} catch {
+  // Nothing here is worth blocking an uninstall over.
+}