@kitkat-vn/kitcode 0.2.0-staging.3

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kitkat-vn/kitcode",
+  "version": "0.2.0-staging.3",
+  "description": "Local aggregate activity server for KitCode.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitkatvn/kitcode-dev.git",
+    "directory": "packages/kitcode-cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "kitcode": "bin/kitcode.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "npm run lint",
+    "lint": "node scripts/lint.mjs",
+    "test": "node --test --test-reporter=spec \"test/*.test.mjs\"",
+    "pack:cli": "npm test && npm run lint && npm pack",
+    "verify:onboarding-native": "electron scripts/check-onboarding-electron.mjs"
+  },
+  "dependencies": {
+    "express": "^4.21.2"
+  },
+  "optionalDependencies": {
+    "electron": "^43.0.0"
+  },
+  "gitHead": "ac0e5e53e90fc09132dabc63474e01e962f50a6d"
+}

package/src/api-access.mjs

@@ -0,0 +1,119 @@
+import net from 'node:net';
+import {isAllowedOrigin} from './cors.mjs';
+
+// Who may use the local API (docs/security.md, "The local API"). There is no login: these checks
+// stop web pages, which cannot choose their Host or Origin headers. A program on this machine can
+// send any header it likes; it can also edit ~/.kitcode/state.json directly.
+
+const LOOPBACK_NAMES = ['127.0.0.1', 'localhost'];
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+// Event streams one tracker keeps open at once: the Mini holds one, a preview tab another.
+export const MAX_EVENT_STREAMS = 8;
+
+// A refusal any page may read: fixed words, nothing of the user's and no local path, with
+// `Access-Control-Allow-Origin: *` and no credentials. A dashboard at an address this tracker does not
+// accept can then tell the person to update KitCode, where it could only say that nothing answered.
+// An answer that carries data goes to allow-listed origins alone (cors.mjs).
+function refuse(res, status, error) {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.status(status).json({error});
+}
+
+// Every route: the Host header must be 127.0.0.1 or localhost on the port this request arrived on.
+// A page whose domain was rebound to 127.0.0.1 sends its own domain as Host, and is refused.
+export function requireLoopbackHost(req, res, next) {
+  const host = String(req.headers.host ?? '').toLowerCase();
+  const port = req.socket.localPort;
+
+  if (LOOPBACK_NAMES.some((name) => host === `${name}:${port}`)) {
+    next();
+    return;
+  }
+
+  refuse(res, 403, `KitCode answers only to 127.0.0.1:${port} and localhost:${port}.`);
+}
+
+// Every read that names an Origin: an allow-listed one, or the tracker's own, which only a page it
+// served can have. Any other page is refused in words it can read, rather than answered with data its
+// browser keeps from it. A read with no Origin, a program's or the Mini's, is answered as before.
+// Preflights never get here: cors.mjs answers them.
+export function requireDashboardRead(req, res, next) {
+  const origin = req.headers.origin;
+  const ownOrigin = `http://${String(req.headers.host ?? '').toLowerCase()}`;
+
+  if (!READ_METHODS.has(req.method) || origin === undefined || origin === ownOrigin || isAllowedOrigin(origin)) {
+    next();
+    return;
+  }
+
+  refuse(res, 403, 'KitCode answers only its dashboard.');
+}
+
+// Every route that can change something: a JSON body from an allow-listed Origin. A website can send
+// a text/plain or form POST without asking first; a JSON one needs a CORS preflight, which only an
+// allow-listed origin passes (cors.mjs).
+export function requireDashboardWrite(req, res, next) {
+  if (READ_METHODS.has(req.method)) {
+    next();
+    return;
+  }
+
+  if (!isAllowedOrigin(req.headers.origin)) {
+    refuse(res, 403, 'KitCode accepts changes only from its dashboard.');
+    return;
+  }
+
+  const type = String(req.headers['content-type'] ?? '').split(';')[0].trim().toLowerCase();
+
+  if (type !== 'application/json') {
+    refuse(res, 415, 'KitCode accepts changes only as application/json.');
+    return;
+  }
+
+  next();
+}
+
+// A read only the dashboard may make: the claim bundle (docs/security.md, "The local API"). It needs an
+// allow-listed Origin, as a write does. The other reads answer a request with no Origin too, which is
+// how the Mini, served by the tracker itself, reads them; a page can send no Origin only from the
+// tracker's own origin, or through a request whose answer it cannot read.
+export function requireDashboardOrigin(req, res, next) {
+  if (isAllowedOrigin(req.headers.origin)) {
+    next();
+    return;
+  }
+
+  refuse(res, 403, 'KitCode gives the claim bundle only to its dashboard.');
+}
+
+// Addresses only this machine can reach. A name other than localhost may resolve anywhere.
+export function isLoopbackAddress(host) {
+  const value = String(host ?? '').trim().toLowerCase();
+
+  if (value === 'localhost') {
+    return true;
+  }
+
+  if (net.isIPv4(value)) {
+    return value.split('.')[0] === '127';
+  }
+
+  if (net.isIPv6(value)) {
+    return value === '::1' || /^::ffff:127\./.test(value);
+  }
+
+  return false;
+}
+
+// The address KitCode itself uses to reach a tracker bound to `host`. One bound to every interface
+// is reached on 127.0.0.1; the API answers no other Host, and Windows cannot connect to 0.0.0.0.
+export function reachableAddress(host) {
+  const value = String(host ?? '').trim();
+
+  if (value === '' || value === '0.0.0.0' || value === '::') {
+    return '127.0.0.1';
+  }
+
+  return value === '::1' ? 'localhost' : value;
+}

