@kitkat-vn/kitcode 0.2.0-staging.4 → 0.2.0-staging.5

package/bin/kitcode.mjs

@@ -10,6 +10,19 @@ import process from 'node:process';
 import {fileURLToPath} from 'node:url';
 import {createServer} from '../src/api.mjs';
 import {isLoopbackAddress} from '../src/api-access.mjs';
+import {
+  configProblemCode,
+  describeOutcome,
+  diagnosticsEnabled,
+  diagnosticsStatus,
+  errorCodeOf,
+  errorNameOf,
+  projectRef,
+  recordEvent,
+  sendQueued,
+  startDiagnosticsLoop,
+  sweepHookMarkers,
+} from '../src/diagnostics.mjs';
 import {manualHookSnippet} from '../src/hook-installers.mjs';
 import {runPromptHook} from '../src/hook-prompt.mjs';
 import {installIntegration, integrationStatus, uninstallIntegration} from '../src/integration-installers.mjs';
@@ -236,6 +249,8 @@ Commands:
                         Internal prompt hook used by Codex and Claude
   codex on|off|status   Install, remove, or inspect the Codex hook and skill
   claude on|off|status  Install, remove, or inspect the Claude hook and skill
+  diagnostics status|send
+                        A tester build's diagnostics: what waits, and send it now
 
 Options:
   --host <host>         Host to bind, default ${DEFAULT_HOST}
