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

package/src/hook-prompt.mjs

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import {spawn} from 'node:child_process';
+import {hookFinished, hookStarted} from './diagnostics.mjs';
 import {appendLogLine} from './log-file.mjs';
 import {formatBreakDuration, nextBreakReminder} from './next-break-reminder.mjs';
 import {getDiskRewardSummary, getReadyUnannouncedTiers, markTiersAnnounced} from './reward.mjs';
@@ -175,11 +176,20 @@ function collectPromptProgress(source) {
   }
 }
 
+// In a tester build alone (src/diagnostics.mjs), each run also leaves a start marker, which it removes as it ends, so that a
+// run its agent stopped at the timeout is found later by whatever sends, since it cannot record its own end; and it records
+// a failure, by the error's code and name, or else a run past 2 s: one event at most, one small file. The hook never touches
+// the network: a tester build's tracker, or a command, sends what it recorded. Neither call ever throws; in any other build
+// each returns at once.
 export async function runPromptHook({source}) {
   if (isDisabled()) {
     return;
   }
 
+  const started = Date.now();
+  const marker = hookStarted(source, started);
+  let failure = null;
+
   try {
     const input = await readStdin();
     const payload = JSON.parse(input || '{}');
@@ -199,6 +209,9 @@ export async function runPromptHook({source}) {
     notify('KitCode milestone reached', `Milestone ${label} unlocked. Open kitcode dashboard.`);
     process.stdout.write(`${JSON.stringify(hookOutputFor({tiers: announced, reward}))}\n`);
   } catch (error) {
+    failure = error;
     logHookError(error);
+  } finally {
+    hookFinished(marker, source, Date.now() - started, failure);
   }
 }

package/src/integration-spec.mjs

@@ -1,10 +1,15 @@
 export const CLI_PACKAGE_NAME = '@kitkat-vn/kitcode';
 export const CLI_PACKAGE_COMMAND = `npx ${CLI_PACKAGE_NAME}`;
 export const CLI_GLOBAL_INSTALL_COMMAND = `npm install -g ${CLI_PACKAGE_NAME}`;
-// A staging round's tester build, once one is published under npm's `staging` tag (stagingSetupPromptFor, below).
+// A staging round's tester build, published under npm's `staging` tag: since 2026-10-02 the only way a tester installs it
+// (stagingSetupPromptFor, below).
 export const CLI_STAGING_INSTALL_COMMAND = `${CLI_GLOBAL_INSTALL_COMMAND}@staging`;
 export const CLI_GLOBAL_COMMAND = 'kitcode';
 export const DASHBOARD_URL = "https://staging.kitcode.vn/";
+// Where a tester build sends KitCode's own diagnostics (src/diagnostics.mjs; docs/backend.md, "Tester diagnostics"): the
+// staging dashboard's /v1/diagnostics, which scripts/tester-build.mjs alone writes here, as it writes DASHBOARD_URL. null in
+// the repository, and so in every release of it: such a CLI collects, writes and sends no diagnostics at all.
+export const DIAGNOSTICS_URL = "https://staging.kitcode.vn/v1/diagnostics";
 export const LOCAL_SERVER_URL = 'http://127.0.0.1:4747';
 export const STATE_DISPLAY_PATH = '~/.kitcode/state.json';
 export const RUNNER_PATH_PARTS = ['.kitcode', 'bin', 'kitcode'];
@@ -258,16 +263,28 @@ export function assistantSetupPromptFor(source) {
   ].join('\n');
 }
 
+// What the staging setup prompt says of the tester build's diagnostics (src/diagnostics.mjs; the operator's decision 2 of
+// the voucher scheme's phase 4, 2026-10-01): that it sends them, where to, and what they never hold. In the tester's own
+// voice, as the prompt is, and with no URL in it, as the prompt has none.
+export const STAGING_DIAGNOSTICS_NOTICE = 'The tester build sends diagnostic logs to KitCode\'s staging server: KitCode\'s own events and errors, such as the tracker starting or a hook failing, and never my code, my files, my prompts or my project names.';
+
 // The setup prompt a staging dashboard copies for its invited testers (apps/web src/lib/staging-prompts.ts): the one