package/src/api.mjs

@@ -0,0 +1,165 @@
+import express from 'express';
+import {MAX_EVENT_STREAMS, requireDashboardOrigin, requireDashboardRead, requireDashboardWrite, requireLoopbackHost} from './api-access.mjs';
+import {claimBundleFromState} from './claim-bundle.mjs';
+import {corsMiddleware} from './cors.mjs';
+import {renderCompanionWindow} from './companion-window.mjs';
+import {INSTALL_ID_DISPLAY_PATH, InstallIdError, readInstallId} from './install-id.mjs';
+import {STATE_DISPLAY_PATH} from './integration-spec.mjs';
+import {MilestoneRecordError} from './milestones-reached.mjs';
+import {buildSummary, persistRuntimeState, refreshRuntimeLedger} from './runtime.mjs';
+import {normalizeTierPercent, redeemReadyTiers} from './reward.mjs';
+import {loadState, StateFileError} from './store.mjs';
+
+const projectLevelGone = (_req, res) => {
+  res.status(410).json({error: 'Project-level metadata is no longer exposed'});
+};
+
+export function createServer(runtime, version) {
+  const app = express();
+  let openEventStreams = 0;
+
+  app.disable('x-powered-by');
+  // In this order: a foreign Host is refused before anything else; CORS headers come next, so the
+  // dashboard can read what follows, and preflights end there; then a read from a page elsewhere is
+  // refused, and writes are held to the dashboard's own requests. Every refusal is readable by any
+  // page, and says only fixed words (api-access.mjs).
+  app.use(requireLoopbackHost);
+  app.use(corsMiddleware);
+  app.use(requireDashboardRead);
+  app.use(requireDashboardWrite);
+  app.use(express.json());
+
+  // `status` says the API answers, as it always has: the dashboard and older CLIs look for 'ok'.
+  // `tracking` says how the tracker is doing, `ok` or `degraded`, and `problems` says what is wrong,
+  // by code. `pid` lets kitcode track tell this tracker from a process that took its pid later.
+  app.get('/api/health', (_req, res) => {
+    res.json({
+      status: 'ok',
+      app: 'kitcode',
+      version,
+      pid: process.pid,
+      ...(runtime.status?.() ?? {tracking: 'ok', problems: []}),
+    });
+  });
+
+  app.get('/api/summary', (_req, res) => {
+    res.json(buildSummary(runtime));
+  });
+
+  app.get('/companion', (_req, res) => {
+    res.type('html').send(renderCompanionWindow());
+  });
+
+  app.get('/api/projects', (_req, res) => {
+    res.json(buildSummary(runtime).global);
+  });
+
+  app.post('/api/reward/redeem', (req, res) => {
+    const requestedTier = req.body?.tier;
+
+    if (requestedTier !== undefined && !normalizeTierPercent(requestedTier)) {
+      res.status(400).json({error: 'Invalid reward tier'});
+      return;
+    }
+
+    // Readiness is judged from the file, so the tracker's latest time goes there first.
+    persistRuntimeState(runtime);
+    const result = redeemReadyTiers(requestedTier === undefined ? null : requestedTier);
+    refreshRuntimeLedger(runtime);
+
+    res.json({
+      ...result,
+      summary: buildSummary(runtime),
+    });
+  });
+
+  // The claim bundle (docs/backend.md, "The contract"): totals only, from state.json as it is on disk,
+  // which this reads and never writes. Only the dashboard's allow-listed origins get it, where
+  // /api/summary also answers a request with no Origin. The tracker sends it nowhere: the dashboard
+  // carries it on, in a later phase. Its errors name no local path, as none of the API's do.
+  app.get('/api/claim/bundle', requireDashboardOrigin, (_req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+
+    let installId;
+    let state;
+
+    try {
+      installId = readInstallId();
+      state = loadState();
+    } catch (error) {
+      if (error instanceof InstallIdError) {
+        res.status(500).json({error: `KitCode cannot read its install id, ${INSTALL_ID_DISPLAY_PATH}, and has left it as it is.`});
+        return;
+      }
+
+      if (error instanceof StateFileError) {
+        res.status(500).json({error: `KitCode cannot read ${STATE_DISPLAY_PATH}.`});
+        return;
+      }
+
+      throw error;
+    }
+
+    if (installId === null) {
+      res.status(503).json({error: 'KitCode has no install id yet: the tracker makes one as it starts. Run `kitcode untrack`, then `kitcode track`.'});
+      return;
+    }
+
+    try {
+      res.json(claimBundleFromState(state, {installId, cliVersion: version, createdAt: new Date().toISOString()}));
+    } catch (error) {
+      if (!(error instanceof MilestoneRecordError)) {
+        throw error;
+      }
+
+      res.status(500).json({error: `The record of when each milestone was reached, in ${STATE_DISPLAY_PATH}, is not one KitCode writes, and has been left as it is.`});
+    }
+  });
+
+  app.get('/api/projects/:id/commits', projectLevelGone);
+  app.post('/api/projects/:id/start', projectLevelGone);
+  app.post('/api/projects/:id/stop', projectLevelGone);
+  app.post('/api/projects/selection', projectLevelGone);
+
+  // Each open stream costs a summary every second, so their number is capped.
+  app.get('/api/events', (_req, res) => {
+    if (openEventStreams >= MAX_EVENT_STREAMS) {
+      res.setHeader('Retry-After', '5');
+      res.status(503).json({error: `KitCode serves at most ${MAX_EVENT_STREAMS} event streams at once.`});
+      return;
+    }
+
+    openEventStreams += 1;
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+    res.flushHeaders?.();
+
+    const send = () => {
+      res.write('event: summary\n');
+      res.write(`data: ${JSON.stringify(buildSummary(runtime))}\n\n`);
+    };
+    const interval = setInterval(send, 1000);
+
+    send();
+    // The response closes when the client goes, whatever the request stream does.
+    res.once('close', () => {
+      clearInterval(interval);
+      openEventStreams -= 1;
+    });
+  });
+
+  // A body that is not valid JSON, and anything thrown, gets a short answer: Express's own error page
+  // carries the stack trace, local paths included.
+  app.use((error, _req, res, next) => {
+    if (res.headersSent) {
+      next(error);
+      return;
+    }
+
+    const status = Number.isInteger(error?.status) && error.status >= 400 && error.status < 500 ? error.status : 500;
+    res.status(status).json({error: status === 500 ? 'KitCode could not answer that request.' : 'KitCode could not read that request.'});
+  });
+
+  return app;
+}