@@ -443,7 +458,7 @@ function openElectronEntry(entryName, environment = {}) {
 
 function printElectronSetupHelp() {
   console.error('KitCode setup needs Electron for the desktop folder picker.');
-  console.error("Reinstall the tester build: download kitcode-0.2.0-staging.4.tgz again from the staging site, https://staging.kitcode.vn/, then run npm install -g ./kitcode-0.2.0-staging.4.tgz in the folder you saved it to.");
+  console.error("Reinstall the tester build with: npm install -g @kitkat-vn/kitcode@staging");
   console.error('If install succeeded but Electron is still missing, fix npm cache permissions and reinstall.');
 }
 
@@ -458,7 +473,7 @@ function printElectronLaunchFailure(result, label) {
 
   if (result?.reason === 'electron-binary-missing') {
     console.error(`Electron's binary is missing: Electron points to ${result.detail}, and nothing is there.`);
-    console.error("Reinstall the tester build: download kitcode-0.2.0-staging.4.tgz again from the staging site, https://staging.kitcode.vn/, then run npm install -g ./kitcode-0.2.0-staging.4.tgz in the folder you saved it to.");
+    console.error("Reinstall the tester build with: npm install -g @kitkat-vn/kitcode@staging");
     return;
   }
 
@@ -480,6 +495,8 @@ async function openOnboardingWindow(options = {}) {
     const platform = normalizeSetupPlatform(options.setupPlatform);
     if (!platform) {
       console.error('Invalid --platform. Use macos, windows, or linux (aliases: darwin, win32).');
+      recordWelcomeFailed(options.welcomeCommand ?? 'setup', {reason: 'invalid-platform'});
+      await sendOnce();
       return false;
     }
     environment.KITCODE_SETUP_PLATFORM = platform;
@@ -491,6 +508,8 @@ async function openOnboardingWindow(options = {}) {
   }
 
   printElectronLaunchFailure(result, 'KitCode Welcome');
+  recordWelcomeFailed(options.welcomeCommand ?? 'setup', result);
+  await sendOnce();
   return false;
 }
 
@@ -650,29 +669,44 @@ async function handleUninstall(options) {
   printUninstallReport(report);
 }
 
+// What became of the hook in the agent's settings, for a tester build's diagnostics: by outcome, and a refusal by a fixed code,
+// never the file's path or its words.
+function recordAgentHook(source, action, hook) {
+  recordEvent('agent-hook', {agent: source, action, outcome: hook.action, problem: hook.action === 'refused' ? configProblemCode(hook.error) : 'none'}, {source: 'command'});
+}
+
 async function handleHookInstaller(source, action) {
   if (action === 'on') {
     const status = installIntegration(source);
     printIntegrationStatus(source, status);
+    recordAgentHook(source, 'on', status.hook);
+    let failed = false;
     if (status.hook.action === 'refused') {
       printRefusedHook(source, status.hook);
       process.exitCode = 1;
+      failed = true;
     }
     if (!onboardingPreferences().completed) {
-      if (!(await openOnboardingWindow({host: DEFAULT_HOST, port: DEFAULT_PORT, initialProject: process.cwd()}))) {
+      if (!(await openOnboardingWindow({host: DEFAULT_HOST, port: DEFAULT_PORT, initialProject: process.cwd(), welcomeCommand: `${source}-on`}))) {
         console.error('KitCode Welcome could not open. Fix Electron install, then re-run `kitcode setup`.');
         process.exitCode = 1;
+        failed = true;
       }
     }
+    if (failed) {
+      await sendOnce();
+    }
     return;
   }
 
   if (action === 'off') {
     const status = uninstallIntegration(source);
     printIntegrationStatus(source, status);
+    recordAgentHook(source, 'off', status.hook);
     if (status.hook.action === 'refused') {
       printRefusedHook(source, status.hook);
       process.exitCode = 1;
+      await sendOnce();
     }
     return;
   }
@@ -690,6 +724,54 @@ async function isServerRunning(options) {
   return Boolean(await trackerHealth(options));
 }
 
+// `kitcode diagnostics status` and `kitcode diagnostics send` (docs/way-of-working.md, "A full staging round"): what a tester
+// build's diagnostics hold, and Send logs now from the terminal, for when the dashboard cannot reach the tracker. Any other
+// build says it sends nothing, and sends nothing.
+async function handleDiagnostics(action) {
+  if (action === 'status' || action === undefined) {
+    const status = diagnosticsStatus();
+
+    if (!status.enabled) {
+      console.log(describeOutcome({outcome: 'disabled'}));
+      return;
+    }
+
+    sweepHookMarkers({source: 'command'});
+    console.log('KitCode diagnostics: this tester build sends KitCode\'s own events and errors to its staging server, never your code, files, prompts or project names.');
+    console.log(`  staging server: ${status.destination}`);
+    console.log(`  install id: ${status.installId ?? 'none yet'}`);
+    console.log(`  invited email: ${status.invitedEmail ?? 'none given'}`);
+    console.log(`  waiting to be sent: ${status.queued} event${status.queued === 1 ? '' : 's'}`);
+
+    if (status.closedUntil) {
+      console.log(`  paused: the staging server is not taking diagnostics; KitCode tries again after ${status.closedUntil}`);
+    }
+
+    console.log(`  last send: ${status.lastSend ? `${status.lastSend.at}, ${describeOutcome(status.lastSend)}` : 'none yet'}`);
+    return;
+  }
+
+  if (action === 'send') {
+    if (!diagnosticsEnabled()) {
+      console.log(describeOutcome({outcome: 'disabled'}));
+      return;
+    }
+
+    sweepHookMarkers({source: 'command'});
+    const result = await sendQueued({timeoutMs: 10_000, maxBatches: 5, manual: true, source: 'command'});
+    console.log(describeOutcome(result));
+
+    if (result.outcome !== 'stored' && result.outcome !== 'nothing') {
+      process.exitCode = 1;
+    }
+
+    return;
+  }
+
+  printHelp();
+  process.exit(1);
+}
+
 // The local API has no login. Bound to anything but loopback, it is on every network that can reach
 // that address, so that takes --allow-non-loopback, and a warning.
 function bindRefusal(options) {
@@ -712,6 +794,49 @@ function printTrackerNotRunning() {
   console.error('KitCode tracker is not running. Run `kitcode track` first.');
 }
 
+// A tester build's diagnostics (src/diagnostics.mjs): a command that saw something fail records it and sends what waits,
+// once, with a short timeout, and quietly, since no tracker may be running to send it later. In any other build each
+// returns at once, and nothing is written or sent.
+const COMMAND_NAMES = new Set(['add', 'remove', 'track', 'untrack', 'list', 'status', 'summary', 'awards', 'dashboard', 'setup', 'uninstall', 'claude', 'codex', 'diagnostics']);
+
+function commandName(command) {
+  const name = command === 'award' || command === 'rewards' ? 'awards' : command;
+  return COMMAND_NAMES.has(name) ? name : 'other';
+}
+
+// Once a process: the first failure sends what waits, then, and what a command records after it waits for the next send.
+let sentOnce = false;
+
+async function sendOnce() {
+  if (!diagnosticsEnabled() || sentOnce) {
+    return;
+  }
+
+  sentOnce = true;
+
+  try {
+    sweepHookMarkers({source: 'command'});
+    await sendQueued({timeoutMs: 3000, maxBatches: 1, source: 'command'});
+  } catch {
+    // Quietly: whatever sends next sends it.
+  }
+}
+
+function recordCommandFailed(command, error) {
+  recordEvent('command-failed', {command: commandName(command), errorCode: errorCodeOf(error), errorName: errorNameOf(error)}, {source: 'command'});
+}
+
+function recordTrackerNotStarted(source, reason, error = null) {
+  recordEvent('tracker-not-started', {reason, errorCode: errorCodeOf(error), errorName: errorNameOf(error)}, {source});
+}
+
+const WELCOME_REASONS = new Set(['missing-electron', 'electron-download-failed', 'electron-binary-missing', 'missing-entry', 'spawn-error', 'exited', 'invalid-platform']);
+
+function recordWelcomeFailed(command, result) {
+  const exitCode = Number.isInteger(result?.code) ? result.code : null;
+  recordEvent('welcome-failed', {command, reason: WELCOME_REASONS.has(result?.reason) ? result.reason : 'other', exitCode}, {source: 'command'});
+}
+
 async function runDaemon(options, status = createStatusReporter()) {
   status.set('Starting KitCode tracker...');
   const log = createLog(TRACKER_LOG_PATH);
@@ -729,6 +854,7 @@ async function runDaemon(options, status = createStatusReporter()) {
   // keeps the last periodic save.
   const fatal = (kind) => (error) => {
     log.error(`${kind}: ${error?.stack ?? error}`);
+    recordEvent('tracker-crashed', {kind: kind === 'uncaughtException' ? 'uncaught-exception' : 'unhandled-rejection', errorCode: errorCodeOf(error), errorName: errorNameOf(error)}, {source: 'tracker'});
     releaseTracker(process.pid);
     process.exit(1);
   };
@@ -741,6 +867,7 @@ async function runDaemon(options, status = createStatusReporter()) {
   if (refusal) {
     status.stop();
     report('error', refusal);
+    recordTrackerNotStarted('tracker', 'bind-refused');
     process.exit(1);
   }
 
@@ -758,12 +885,14 @@ async function runDaemon(options, status = createStatusReporter()) {
   if (existing && existing.state !== 'unresponsive') {
     status.stop();
     report('warn', `Not started: another KitCode tracker (process ${existing.record.pid}) is ${existing.state} at http://${existing.record.host}:${existing.record.port}.`);
+    recordTrackerNotStarted('tracker', 'already-running');
     process.exit(1);
   }
 
   if (!claimTracker(record, existing?.record ?? null).claimed) {
     status.stop();
     report('warn', 'Not started: another KitCode tracker started at the same moment.');
+    recordTrackerNotStarted('tracker', 'claimed-elsewhere');
     process.exit(1);
   }
 
@@ -774,6 +903,7 @@ async function runDaemon(options, status = createStatusReporter()) {
   } catch (error) {
     releaseTracker(process.pid);
     report('error', `Not started: ${error.message}`);
+    recordTrackerNotStarted('tracker', error instanceof StateFileError || error instanceof StateLockError ? 'state-unreadable' : 'start-failed', error);
     throw error;
   }
 
@@ -786,7 +916,17 @@ async function runDaemon(options, status = createStatusReporter()) {
     report('warn', `KitCode could not make its install id (${error.message}); the claim bundle is not given out until it can.`);
   }
 
-  const app = createServer(runtime, VERSION);
+  // A tester build's diagnostics while the tracker runs (src/diagnostics.mjs): its events sent every minute, a heartbeat every
+  // hour, and Send logs now through the local API. In any other build it does nothing.
+  const startedMs = Date.now();
+  const uptimeSeconds = () => Math.max(0, Math.floor((Date.now() - startedMs) / 1000));
+  const diagnostics = startDiagnosticsLoop({
+    snapshot: () => {
+      const current = runtime.status?.() ?? {tracking: 'ok', problems: []};
+      return {projects: Object.values(runtime.state.projects).filter((project) => project.active).length, tracking: current.tracking, problems: current.problems.map((problem) => problem.code)};
+    },
+  });
+  const app = createServer(runtime, VERSION, {diagnostics});
   let cleanup = async () => {};
   let server = null;
 
@@ -802,6 +942,8 @@ async function runDaemon(options, status = createStatusReporter()) {
     server.close(() => process.exit(code));
   };
 
+  const PROBLEMS = new Set(['watch-failed', 'project-missing', 'scan-failed', 'git-locked', 'git-unfinished']);
+
   cleanup = startWatchers(runtime, {
     log,
     onProgress(message) {
@@ -811,12 +953,19 @@ async function runDaemon(options, status = createStatusReporter()) {
     onStatus(current) {
       updateTrackerRecord(process.pid, {...current, heartbeatAt: new Date().toISOString()});
     },
+    // Each project's problem, raised or cleared, by its fixed code and an opaque reference to the project.
+    onProblem({code, projectId, state, error}) {
+      if (PROBLEMS.has(code)) {
+        recordEvent('tracker-problem', {problem: code, state, project: projectRef(projectId), errorCode: errorCodeOf(error)}, {source: 'tracker'});
+      }
+    },
     // state.json can no longer be read. Stop without writing it: it holds the user's progress.
     onStateError(error) {
       status.stop();
       report('error', `Stopped: ${error.message}`);
       cleanup({persist: false});
-      exit(1);
+      recordEvent('tracker-stopped', {reason: 'state-unreadable', uptimeSeconds: uptimeSeconds()}, {source: 'tracker'});
+      diagnostics.stop().finally(() => exit(1));
     },
   });
 
@@ -832,18 +981,23 @@ async function runDaemon(options, status = createStatusReporter()) {
     }
 
     log.info(`stopped (${signal})`);
+    recordEvent('tracker-stopped', {reason: signal === 'stop request' ? 'stop-request' : 'signal', uptimeSeconds: uptimeSeconds()}, {source: 'tracker'});
+    await diagnostics.stop();
     exit(0);
   };
 
   server = app.listen(options.port, options.host, () => {
     status.stop();
     log.info(`started: KitCode ${VERSION}, process ${process.pid}, http://${options.host}:${options.port}, node ${process.version}`);
+    recordEvent('tracker-started', {projects: Object.values(runtime.state.projects).filter((project) => project.active).length, port: options.port}, {source: 'tracker'});
   });
 
   server.on('error', async (error) => {
     status.stop();
     await cleanup().catch(() => {});
     releaseTracker(process.pid);
+    recordTrackerNotStarted('tracker', error.code === 'EADDRINUSE' ? 'port-in-use' : 'start-failed', error);
+    await diagnostics.stop({finalSend: false});
 
     if (error.code === 'EADDRINUSE') {
       report('error', `Not started: port ${options.port} is already in use. Stop the other server or pass --port <port>.`);
@@ -874,6 +1028,8 @@ async function startTracker(options) {
 
   if (refusal) {
     console.error(refusal);
+    recordTrackerNotStarted('command', 'bind-refused');
+    await sendOnce();
     process.exit(1);
   }
 
@@ -952,6 +1108,8 @@ async function startTracker(options) {
   }
 
   console.error('KitCode tracker did not start. Try running `kitcode track` again.');
+  recordTrackerNotStarted('command', 'did-not-answer');
+  await sendOnce();
   process.exit(1);
 }
 
@@ -1031,6 +1189,8 @@ try {
 
       // The folder could not be listed: it is gone, not a folder, or git could not list it.
       console.error(`KitCode could not add ${path.resolve(targetPath)}: ${error.message}`);
+      recordCommandFailed('add', error);
+      await sendOnce();
       process.exit(1);
     }
 
@@ -1080,6 +1240,8 @@ try {
     await handleHookInstaller('codex', options.subcommand);
   } else if (options.command === 'claude') {
     await handleHookInstaller('claude', options.subcommand);
+  } else if (options.command === 'diagnostics') {
+    await handleDiagnostics(options.subcommand);
   } else if (options.command === 'version') {
     console.log(VERSION);
   } else {
@@ -1087,6 +1249,13 @@ try {
     process.exit(options.command === 'help' || !options.command ? 0 : 1);
   }
 } catch (error) {
+  // A tester build records the failure, and sends it, once: but never from the prompt hook, which touches no network, nor
+  // from the tracker, which recorded its own.
+  if (options.command !== 'hook' && !(options.command === 'track' && process.env.KITCODE_DAEMON === '1')) {
+    recordCommandFailed(options.command, error);
+    await sendOnce();
+  }
+
   // A state file KitCode cannot read or lock stops the command with the reason. It is never replaced.
   if (error instanceof StateFileError || error instanceof StateLockError) {
     console.error(error.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitkat-vn/kitcode",
-  "version": "0.2.0-staging.4",
+  "version": "0.2.0-staging.5",
   "description": "Local aggregate activity server for KitCode.",
   "license": "MIT",
   "repository": {
@@ -37,5 +37,5 @@
   "optionalDependencies": {
     "electron": "^43.0.0"
   },
-  "gitHead": "ed3ca58fd6379cf7cfa15824f451773f092fb6d5"
+  "gitHead": "507aaa120cd48a65b06380f3eee194d799428db1"
 }

package/src/api.mjs

@@ -3,6 +3,7 @@ import {MAX_EVENT_STREAMS, requireDashboardOrigin, requireDashboardRead, require
 import {claimBundleFromState} from './claim-bundle.mjs';
 import {corsMiddleware} from './cors.mjs';
 import {renderCompanionWindow} from './companion-window.mjs';
+import {describeOutcome, diagnosticsStatus, sendQueued} from './diagnostics.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';
@@ -20,7 +21,8 @@ const redeemGone = (_req, res) => {
   res.status(410).json({error: 'Break codes are no longer shown or recorded: each milestone reached shows its message on the dashboard.'});
 };
 
-export function createServer(runtime, version) {
+// `diagnostics` is the tracker's send loop (src/diagnostics.mjs, startDiagnosticsLoop), for Send logs now.
+export function createServer(runtime, version, {diagnostics = null} = {}) {
   const app = express();
   let openEventStreams = 0;
 
@@ -105,6 +107,25 @@ export function createServer(runtime, version) {
     }
   });
 
+  // A tester build's diagnostics, for the staging dashboard (docs/security.md, "Tester diagnostics"): whether this tracker
+  // sends them, its install id, which the dashboard links its own events by, what waits, and the last send. Only to an
+  // allow-listed Origin, as the claim bundle, which holds the same install id; never the events, or the invited email.
+  app.get('/api/diagnostics', requireDashboardOrigin, (_req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    const {invitedEmail, ...status} = diagnosticsStatus();
+    res.json(invitedEmail === undefined ? status : {...status, emailGiven: invitedEmail !== null});
+  });
+
+  // Send logs now: the dashboard's button. A write, so it passes every write's guards first: a loopback Host, an allow-listed
+  // Origin and a JSON body (api-access.mjs). It sends what waits, past any backoff, and answers with exactly what the
+  // server confirmed, or why nothing was sent, in plain words; in a build that sends nothing, that it sends nothing.
+  app.post('/api/diagnostics/send', (_req, res, next) => {
+    (diagnostics ? diagnostics.sendNow() : sendQueued({timeoutMs: 10_000, maxBatches: 5, manual: true, source: 'tracker'})).then((result) => {
+      res.setHeader('Cache-Control', 'no-store');
+      res.json({...result, words: describeOutcome(result)});
+    }, next);
+  });
+
   app.get('/api/projects/:id/commits', projectLevelGone);
   app.post('/api/projects/:id/start', projectLevelGone);
   app.post('/api/projects/:id/stop', projectLevelGone);