@kitkat-vn/kitcode 0.2.0-staging.3

package/src/open-dashboard.mjs

@@ -0,0 +1,30 @@
+import {spawn} from 'node:child_process';
+import {DASHBOARD_URL} from './integration-spec.mjs';
+
+export {DASHBOARD_URL};
+
+export function resolveDashboardUrl(url = process.env.KITCODE_DASHBOARD_URL || DASHBOARD_URL) {
+  return url;
+}
+
+export function openDashboard(url = resolveDashboardUrl()) {
+  const opener = process.platform === 'darwin'
+    ? {command: 'open', args: [url]}
+    : process.platform === 'win32'
+      ? {command: 'cmd', args: ['/c', 'start', '', url]}
+      : {command: 'xdg-open', args: [url]};
+
+  try {
+    const child = spawn(opener.command, opener.args, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/reward.mjs

@@ -0,0 +1,311 @@
+import {breakProgressPercent} from './break-progress.mjs';
+import {equalsLedgerFrom, storedEqualsLedger} from './equals-ledger.mjs';
+import {focusTimeFrom} from './focus-clock.mjs';
+import {nextBreakReminder} from './next-break-reminder.mjs';
+import {KITCODE_DISPLAY_MILESTONES, KITCODE_REWARD_TIERS} from './integration-spec.mjs';
+import {loadState, updateState, withStateLock} from './store.mjs';
+
+// The focus time the 100 % milestone needs, fixed (operator decision Q5, 2026-09-25; docs/reward-rules.md
+// §3). Until then it was a setting, down to 1 s: --reward-seconds, KITCODE_REWARD_SECONDS, and
+// rewardSettings.requiredSeconds in state.json. A requiredSeconds an older KitCode stored stays in the
+// file, unread, as the removed requiredEquals does.
+export const REWARD_SECONDS = 3600;
+export const REWARD_TIERS = KITCODE_REWARD_TIERS;
+export const CAMPAIGN_MILESTONES = KITCODE_DISPLAY_MILESTONES;
+export const REWARD_MILESTONES = [
+  ...REWARD_TIERS.map((tier) => ({...tier, rewardBacked: true})),
+  ...CAMPAIGN_MILESTONES.map((milestone) => ({...milestone, rewardBacked: false})),
+];
+// The = the last milestone needs. The = targets are the table's; no setting changes them (the
+// --reward-equals setting, which gated nothing, was removed on 2026-09-24).
+const FINAL_EQUALS = Math.max(...REWARD_MILESTONES.map((milestone) => milestone.requiredEquals));
+
+const VALID_TIER_PERCENTS = new Set(REWARD_TIERS.map((tier) => tier.percent));
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeSource(source) {
+  return source === 'codex' || source === 'claude' ? source : null;
+}
+
+export function normalizeTierPercent(value) {
+  const percent = Number(value);
+
+  if (!VALID_TIER_PERCENTS.has(percent)) {
+    return null;
+  }
+
+  return percent;
+}
+
+function normalizeTierRecord(entry) {
+  const percent = normalizeTierPercent(
+    typeof entry === 'object' && entry !== null ? entry.percent : entry,
+  );
+
+  if (!percent) {
+    return null;
+  }
+
+  const announcedAt = entry?.announced_at && typeof entry.announced_at === 'object'
+    ? Object.fromEntries(
+      Object.entries(entry.announced_at)
+        .filter(([source, value]) => normalizeSource(source) && typeof value === 'string'),
+    )
+    : {};
+
+  return {
+    percent,
+    redeemed_at: typeof entry?.redeemed_at === 'string' ? entry.redeemed_at : null,
+    announced_at: announcedAt,
+  };
+}
+
+export function normalizeEarnedTiers(entries) {
+  const records = new Map();
+
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    const record = normalizeTierRecord(entry);
+
+    if (!record) {
+      continue;
+    }
+
+    const existing = records.get(record.percent);
+    records.set(record.percent, {
+      percent: record.percent,
+      redeemed_at: existing?.redeemed_at ?? record.redeemed_at,
+      announced_at: {
+        ...(existing?.announced_at ?? {}),
+        ...record.announced_at,
+      },
+    });
+  }
+
+  return [...records.values()].sort((a, b) => a.percent - b.percent);
+}
+
+function tierRecordMap(ledger) {
+  return new Map(normalizeEarnedTiers(ledger.earned_tiers).map((record) => [record.percent, record]));
+}
+
+// Replaces the stored records of one tier with a single record made by `change`, in the place of
+// the first one. Every other entry, including tiers this version does not know, and every field it
+// does not know, is kept as it is.
+function updateTierRecord(ledger, percent, change) {
+  const entries = ledger.earned_tiers;
+  const isThisTier = (entry) => normalizeTierRecord(entry)?.percent === percent;
+  const matching = entries.filter(isThisTier);
+  const stored = matching.filter(isObject);
+  const merged = normalizeEarnedTiers(matching)[0] ?? {percent, redeemed_at: null, announced_at: {}};
+  const record = change({
+    ...Object.assign({}, ...stored),
+    ...merged,
+    announced_at: {
+      ...Object.assign({}, ...stored.map((entry) => (isObject(entry.announced_at) ? entry.announced_at : {}))),
+      ...merged.announced_at,
+    },
+  });
+  const firstIndex = entries.findIndex(isThisTier);
+
+  if (firstIndex === -1) {
+    const after = entries.findIndex((entry) => Number(isObject(entry) ? entry.percent : entry) > percent);
+    entries.splice(after === -1 ? entries.length : after, 0, record);
+    return;
+  }
+
+  ledger.earned_tiers = entries.flatMap((entry, index) => {
+    if (index === firstIndex) {
+      return [record];
+    }
+
+    return isThisTier(entry) ? [] : [entry];
+  });
+}
+
+function milestoneTimeTarget(requiredSeconds, percent) {
+  return Math.ceil(requiredSeconds * (percent / 100));
+}
+
+// The reward summary for `earnedSeconds` of focus time and `totalEquals` counted, against the fixed time
+// target and the tier table's = targets. It takes no target: a `settings` a caller still passes, as
+// older code and tests do, is not read.
+export function buildRewardSummary({earnedSeconds, totalEquals, ledger}) {
+  const requiredSeconds = REWARD_SECONDS;
+  const records = tierRecordMap(ledger);
+  const normalizedEarnedSeconds = Math.floor(Math.max(0, Number(earnedSeconds) || 0));
+  const normalizedTotalEquals = Math.max(0, Number(totalEquals) || 0);
+  const tiers = REWARD_TIERS.map((tier) => {
+    const record = records.get(tier.percent);
+    const requiredTimeSeconds = milestoneTimeTarget(requiredSeconds, tier.percent);
+    const unlocked = (
+      normalizedEarnedSeconds >= requiredTimeSeconds &&
+      normalizedTotalEquals >= tier.requiredEquals
+    );
+    const redeemed = Boolean(record?.redeemed_at);
+
+    return {
+      code: tier.code,
+      percent: tier.percent,
+      requiredEquals: tier.requiredEquals,
+      requiredSeconds: requiredTimeSeconds,
+      unlocked,
+      redeemed,
+      redeemedAt: record?.redeemed_at ?? null,
+      status: redeemed ? 'redeemed' : unlocked ? 'ready' : 'locked',
+    };
+  });
+  const tierMap = new Map(tiers.map((tier) => [tier.percent, tier]));
+
+  const summary = {
+    requiredSeconds,
+    requiredEquals: FINAL_EQUALS,
+    earnedSeconds: normalizedEarnedSeconds,
+    totalEquals: normalizedTotalEquals,
+    timeLeftSeconds: Math.max(0, Math.floor(requiredSeconds - normalizedEarnedSeconds)),
+    tiers,
+    milestones: REWARD_MILESTONES.map((milestone) => {
+      const tier = tierMap.get(milestone.percent);
+      const requiredTimeSeconds = tier?.requiredSeconds ?? milestoneTimeTarget(requiredSeconds, milestone.percent);
+      const timeReached = normalizedEarnedSeconds >= requiredTimeSeconds;
+      const equalsReached = normalizedTotalEquals >= milestone.requiredEquals;
+      const unlocked = timeReached && equalsReached;
+
+      return {
+        code: tier?.code ?? milestone.code,
+        percent: milestone.percent,
+        requiredEquals: milestone.requiredEquals,
+        requiredSeconds: requiredTimeSeconds,
+        rewardBacked: milestone.rewardBacked,
+        displayOnly: !milestone.rewardBacked,
+        unlocked,
+        redeemed: tier?.redeemed ?? false,
+        redeemedAt: tier?.redeemedAt ?? null,
+        status: tier?.status ?? (unlocked ? 'ready' : 'locked'),
+      };
+    }),
+  };
+
+  // The one progress number the CLI, the Mini and the dashboard all show (docs/reward-rules.md
+  // §10). `progress` is the same number as a fraction; until 2026-09-24 it was time alone.
+  summary.progressPercent = breakProgressPercent(summary);
+  summary.progress = summary.progressPercent / 100;
+  summary.nextBreak = nextBreakReminder(summary);
+  return summary;
+}
+
+function rewardSummaryFrom(state) {
+  const ledger = equalsLedgerFrom(state);
+  // The shared clock (docs/reward-rules.md §4); in a file from before it, the summed total.
+  const earnedSeconds = focusTimeFrom(state).activeSeconds;
+
+  return buildRewardSummary({
+    earnedSeconds,
+    totalEquals: ledger.total_equals,
+    ledger,
+  });
+}
+
+export function getDiskRewardSummary() {
+  return rewardSummaryFrom(loadState());
+}
+
+// Records tier changes in the stored ledger, under the state lock.
+function saveTierRecords(changes) {
+  updateState((state) => {
+    const ledger = storedEqualsLedger(state);
+
+    for (const [percent, change] of changes) {
+      updateTierRecord(ledger, percent, change);
+    }
+
+    ledger.last_updated_at = new Date().toISOString();
+  });
+}
+
+export function redeemReadyTiers(percent = null) {
+  const requestedPercent = percent === null ? null : normalizeTierPercent(percent);
+
+  if (percent !== null && !requestedPercent) {
+    return {redeemed: [], skipped: [], reward: getDiskRewardSummary()};
+  }
+
+  // Readiness is checked and the redeem recorded under one lock, so a tier is redeemed once.
+  return withStateLock(() => {
+    const reward = getDiskRewardSummary();
+    const now = new Date().toISOString();
+    const redeemed = [];
+    const skipped = [];
+
+    for (const tier of reward.tiers) {
+      if (requestedPercent && tier.percent !== requestedPercent) {
+        continue;
+      }
+
+      if (tier.status !== 'ready') {
+        skipped.push(tier);
+        continue;
+      }
+
+      redeemed.push({...tier, redeemed: true, redeemedAt: now, status: 'redeemed'});
+    }
+
+    if (redeemed.length > 0) {
+      saveTierRecords(redeemed.map((tier) => [tier.percent, (record) => ({...record, redeemed_at: now})]));
+    }
+
+    return {
+      redeemed,
+      skipped,
+      reward: getDiskRewardSummary(),
+    };
+  });
+}
+
+export function markTiersAnnounced(source, tiers) {
+  const normalizedSource = normalizeSource(source);
+
+  if (!normalizedSource || tiers.length === 0) {
+    return [];
+  }
+
+  const now = new Date().toISOString();
+  const announced = [];
+  const changes = [];
+
+  for (const tier of tiers) {
+    const percent = normalizeTierPercent(tier.percent);
+
+    if (!percent) {
+      continue;
+    }
+
+    changes.push([percent, (record) => ({...record, announced_at: {...record.announced_at, [normalizedSource]: now}})]);
+    announced.push({...tier, announcedAt: now});
+  }
+
+  if (changes.length > 0) {
+    saveTierRecords(changes);
+  }
+
+  return announced;
+}
+
+export function getReadyUnannouncedTiers(source) {
+  const normalizedSource = normalizeSource(source);
+
+  if (!normalizedSource) {
+    return [];
+  }
+
+  const state = loadState();
+  const records = tierRecordMap(equalsLedgerFrom(state));
+
+  return rewardSummaryFrom(state).tiers.filter((tier) => {
+    const record = records.get(tier.percent);
+
+    return tier.status === 'ready' && !record?.announced_at?.[normalizedSource];
+  });
+}

package/src/runner-installer.mjs

@@ -0,0 +1,153 @@
+import fs from 'node:fs';
+import {createRequire} from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import {fileURLToPath} from 'node:url';
+import {writeFileAtomically} from './atomic-file.mjs';
+import {CLI_PACKAGE_NAME, RUNNER_PATH_PARTS, shellQuote} from './integration-spec.mjs';
+
+const require = createRequire(import.meta.url);
+
+function packageRoot() {
+  return path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+}
+
+export function runnerPath() {
+  return path.join(os.homedir(), ...RUNNER_PATH_PARTS);
+}
+
+// The fallback runs this exact version, never whatever is newest on npm.
+function pinnedPackage() {
+  return `${CLI_PACKAGE_NAME}@${require(path.join(packageRoot(), 'package.json')).version}`;
+}
+
+function runnerScript() {
+  const node = shellQuote(process.execPath);
+  const bin = shellQuote(path.join(packageRoot(), 'bin', 'kitcode.mjs'));
+  const fallback = `npx -y ${shellQuote(pinnedPackage())}`;
+
+  return [
+    '#!/bin/sh',
+    `if [ -x ${node} ] && [ -f ${bin} ]; then`,
+    `  exec ${node} ${bin} "$@"`,
+    'fi',
+    '# The installed CLI is gone. Exit code 2 from the prompt hook blocks the prompt, so the hook',
+    '# exits 0 whatever the fallback does.',
+    'if [ "$1" = hook ]; then',
+    `  ${fallback} "$@"`,
+    '  exit 0',
+    'fi',
+    `exec ${fallback} "$@"`,
+    '',
+  ].join('\n');
+}
+
+// The runner for cmd.exe, which does what the runner does. `call`, because npx is itself a .cmd file,
+// and a .cmd file run without it never returns to the one that ran it: before 2026-09-29 nothing ran
+// after the fallback, and the hook's exit code was npx's. Each way out names its exit code: a bare
+// `exit /b` gave cmd /c's caller 0 whatever npx returned (the second Windows run). A % in a path is
+// doubled, as a .cmd file needs.
+function runnerCmdScript() {
+  const cmdText = (text) => text.replaceAll('%', '%%');
+  const binPath = cmdText(path.join(packageRoot(), 'bin', 'kitcode.mjs'));
+  const fallback = `call npx -y ${pinnedPackage()} %*`;
+
+  return [
+    '@echo off',
+    `if exist "${binPath}" goto run`,
+    'rem The installed CLI is gone. Exit code 2 from the prompt hook blocks the prompt, so the hook',
+    'rem exits 0 whatever the fallback does.',
+    'if /i "%~1"=="hook" goto hook',
+    fallback,
+    'exit /b %errorlevel%',
+    ':hook',
+    fallback,
+    'exit /b 0',
+    ':run',
+    `"${cmdText(process.execPath)}" "${binPath}" %*`,
+    'exit /b %errorlevel%',
+    '',
+  ].join('\r\n');
+}
+
+// The runner module, which the hook's command runs on Windows with the `node` on PATH
+// (integration-spec.mjs, hookCommandFor). It does what the runner does: the installed CLI, with the node
+// that installed it, or failing that this one; if the CLI is gone, this exact version from npm; and the
+// prompt hook exits 0 whatever happens, since exit code 2 blocks the user's prompt. On Windows npx is a
+// .cmd file, which only a shell runs, and cmd.exe splits and expands what it is given, so there only
+// arguments it takes as they are reach the fallback. Written on every platform, so that every platform's
+// tests run it.
+function runnerModuleScript() {
+  return [
+    '// KitCode\'s runner module, written by `kitcode <agent> on` (runner-installer.mjs).',
+    'import {spawnSync} from \'node:child_process\';',
+    'import {existsSync} from \'node:fs\';',
+    '',
+    `const node = ${JSON.stringify(process.execPath)};`,
+    `const bin = ${JSON.stringify(path.join(packageRoot(), 'bin', 'kitcode.mjs'))};`,
+    `const pinned = ${JSON.stringify(pinnedPackage())};`,
+    'const args = process.argv.slice(2);',
+    'const windows = process.platform === \'win32\';',
+    '',
+    '// With a shell, one command line and no arguments beside it, which Node would pass on unquoted.',
+    'function run(command, commandArgs) {',
+    '  const options = {stdio: \'inherit\', windowsHide: true};',
+    '  const result = commandArgs === undefined ? spawnSync(command, {...options, shell: true}) : spawnSync(command, commandArgs, options);',
+    '  return result.status ?? 1;',
+    '}',
+    '',
+    'let status;',
+    '',
+    'if (existsSync(bin)) {',
+    '  status = run(existsSync(node) ? node : process.execPath, [bin, ...args]);',
+    '} else if (!windows) {',
+    '  status = run(\'npx\', [\'-y\', pinned, ...args]);',
+    '} else if (args.every((arg) => /^[\\w@./:=,+-]+$/u.test(arg))) {',
+    '  status = run([\'npx\', \'-y\', pinned, ...args].join(\' \'));',
+    '} else {',
+    '  console.error(`KitCode is not installed any more. Install it again with: npm install -g ${pinned}`);',
+    '  status = 1;',
+    '}',
+    '',
+    'process.exit(args[0] === \'hook\' ? 0 : status);',
+    '',
+  ].join('\n');
+}
+
+// Rewrites a runner file only when its content changes, and atomically: the prompt hook may be
+// reading it at that moment, and a half-written script is a shell syntax error, exit 2.
+function writeRunnerFile(filePath, content, mode) {
+  try {
+    if (fs.readFileSync(filePath, 'utf8') === content && (fs.statSync(filePath).mode & 0o777) === mode) {
+      return;
+    }
+  } catch {
+    // Missing or unreadable: write it.
+  }
+
+  writeFileAtomically(filePath, content, {mode});
+}
+
+export function installRunner() {
+  const filePath = runnerPath();
+
+  fs.mkdirSync(path.dirname(filePath), {recursive: true});
+  writeRunnerFile(filePath, runnerScript(), 0o755);
+  writeRunnerFile(`${filePath}.cmd`, runnerCmdScript(), 0o644);
+  writeRunnerFile(`${filePath}.mjs`, runnerModuleScript(), 0o644);
+
+  return {
+    installed: true,
+    path: filePath,
+  };
+}
+
+export function runnerStatus() {
+  const filePath = runnerPath();
+
+  return {
+    installed: fs.existsSync(filePath),
+    path: filePath,
+  };
+}