package/src/atomic-file.mjs

@@ -0,0 +1,85 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Writes a file so that no reader, and no crash, can ever see it half-written: the data goes to a
+// temporary file in the same folder, is flushed to disk, and is then renamed over the target in
+// one step. The file gets exactly `mode`, whatever the umask.
+export function writeFileAtomically(filePath, data, {mode}) {
+  const directory = path.dirname(filePath);
+  const tempPath = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+  const fd = fs.openSync(tempPath, 'wx', 0o600);
+
+  try {
+    try {
+      fs.fchmodSync(fd, mode);
+      fs.writeFileSync(fd, data);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+
+    renameIntoPlace(tempPath, filePath);
+  } catch (error) {
+    fs.rmSync(tempPath, {force: true});
+    throw error;
+  }
+
+  syncDirectory(directory);
+}
+
+// Windows will not replace a file another process has open: the rename fails with EPERM, EACCES or
+// EBUSY until that process closes it, as a reader of state.json does within milliseconds (the first
+// Windows CI run, 2026-09-29, "a reader never sees a partial file while a writer saves"). There the
+// rename is tried again, every 50 ms for up to a second, and the target keeps its previous content until
+// one succeeds. macOS and Linux replace an open file, and never wait.
+const RENAME_RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+const RENAME_ATTEMPTS = 20;
+const RENAME_RETRY_MS = 50;
+
+function renameIntoPlace(from, to) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      fs.renameSync(from, to);
+      return;
+    } catch (error) {
+      if (process.platform !== 'win32' || !RENAME_RETRY_CODES.has(error.code) || attempt >= RENAME_ATTEMPTS) {
+        throw error;
+      }
+
+      // The write is synchronous, and so is its wait.
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, RENAME_RETRY_MS);
+    }
+  }
+}
+
+// Temporary files a crashed writeFileAtomically left next to `filePath`. Only safe to remove while
+// nothing else can be writing that file.
+export function leftoverTempFiles(filePath) {
+  const directory = path.dirname(filePath);
+  const prefix = `.${path.basename(filePath)}.`;
+
+  try {
+    return fs.readdirSync(directory)
+      .filter((name) => name.startsWith(prefix) && name.endsWith('.tmp'))
+      .map((name) => path.join(directory, name));
+  } catch {
+    return [];
+  }
+}
+
+export function syncDirectory(directory) {
+  let fd;
+
+  try {
+    fd = fs.openSync(directory, 'r');
+    fs.fsyncSync(fd);
+  } catch {
+    // Some platforms cannot open or flush a folder (Windows cannot). The rename is atomic anyway;
+    // this only makes it durable sooner.
+  } finally {
+    if (fd !== undefined) {
+      fs.closeSync(fd);
+    }
+  }
+}