-// above, line for line, with three changes and no other. Step 2 installs the round's tester build, from the file the
-// tester downloaded from the staging site, which the dashboard's steps link (install 'file'), or, once a staging
-// version is published, from npm's `staging` tag (install 'npm'), and checks its version. Then, before step 3 turns
-// KitCode on, it stops a tracker an earlier build left running. And it holds no URL: the public docs the prompt above
-// links are not public yet (docs/lessons-learned.md F5). It is made from the prompt above as it stands, so that the two
-// cannot drift: a line it changes that is not there once throws, and check-integration-spec.mjs runs both.
-export function stagingSetupPromptFor(source, {testerVersion, fileName, install}) {
-  if (install !== 'file' && install !== 'npm') {
-    throw new Error('stagingSetupPromptFor installs from a file or from npm: install must be \'file\' or \'npm\'.');
+// above, line for line, with four changes and no other. Step 2 installs the round's tester build from npm's `staging` tag,
+// and checks its version. Then, before step 3 turns KitCode on, it stops a tracker an earlier build left running. It holds
+// no URL: the public docs the prompt above links are not public yet (docs/lessons-learned.md F5). And, since the voucher
+// scheme's phase 4, it says, under the round's line, that the tester build sends diagnostic logs to KitCode's staging
+// server (STAGING_DIAGNOSTICS_NOTICE). It is made from the prompt above as it stands, so that the two cannot drift: a line
+// it changes that is not there once throws, and check-integration-spec.mjs runs both.
+//
+// Until 2026-10-02 it could install a file the tester downloaded from the staging site instead (install 'file', with its
+// fileName). The operator's rule of that day is npm alone, "never let user download file even as tester, must be via npm
+// package only": it takes the tester build's version and nothing else, and refuses an option it does not know, so that a
+// caller still asking for the file is told so rather than given npm in silence.
+export function stagingSetupPromptFor(source, options) {
+  const {testerVersion, ...others} = options;
+
+  if (Object.keys(others).length > 0) {
+    throw new Error(`stagingSetupPromptFor takes the tester build's version alone, and installs it from npm's staging tag: it does not know ${Object.keys(others).join(', ')}.`);
   }
 
   const lines = assistantSetupPromptFor(source).split('\n');
@@ -289,15 +306,10 @@ export function stagingSetupPromptFor(source, {testerVersion, fileName, install}
     throw new Error('stagingSetupPromptFor found no blank line after the public docs: assistantSetupPromptFor changed, and stagingSetupPromptFor must follow it.');
   }
 
-  lines.splice(docs, docsEnd - docs, `KitCode is a local-first project. I am an invited tester of its staging round, which needs KitCode's tester build, ${testerVersion}: step 2 installs it.`);
+  lines.splice(docs, docsEnd - docs, `KitCode is a local-first project. I am an invited tester of its staging round, which needs KitCode's tester build, ${testerVersion}: step 2 installs it.`, STAGING_DIAGNOSTICS_NOTICE);
 
   const installLine = onlyLine((line) => line.endsWith(`install KitCode globally with: ${CLI_GLOBAL_INSTALL_COMMAND}`), 'the install');
-  lines[installLine] = lines[installLine].replace(
-    `with: ${CLI_GLOBAL_INSTALL_COMMAND}`,
-    install === 'npm'
-      ? `with: ${CLI_STAGING_INSTALL_COMMAND}`
-      : `from the tester build I downloaded from KitCode's staging site, ${fileName}. Look for it in my Downloads folder, and if it is not there, ask me where it is. In the folder that holds it, run: npm install -g ./${fileName}`,
-  );
+  lines[installLine] = lines[installLine].replace(`with: ${CLI_GLOBAL_INSTALL_COMMAND}`, `with: ${CLI_STAGING_INSTALL_COMMAND}`);
 
   const globalCommand = onlyLine((line) => line === `- After install, use the global ${CLI_GLOBAL_COMMAND} command for all following steps (not npx).`, 'the global command');
   lines.splice(

package/src/onboarding-electron.mjs

@@ -4,6 +4,7 @@ import {app, BrowserWindow, dialog, ipcMain, nativeTheme} from 'electron';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {describeProjects, listProjectRecords, registerNewProjects, removeProject, resolveInitialProjectSuggestion} from './runtime.mjs';
+import {diagnosticsEnabled, readInvitedEmail, setInvitedEmail} from './diagnostics.mjs';
 import {DASHBOARD_URL} from './integration-spec.mjs';
 import {onboardingPreferences, saveOnboardingPreferences, STORE_DIR} from './store.mjs';
 import {resolveSetupPlatform} from './onboarding-platform.mjs';
@@ -154,6 +155,8 @@ app.whenReady().then(() => {
       ...onboardingPreferences(),
       projects: listProjectRecords(),
       suggestedProjects: initialSuggestedProjects(),
+      // A tester build's: the email the tester gave before, if any (src/diagnostics.mjs).
+      ...(diagnosticsEnabled() ? {invitedEmail: readInvitedEmail()} : {}),
     };
   });
   ipcMain.handle('kitcode:onboarding-select-folders', async (event) => {
@@ -164,6 +167,11 @@ app.whenReady().then(() => {
   });
   ipcMain.handle('kitcode:onboarding-submit', async (event, input) => {
     if (event.sender !== window.webContents) return {ok: false, error: 'Invalid setup request.'};
+    // A tester build's invited email, kept outside state.json, before anything else is saved; one that is not an address is
+    // asked for again, and nothing is saved.
+    if (diagnosticsEnabled() && typeof input?.invitedEmail === 'string' && !setInvitedEmail(input.invitedEmail).ok) {
+      return {ok: false, error: 'That email address does not look right: check it, or leave it empty.'};
+    }
     const folders = validFolders(input?.folders);
     if (!folders.length && !listProjectRecords().length) return {ok: false, error: 'Add at least one readable project folder.'};
     try { registerNewProjects(folders); } catch { return {ok: false, error: 'KitCode could not register one of those folders.'}; }

package/src/onboarding-window.mjs

@@ -1,3 +1,4 @@
+import {diagnosticsEnabled} from './diagnostics.mjs';
 import {
   renderPlatformChrome,
   resolveSetupPlatform,
@@ -5,7 +6,11 @@ import {
 } from './onboarding-platform.mjs';
 import {contentSecurityPolicy, fontFaces} from './window-page.mjs';
 
-export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
+// `diagnostics`: whether this is a tester build (src/diagnostics.mjs), unless a test says. Then, and only then, Welcome says
+// that the build sends diagnostic logs to KitCode's staging server, and what they never hold, and asks, optionally, for the
+// email the tester was invited with, so that staff can find their logs by it. Without it the page is as it was, byte for
+// byte.
+export function renderOnboardingWindow(platform = resolveSetupPlatform(), {diagnostics = diagnosticsEnabled()} = {}) {
   const theme = setupPlatformTheme(platform);
   // The page's one stylesheet and one script, kept apart so that its policy allows exactly them.
   const style = `
@@ -460,7 +465,28 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
     .status-text[data-state="success"] { color: var(--red-color); }
 
     .keyboard-hint.status-shortcuts { color: var(--white-text); }
-  `;
+${diagnostics ? `
+    /* With a third step the steps outgrow the panel at the window's own 960 x 640: the projects step must not shrink, as it
+       does alone to fill the panel, or its list and + ADD PROJECTS spill under the diagnostics step, whose email field then
+       takes their clicks (found 2026-10-02). The panel scrolls instead, as its rail expects. */
+    .projects-step { flex: 0 0 auto; }
+
+    .diagnostics-step p { color: var(--white-text); font-size: 10px; line-height: 1.5; margin-bottom: 10px; max-width: 560px; }
+
+    .diagnostics-step label { display: block; color: var(--grey-text); font-size: 10px; margin-bottom: 6px; }
+
+    .diagnostics-step input {
+      width: 100%;
+      max-width: 360px;
+      padding: 7px 9px;
+      background: transparent;
+      color: var(--white-text);
+      border: 1px dashed var(--grey-border);
+      -webkit-app-region: no-drag;
+    }
+
+    .diagnostics-step input:focus-visible { outline: none; border-color: var(--red-color); }
+` : ''}  `;
   const script = `
     const bridge = window.kitcodeOnboarding;
     const projectList = document.getElementById('projectList');
@@ -472,7 +498,8 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
     const setupContent = document.getElementById('setupContent');
     const railItems = [...document.querySelectorAll('.rail-item')];
     const stepSections = [...document.querySelectorAll('[data-setup-step]')];
-    const SAVE_LABEL = '+ SAVE AND OPEN KITCODE ->';
+    const SAVE_LABEL = '+ SAVE AND OPEN KITCODE ->';${diagnostics ? `
+    const invitedEmail = document.getElementById('invitedEmail');` : ''}
     const FOLDER_ICON = '<svg class="dropzone-icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"></path></svg>';
     let persistedProjects = [];
     let pendingProjects = [];
@@ -713,7 +740,8 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
         const result = await bridge.submit({
           folders: pendingProjects.map((project) => project.repoRoot),
           autoTrack,
-          companionView,
+          companionView,${diagnostics ? `
+          invitedEmail: invitedEmail.value,` : ''}
         });
 
         if (Array.isArray(result.projects)) {
@@ -777,7 +805,8 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
           suggestedCount += 1;
         }
 
-        document.querySelector('input[name="autoTrack"][value="' + (state.autoTrack === false ? 'no' : 'yes') + '"]').checked = true;
+        document.querySelector('input[name="autoTrack"][value="' + (state.autoTrack === false ? 'no' : 'yes') + '"]').checked = true;${diagnostics ? `
+        invitedEmail.value = typeof state.invitedEmail === 'string' ? state.invitedEmail : '';` : ''}
         document.querySelectorAll('.option-group').forEach(syncOptionGroup);
         renderProjects();
 
@@ -826,7 +855,12 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
           <div class="rail-item" data-step="projects" data-testid="setup-rail-projects">
             <span class="rail-badge tech-box-red">02</span>
             <span class="rail-label">PROJECTS</span>
-          </div>
+          </div>${diagnostics ? `
+          <div class="step-connector" aria-hidden="true"></div>
+          <div class="rail-item" data-step="diagnostics" data-testid="setup-rail-diagnostics">
+            <span class="rail-badge tech-box-red">03</span>
+            <span class="rail-label">DIAGNOSTICS</span>
+          </div>` : ''}
         </aside>
         <div class="content">
           <fieldset class="step" id="trackingStep" data-setup-step="tracking">
@@ -852,7 +886,13 @@ export function renderOnboardingWindow(platform = resolveSetupPlatform()) {
               <button class="terminal-button tech-box-red" id="pickFolders" type="button" data-testid="add-projects">+ ADD PROJECTS</button>
               <p class="hint">Existing files become the baseline.<br>Source and diffs stay local.</p>
             </div>
-          </section>
+          </section>${diagnostics ? `
+          <section class="step diagnostics-step" aria-labelledby="diagnosticsTitle" data-setup-step="diagnostics" data-testid="setup-diagnostics">
+            <h2 class="section-title" id="diagnosticsTitle">This test build sends diagnostic logs</h2>
+            <p>This test build of KitCode sends diagnostic logs to KitCode’s staging server: KitCode’s own events and errors, such as the tracker starting or a hook failing, so that a problem you meet can be traced without asking you for it. They never hold your code, your files, your prompts or your project names.</p>
+            <label for="invitedEmail">The email address you were invited with, optional: staff find your logs by it.</label>
+            <input id="invitedEmail" name="invitedEmail" type="email" autocomplete="email" maxlength="254" spellcheck="false" data-testid="invited-email">
+          </section>` : ''}
         </div>
       </div>
       <div class="dashed-divider section-divider" aria-hidden="true">==================================================================================================================================================================================================</div>

package/src/runtime.mjs

@@ -787,8 +787,10 @@ function enqueue(runtime, projectId, run, job) {
 }
 
 // What is wrong with the tracker, by fixed code (the prompt hook turns each code into fixed words,
-// so nothing from a file reaches the agent): the projects affected, and since when.
-function reportProblem(runtime, code, projectId, message) {
+// so nothing from a file reaches the agent): the projects affected, and since when. `onProblem` hears of each project's
+// problem raised and cleared, with the error that raised it where there is one: a tester build's diagnostics
+// (src/diagnostics.mjs) record it, by the code, an opaque reference to the project and the error's code alone.
+function reportProblem(runtime, code, projectId, message, error = null) {
   const problem = runtime.problems.get(code) ?? {since: new Date().toISOString(), projects: new Set()};
 
   if (problem.projects.has(projectId)) {
@@ -798,6 +800,7 @@ function reportProblem(runtime, code, projectId, message) {
   problem.projects.add(projectId);
   runtime.problems.set(code, problem);
   runtime.log.warn(message);
+  runtime.watcherOptions?.onProblem?.({code, projectId, state: 'raised', error});
   runtime.watcherOptions?.onStatus?.(trackerStatus(runtime));
 }
 
@@ -813,6 +816,7 @@ function clearProblem(runtime, code, projectId) {
   }
 
   runtime.log.info(`${code} cleared for ${runtime.state.projects[projectId]?.repoRoot ?? projectId}`);
+  runtime.watcherOptions?.onProblem?.({code, projectId, state: 'cleared', error: null});
   runtime.watcherOptions?.onStatus?.(trackerStatus(runtime));
 }
 
@@ -837,7 +841,7 @@ function scanFailed(runtime, projectId, error) {
   // stays as it is, and the next scan tries again.
   const root = runtime.state.projects[projectId]?.repoRoot ?? projectId;
   const missing = error?.code === 'ENOENT' || error?.code === 'ENOTDIR';
-  reportProblem(runtime, missing ? 'project-missing' : 'scan-failed', projectId, `Scanning ${root} failed (${error?.code ?? 'error'}: ${error?.message ?? error}); its snapshot is kept, and nothing in it is counted until a scan succeeds.`);
+  reportProblem(runtime, missing ? 'project-missing' : 'scan-failed', projectId, `Scanning ${root} failed (${error?.code ?? 'error'}: ${error?.message ?? error}); its snapshot is kept, and nothing in it is counted until a scan succeeds.`, error);
 }
 
 // A Git project whose index stayed locked through a scan (index.lock, git.mjs gitArrival 'locked'): the
@@ -1021,12 +1025,12 @@ function watchFailed(runtime, projectId, run, error) {
   const root = runtime.state.projects[projectId]?.repoRoot ?? projectId;
 
   if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
-    reportProblem(runtime, 'project-missing', projectId, `Watching ${root} failed (${error.code}: ${error.message}): the folder is gone, so nothing in it is counted.`);
+    reportProblem(runtime, 'project-missing', projectId, `Watching ${root} failed (${error.code}: ${error.message}): the folder is gone, so nothing in it is counted.`, error);
     return;
   }
 
   run.poll = setInterval(() => queueFullScan(runtime, projectId, 'poll'), POLL_INTERVAL_MS);
-  reportProblem(runtime, 'watch-failed', projectId, `Watching ${root} failed (${error?.code ?? 'error'}: ${error?.message ?? error}); polling it every ${POLL_INTERVAL_MS / 1000} s instead.`);
+  reportProblem(runtime, 'watch-failed', projectId, `Watching ${root} failed (${error?.code ?? 'error'}: ${error?.message ?? error}); polling it every ${POLL_INTERVAL_MS / 1000} s instead.`, error);
 }
 
 function watchProject(runtime, projectId, run) {
@@ -1271,7 +1275,8 @@ export function buildSummary(runtime) {
 }
 
 // Starts the tracker's work. `options.log` records what goes wrong; `options.onStatus` hears how the
-// tracker is doing whenever that changes, and after every save.
+// tracker is doing whenever that changes, and after every save; `options.onProblem`, each project's problem as it is raised
+// and cleared (reportProblem).
 export function startWatchers(runtime, options = {}) {
   runtime.watcherOptions = options;
   runtime.log = options.log ?? SILENT_LOG;