@kitkat-vn/kitcode 0.2.0-staging.3

package/src/tracker-instance.mjs

@@ -0,0 +1,166 @@
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import process from 'node:process';
+import {reachableAddress} from './api-access.mjs';
+import {writeFileAtomically} from './atomic-file.mjs';
+import {STORE_DIR, withStateLock} from './store.mjs';
+
+// ~/.kitcode/tracker.json names the one tracker of this HOME: two trackers would each write their
+// own time into the same projects. Only the tracker it names writes or removes it.
+export const TRACKER_PATH = path.join(STORE_DIR, 'tracker.json');
+// What the tracker did and what went wrong: it runs detached, with nowhere else to say it.
+export const TRACKER_LOG_PATH = path.join(STORE_DIR, 'tracker.log');
+
+// A tracker that has claimed tracker.json but does not answer yet is still starting, for this long.
+const STARTING_GRACE_MS = 15_000;
+const TRACKER_FILE_MODE = 0o600;
+// Status updates wait this long for the state lock, then wait for the next update.
+const UPDATE_LOCK_TIMEOUT_MS = 500;
+
+// A process of this user that exists. One that belongs to another user cannot be this user's tracker.
+export function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readTrackerRecord() {
+  try {
+    const record = JSON.parse(fs.readFileSync(TRACKER_PATH, 'utf8'));
+    return record && typeof record === 'object' && Number.isInteger(record.pid) ? record : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeTrackerRecord(record) {
+  fs.mkdirSync(STORE_DIR, {recursive: true});
+  writeFileAtomically(TRACKER_PATH, `${JSON.stringify(record, null, 2)}\n`, {mode: TRACKER_FILE_MODE});
+}
+
+// What the tracker at host:port says about itself, or null when nothing there answers as KitCode.
+// It asks with Host 127.0.0.1:<port>, as a browser on this machine does: the API answers no other
+// Host (api-access.mjs), whatever address the tracker is bound to. fetch cannot set Host.
+export function trackerHealth({host, port}, timeoutMs = 800) {
+  return new Promise((resolve) => {
+    let request;
+
+    try {
+      request = http.get({
+        host: reachableAddress(host),
+        port,
+        path: '/api/health',
+        agent: false,
+        headers: {host: `127.0.0.1:${port}`},
+        signal: AbortSignal.timeout(timeoutMs),
+      }, (response) => {
+        let text = '';
+
+        response.setEncoding('utf8');
+        response.on('data', (chunk) => {
+          text += chunk;
+        });
+        response.on('error', () => resolve(null));
+        response.on('end', () => {
+          try {
+            const health = response.statusCode >= 200 && response.statusCode < 300 ? JSON.parse(text) : null;
+            resolve(health?.status === 'ok' && health?.app === 'kitcode' ? health : null);
+          } catch {
+            resolve(null);
+          }
+        });
+      });
+    } catch {
+      // A port that is not a port, say.
+      resolve(null);
+      return;
+    }
+
+    request.on('error', () => resolve(null));
+  });
+}
+
+// The tracker tracker.json names, when its process is alive: `running` when it answers as that
+// tracker, `starting` when it claimed the file moments ago, and otherwise `unresponsive`, which is a
+// tracker that hangs or, more likely, a pid that now belongs to another process. A tracker from
+// before 2026-09-24 does not report its pid, and counts as running when it answers.
+export async function findRunningTracker() {
+  const record = readTrackerRecord();
+
+  if (!record || !isProcessAlive(record.pid)) {
+    return null;
+  }
+
+  const health = await trackerHealth(record);
+
+  if (health && (health.pid === undefined || health.pid === record.pid)) {
+    return {record, state: 'running', health};
+  }
+
+  const startedAt = Date.parse(record.startedAt);
+
+  if (Number.isFinite(startedAt) && Date.now() - startedAt < STARTING_GRACE_MS) {
+    return {record, state: 'starting'};
+  }
+
+  return {record, state: 'unresponsive'};
+}
+
+function sameRecord(left, right) {
+  return Boolean(left && right) && left.pid === right.pid && left.startedAt === right.startedAt;
+}
+
+// Makes `record` the tracker of record, unless another live process holds tracker.json. The check
+// and the write happen under the state lock, so of two trackers starting together one wins.
+// `replacing` is a record the caller found unresponsive; that one may be replaced.
+export function claimTracker(record, replacing = null) {
+  return withStateLock(() => {
+    const current = readTrackerRecord();
+
+    if (current && current.pid !== record.pid && isProcessAlive(current.pid) && !sameRecord(current, replacing)) {
+      return {claimed: false, current};
+    }
+
+    writeTrackerRecord(record);
+    return {claimed: true};
+  });
+}
+
+// Updates the record of the tracker `pid`, if it is still the tracker of record. A busy lock skips it.
+export function updateTrackerRecord(pid, patch) {
+  try {
+    return withStateLock(() => {
+      const current = readTrackerRecord();
+
+      if (current?.pid !== pid) {
+        return false;
+      }
+
+      writeTrackerRecord({...current, ...patch});
+      return true;
+    }, {lockTimeoutMs: UPDATE_LOCK_TIMEOUT_MS});
+  } catch {
+    return false;
+  }
+}
+
+// Removes tracker.json if it names `pid`, or, with no pid, if its process is gone.
+export function releaseTracker(pid = null) {
+  try {
+    const current = readTrackerRecord();
+
+    if (current && (pid === null ? !isProcessAlive(current.pid) : current.pid === pid)) {
+      fs.rmSync(TRACKER_PATH, {force: true});
+    }
+  } catch {
+    // Nothing to remove.
+  }
+}

package/src/tracker-problems.mjs

@@ -0,0 +1,30 @@
+// What KitCode says when its tracker is stopped or degraded, in fixed words: the prompt hook tells the
+// agent (hook-prompt.mjs), and the dashboard tells the user (apps/web). tracker.json and /api/health
+// give problem codes only, and a code this version does not know gets the general sentence, so nothing
+// written into either becomes text. No imports: the dashboard runs this in the browser.
+
+export const TRACKER_STOPPED = 'KitCode tracker is stopped, so focus time is not being counted; `kitcode track` starts it.';
+
+const PROBLEM_SENTENCES = {
+  'watch-failed': 'KitCode tracker could not watch a project folder, so it checks that folder every few seconds instead.',
+  'project-missing': 'A KitCode project folder is missing, so nothing in it is counted.',
+  'scan-failed': 'KitCode tracker could not read a project, so its = are not being counted.',
+  'git-locked': 'A KitCode project\'s git index has stayed locked (index.lock in its .git folder), so nothing in it is counted until the lock goes; a git command that crashed can leave that file behind.',
+};
+const UNKNOWN_PROBLEM = 'KitCode tracker is working with a problem; its log is ~/.kitcode/tracker.log.';
+
+// A problem code fit to print in a terminal. The tracker's own codes are short identifiers
+// (watch-failed); anything with other characters came from a process squatting the port
+// (docs/security.md), so only identifier characters are kept and the rest is dropped, and the length
+// is capped, so no escape or control sequence reaches the terminal.
+export function safeProblemCode(code) {
+  const cleaned = String(code ?? '').replace(/[^A-Za-z0-9_-]/g, '').slice(0, 40);
+  return cleaned || 'unknown';
+}
+
+// One sentence per kind of problem, in the order first seen; the general one when there is none.
+export function problemSentences(problems) {
+  const codes = (Array.isArray(problems) ? problems : []).map((problem) => problem?.code);
+  const sentences = new Set(codes.map((code) => (Object.hasOwn(PROBLEM_SENTENCES, code) ? PROBLEM_SENTENCES[code] : UNKNOWN_PROBLEM)));
+  return [...(sentences.size > 0 ? sentences : [UNKNOWN_PROBLEM])];
+}

package/src/tracker-stop.mjs

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import {writeFileAtomically} from './atomic-file.mjs';
+import {STORE_DIR} from './store.mjs';
+
+// How `kitcode untrack` and `kitcode uninstall` stop the tracker. On macOS and Linux they send SIGTERM,
+// and the tracker's handler scans the changes still waiting, saves, and logs that it stopped. Windows has
+// no SIGTERM: Node ends the process there at once, and no handler runs, so what the last periodic save
+// missed was lost, and the log never said the tracker stopped (the first Windows CI run, 2026-09-29;
+// docs/lessons-learned.md). There they leave a stop request instead, which the tracker reads every second
+// and answers as it answers SIGTERM (the operator's decision, 2026-09-29).
+//
+// Only a process running as the user can write ~/.kitcode, and such a process can end the tracker anyway:
+// the request opens no new way in. It names one tracker, by the process and the moment tracker.json says
+// it started, because Windows soon reuses a process id: a request left behind never stops a tracker
+// started later, and whichever tracker finds it removes it.
+export const STOP_REQUEST_PATH = path.join(STORE_DIR, 'tracker-stop.json');
+
+const STOP_REQUEST_MODE = 0o600;
+const STOP_CHECK_MS = 1000;
+
+// Asks the tracker `record` describes (tracker.json) to stop, as this platform allows. Throws what
+// process.kill throws, ESRCH when the process has gone, or, on Windows, what writing the request throws.
+export function askTrackerToStop(record, platform = process.platform) {
+  if (platform === 'win32') {
+    writeFileAtomically(STOP_REQUEST_PATH, `${JSON.stringify({pid: record.pid, startedAt: record.startedAt})}\n`, {mode: STOP_REQUEST_MODE});
+    return;
+  }
+
+  process.kill(record.pid, 'SIGTERM');
+}
+
+// The request waiting, removed as it is read: null when there is none. One that cannot be read, or is not
+// JSON, reads as a request for no tracker. Nothing here throws, since it runs inside the tracker.
+function takeStopRequest() {
+  if (!fs.existsSync(STOP_REQUEST_PATH)) {
+    return null;
+  }
+
+  let request = {};
+
+  try {
+    request = JSON.parse(fs.readFileSync(STOP_REQUEST_PATH, 'utf8'));
+  } catch {
+    // Read as a request for no tracker, and removed below.
+  }
+
+  try {
+    fs.rmSync(STOP_REQUEST_PATH, {force: true});
+  } catch {
+    // Removed at the next check.
+  }
+
+  return request;
+}
+
+// Run by the tracker, with its own record: calls `onStop` once, when a request names it. Every request it
+// finds is removed, its own and any other, since one tracker runs per HOME: a request for another tracker
+// is one left behind.
+export function watchForStopRequest(record, onStop) {
+  const timer = setInterval(() => {
+    const request = takeStopRequest();
+
+    if (request?.pid === record.pid && request?.startedAt === record.startedAt) {
+      clearInterval(timer);
+      onStop();
+    }
+  }, STOP_CHECK_MS);
+
+  timer.unref();
+  return () => clearInterval(timer);
+}

package/src/uninstall.mjs

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import process from 'node:process';
+import {hookStatus} from './hook-installers.mjs';
+import {uninstallIntegration} from './integration-installers.mjs';
+import {AGENT_SPECS} from './integration-spec.mjs';
+import {uninstallSkillTree} from './skill-installer.mjs';
+import {STORE_DIR} from './store.mjs';
+import {findRunningTracker, isProcessAlive, releaseTracker} from './tracker-instance.mjs';
+import {askTrackerToStop} from './tracker-stop.mjs';
+
+const INTEGRATION_SOURCES = Object.keys(AGENT_SPECS);
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Stops the tracker tracker.json names, if it answers as that tracker: a process that does not may
+// be anything, since a pid is reused after a restart.
+export async function stopTrackerForUninstall() {
+  const running = await findRunningTracker();
+  const host = running?.record.host ?? '127.0.0.1';
+  const port = Number(running?.record.port ?? 4747);
+
+  if (!running || running.state === 'unresponsive') {
+    releaseTracker();
+    return {stopped: false, host, port};
+  }
+
+  // SIGTERM, or on Windows, which has none, a stop request (tracker-stop.mjs).
+  try {
+    askTrackerToStop(running.record);
+  } catch {
+    releaseTracker();
+    return {stopped: false, host, port};
+  }
+
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    if (!isProcessAlive(running.record.pid)) {
+      releaseTracker();
+      return {stopped: true, host, port};
+    }
+
+    await sleep(200);
+  }
+
+  return {stopped: 'requested', host, port};
+}
+
+export async function uninstallKitCode() {
+  // A config KitCode cannot parse may still call the runner under ~/.kitcode, and so may one the user
+  // made read-only, which KitCode does not write. Removing the runner but not the hook would leave a
+  // hook error on every prompt, so nothing is changed at all. A read-only config with no KitCode
+  // entry calls no runner, and needs no write.
+  const refused = INTEGRATION_SOURCES
+    .map((source) => ({source, ...hookStatus(source)}))
+    .filter((status) => status.installed === null || (status.installed && status.error?.readOnly));
+
+  if (refused.length > 0) {
+    return {refused};
+  }
+
+  const report = {
+    tracker: await stopTrackerForUninstall(),
+    integrations: {},
+    skills: {},
+    store: {removed: false, path: STORE_DIR},
+  };
+
+  for (const source of INTEGRATION_SOURCES) {
+    report.integrations[source] = uninstallIntegration(source);
+    report.skills[source] = uninstallSkillTree(source);
+  }
+
+  if (fs.existsSync(STORE_DIR)) {
+    fs.rmSync(STORE_DIR, {recursive: true, force: true});
+    report.store.removed = true;
+  }
+
+  return report;
+}

package/src/vibe.mjs

@@ -0,0 +1,4 @@
+import {createSourceSnapshot, scanSourceChanges} from './source-snapshot.mjs';
+
+export const createVibeSnapshot = createSourceSnapshot;
+export const scanVibeChanges = scanSourceChanges;

package/src/window-guards.mjs

@@ -0,0 +1,7 @@
+// A KitCode window shows its own page and nothing else: it opens no other window, and it never
+// navigates away, whatever the page asks. The dashboard opens in the user's browser through the
+// preload bridge (companion-electron.mjs, shell.openExternal), not in a window of ours.
+export function keepWindowOnItsPage(window) {
+  window.webContents.setWindowOpenHandler(() => ({action: 'deny'}));
+  window.webContents.on('will-navigate', (event) => event.preventDefault());
+}

package/src/window-page.mjs

@@ -0,0 +1,49 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+
+// What Welcome's and the Mini's pages share: their fonts, embedded, and their Content-Security-Policy.
+
+// The latin subsets Google Fonts serves, as published in @fontsource/vt323 and @fontsource/fira-code
+// 5.3.0, under the SIL Open Font License 1.1 (fonts/<family>/OFL.txt, from github.com/google/fonts).
+// Embedded as data: URLs, so a page asks no server for them, whether it is a file, a data: URL or
+// served by the tracker. A character outside the subset falls back to the next font in the stack.
+const FONTS = {
+  'vt323': {family: 'VT323', faces: [{weight: 400, file: 'vt323/vt323-latin-400-normal.woff2'}]},
+  'fira-code': {
+    family: 'Fira Code',
+    faces: [400, 500, 700].map((weight) => ({weight, file: `fira-code/fira-code-latin-${weight}-normal.woff2`})),
+  },
+};
+
+const fontFaceCache = new Map();
+
+export function fontFaces(names) {
+  const key = names.join(',');
+
+  if (!fontFaceCache.has(key)) {
+    fontFaceCache.set(key, names.flatMap((name) => FONTS[name].faces.map(({weight, file}) => {
+      const data = fs.readFileSync(new URL(`./fonts/${file}`, import.meta.url)).toString('base64');
+      return `@font-face{font-family:'${FONTS[name].family}';font-style:normal;font-weight:${weight};font-display:swap;src:url(data:font/woff2;base64,${data}) format('woff2')}`;
+    })).join('\n'));
+  }
+
+  return fontFaceCache.get(key);
+}
+
+function sha256Source(text) {
+  return `'sha256-${crypto.createHash('sha256').update(text, 'utf8').digest('base64')}'`;
+}
+
+// Only the page's own inline script and stylesheet run, by their hashes; fonts come from data: URLs;
+// the page connects only to `connect`, and nothing else loads, frames, submits or changes its base.
+export function contentSecurityPolicy({script, style, connect = []}) {
+  return [
+    'default-src \'none\'',
+    `script-src ${sha256Source(script)}`,
+    `style-src ${sha256Source(style)}`,
+    'font-src data:',
+    `connect-src ${connect.length > 0 ? connect.join(' ') : '\'none\''}`,
+    'base-uri \'none\'',
+    'form-action \'none\'',
+  ].join('; ');
+}