package/src/break-progress.mjs

@@ -0,0 +1,87 @@
+// The progress numbers KitCode shows (docs/reward-rules.md §10). The CLI's summary, the Mini and the
+// dashboard all show breakProgressPercent, so they agree. Every number is floored: none of them
+// reaches a milestone's percent before both of that milestone's targets are reached.
+//
+// Pure, with no imports: the web app imports this file at build time.
+
+function earnedOf(reward) {
+  return {
+    seconds: Math.floor(Math.max(0, Number(reward?.earnedSeconds) || 0)),
+    equals: Math.max(0, Number(reward?.totalEquals) || 0),
+  };
+}
+
+function ladderOf(milestones) {
+  return (Array.isArray(milestones) ? milestones : [])
+    .map((milestone) => ({
+      percent: Number(milestone?.percent) || 0,
+      seconds: Math.max(0, Number(milestone?.requiredSeconds) || 0),
+      equals: Math.max(0, Number(milestone?.requiredEquals) || 0),
+    }))
+    .sort((a, b) => a.percent - b.percent);
+}
+
+// How far `value` has got from one target to the next, from 0 to 1.
+function segmentFraction(value, from, to) {
+  if (!(to > from)) {
+    return value >= to ? 1 : 0;
+  }
+
+  return Math.min(1, Math.max(0, (value - from) / (to - from)));
+}
+
+// Climbs the milestones in order. Past every milestone `reached` accepts, the percent is that
+// milestone's percent plus the share of the way to the next one, and stays below the next one.
+function climb(ladder, reached, fraction) {
+  let previous = {percent: 0, seconds: 0, equals: 0};
+
+  for (const step of ladder) {
+    if (!reached(step)) {
+      const percent = Math.floor(previous.percent + fraction(previous, step) * (step.percent - previous.percent));
+      return Math.max(previous.percent, Math.min(step.percent - 1, percent));
+    }
+
+    previous = step;
+  }
+
+  return previous.percent;
+}
+
+// Percent of the way to one milestone: floor(100 × min(time ÷ its time, = ÷ its =)), at most 100.
+// It is 100 only when both targets are reached, so a locked milestone never shows 100 %.
+export function milestoneProgressPercent(reward, milestone) {
+  const {seconds, equals} = earnedOf(reward);
+  const requiredSeconds = Math.max(0, Number(milestone?.requiredSeconds) || 0);
+  const requiredEquals = Math.max(0, Number(milestone?.requiredEquals) || 0);
+  const time = requiredSeconds > 0 ? Math.floor((100 * seconds) / requiredSeconds) : 100;
+  const equalsPercent = requiredEquals > 0 ? Math.floor((100 * equals) / requiredEquals) : 100;
+
+  return Math.max(0, Math.min(100, time, equalsPercent));
+}
+
+// The one progress number: how far along the 10, 20, 30, 50, 100 % milestones both targets have
+// got together. It is at least the percent of every milestone reached, and below the percent of the
+// first one that is not.
+export function breakProgressPercent(reward, milestones = reward?.milestones) {
+  const {seconds, equals} = earnedOf(reward);
+
+  return climb(
+    ladderOf(milestones),
+    (step) => seconds >= step.seconds && equals >= step.equals,
+    (from, to) => Math.min(segmentFraction(seconds, from.seconds, to.seconds), segmentFraction(equals, from.equals, to.equals)),
+  );
+}
+
+// Time alone, placed on the same milestones.
+export function timeProgressPercent(reward, milestones = reward?.milestones) {
+  const {seconds} = earnedOf(reward);
+
+  return climb(ladderOf(milestones), (step) => seconds >= step.seconds, (from, to) => segmentFraction(seconds, from.seconds, to.seconds));
+}
+
+// = alone, placed on the same milestones.
+export function equalsProgressPercent(reward, milestones = reward?.milestones) {
+  const {equals} = earnedOf(reward);
+
+  return climb(ladderOf(milestones), (step) => equals >= step.equals, (from, to) => segmentFraction(equals, from.equals, to.equals));
+}

package/src/claim-bundle.mjs

@@ -0,0 +1,37 @@
+import {equalsLedgerFrom} from './equals-ledger.mjs';
+import {focusTimeFrom} from './focus-clock.mjs';
+import {milestonesReachedFrom} from './milestones-reached.mjs';
+import {RULES_VERSION} from './source-snapshot.mjs';
+
+// The claim bundle (docs/backend.md, "The contract"): what a claim for the 50 or 100 % milestone carries,
+// in the shape of the contract's schema version 1 (packages/claim-contract). Totals only: the focus time
+// and the = counted, when each milestone was reached, the counting rules, the CLI's version and the
+// install id, with when the bundle and the milestone record were made.
+//
+// Each field is picked out below, by name. Nothing is copied from the state wholesale, so no project,
+// path, file, line, hash or commit can ride along, and the contract refuses any field it does not name.
+// The CLI never sends it anywhere: the local API gives it to the dashboard, which carries it on in a later
+// phase.
+
+export const CLAIM_BUNDLE_SCHEMA_VERSION = 1;
+
+// The bundle for `state`, the user's state.json as read. Pure: it reads nothing else, and writes nothing.
+// A milestone record that is not what KitCode writes throws (milestones-reached.mjs).
+export function claimBundleFromState(state, {installId, cliVersion, createdAt}) {
+  const ledger = equalsLedgerFrom(state);
+  const {recordingSince, milestones} = milestonesReachedFrom(state);
+
+  return {
+    schemaVersion: CLAIM_BUNDLE_SCHEMA_VERSION,
+    createdAt,
+    installId,
+    cliVersion,
+    rulesVersion: RULES_VERSION,
+    totals: {
+      focusSeconds: Math.floor(focusTimeFrom(state).activeSeconds),
+      equals: ledger.total_equals,
+    },
+    recordingSince,
+    milestones,
+  };
+}

package/src/companion-controls.mjs

@@ -0,0 +1,40 @@
+export const COMPANION_HIDE_CSS = `
+  .title-bar .dot-close {
+    position: relative;
+    z-index: 1;
+    box-sizing: content-box;
+    border: 0;
+    padding: 6px;
+    margin: -6px;
+    display: grid;
+    place-items: center;
+    background: var(--red-color);
+    background-clip: content-box;
+    color: var(--bg-color);
+    font: 700 9px/1 var(--font-mono);
+    cursor: pointer;
+    -webkit-app-region: no-drag;
+  }
+
+  .title-bar .dot-close::before {
+    content: "×";
+    opacity: 0;
+  }
+
+  .title-bar .dot-close:hover::before,
+  .title-bar .dot-close:focus-visible::before {
+    opacity: 1;
+  }
+
+  .title-bar .dot-close:focus-visible {
+    outline: none;
+  }
+`;
+
+export function renderCompanionTitleBar() {
+  return `<div class="title-bar" title="Drag window">
+    <button class="dot filled dot-close" id="hideButton" data-testid="companion-hide" type="button" aria-label="Hide companion" title="Hide"></button>
+    <span class="dot" aria-hidden="true"></span>
+    <span class="dot" aria-hidden="true"></span>
+  </div>`;
+}

package/src/companion-electron.mjs

@@ -0,0 +1,87 @@
+import {app, BrowserWindow, ipcMain, nativeTheme, screen, shell} from 'electron';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {reachableAddress} from './api-access.mjs';
+import {renderCompanionWindow} from './companion-window.mjs';
+import {resolveDashboardUrl} from './open-dashboard.mjs';
+import {keepWindowOnItsPage} from './window-guards.mjs';
+
+const sourceDirectory = path.dirname(fileURLToPath(import.meta.url));
+const host = process.env.KITCODE_HOST ?? '127.0.0.1';
+const port = process.env.KITCODE_PORT ?? '4747';
+// The URL sets the Host header, and the API answers only a loopback Host (api-access.mjs).
+const apiBase = `http://${reachableAddress(host)}:${port}`;
+const companionPreload = path.join(sourceDirectory, 'companion-preload.cjs');
+const miniWidth = 560;
+const miniHeight = 76;
+
+let miniWindow;
+let quitting = false;
+
+function miniPosition() {
+  const {workArea} = screen.getPrimaryDisplay();
+  return {
+    x: workArea.x + workArea.width - miniWidth - 28,
+    y: workArea.y + workArea.height - miniHeight - 72,
+  };
+}
+
+async function trackerReady() {
+  try {
+    const response = await fetch(`${apiBase}/api/health`, {signal: AbortSignal.timeout(1200)});
+    const health = response.ok ? await response.json() : null;
+    return health?.status === 'ok' && health?.app === 'kitcode';
+  } catch {
+    return false;
+  }
+}
+
+function createMiniWindow(url) {
+  const position = miniPosition();
+  miniWindow = new BrowserWindow({
+    width: miniWidth, height: miniHeight,
+    minWidth: miniWidth, minHeight: miniHeight, maxWidth: miniWidth, maxHeight: miniHeight,
+    x: position.x, y: position.y, frame: false, transparent: true, hasShadow: false,
+    backgroundColor: '#00000000', resizable: false,
+    movable: true, alwaysOnTop: true, skipTaskbar: true, show: false,
+    webPreferences: {preload: companionPreload, contextIsolation: true, nodeIntegration: false, sandbox: true},
+  });
+  keepWindowOnItsPage(miniWindow);
+  miniWindow.setAlwaysOnTop(true, 'floating');
+  miniWindow.setVisibleOnAllWorkspaces(true, {visibleOnFullScreen: true});
+  miniWindow.on('close', (event) => {
+    if (!quitting) {
+      event.preventDefault();
+      app.quit();
+    }
+  });
+  miniWindow.loadURL(url);
+}
+
+app.whenReady().then(async () => {
+  nativeTheme.themeSource = 'dark';
+  const connected = await trackerReady();
+  const miniUrl = connected
+    ? `${apiBase}/companion`
+    : `data:text/html;charset=utf-8,${encodeURIComponent(renderCompanionWindow(apiBase))}`;
+  createMiniWindow(miniUrl);
+  ipcMain.handle('kitcode:companion-hide', (event) => {
+    if (event.sender === miniWindow.webContents) app.quit();
+    return {hidden: true};
+  });
+  ipcMain.handle('kitcode:open-dashboard', (event) => {
+    if (event.sender !== miniWindow.webContents) {
+      return {opened: false};
+    }
+
+    shell.openExternal(resolveDashboardUrl());
+    return {opened: true};
+  });
+  miniWindow.once('ready-to-show', () => miniWindow.showInactive());
+});
+
+app.on('before-quit', () => {
+  quitting = true;
+  ipcMain.removeHandler('kitcode:companion-hide');
+  ipcMain.removeHandler('kitcode:open-dashboard');
+});

package/src/companion-preload.cjs

@@ -0,0 +1,10 @@
+const {contextBridge, ipcRenderer} = require('electron');
+
+contextBridge.exposeInMainWorld('kitcodeCompanion', {
+  hide() {
+    return ipcRenderer.invoke('kitcode:companion-hide');
+  },
+  openDashboard() {
+    return ipcRenderer.invoke('kitcode:open-dashboard');
+  },
+});