@kitkat-vn/kitcode 0.2.0-staging.9 → 0.3.0-staging.16

package/src/companion-window.mjs

@@ -32,10 +32,10 @@ button{cursor:pointer}
 ${COMPANION_HIDE_CSS}
 `;
   const script = `
-const API_BASE=${JSON.stringify(apiBase)};const percent=document.getElementById('percent'),countValue=document.getElementById('countValue'),workedValue=document.getElementById('workedValue'),idleValue=document.getElementById('idleValue'),progressFill=document.getElementById('progressFill'),main=document.getElementById('main'),dashboardButton=document.getElementById('dashboardButton');
+const API_BASE=${JSON.stringify(apiBase)};const brandLabel=document.getElementById('brandLabel'),brandSecond=document.getElementById('brandSecond'),percent=document.getElementById('percent'),countValue=document.getElementById('countValue'),workedValue=document.getElementById('workedValue'),idleValue=document.getElementById('idleValue'),progressFill=document.getElementById('progressFill'),main=document.getElementById('main'),dashboardButton=document.getElementById('dashboardButton');
 function formatDuration(seconds){const totalSeconds=Math.max(0,Math.floor(Number(seconds)||0));if(totalSeconds<60)return totalSeconds+'s';const hours=Math.floor(totalSeconds/3600),minutes=Math.floor((totalSeconds%3600)/60);if(hours>0)return minutes>0?hours+'h '+minutes+'m':hours+'h';return minutes+'m'}
 function updateProgress(value){progressFill.style.width=Math.max(0,Math.min(100,Number(value)||0))+'%'}
-function render(summary){const reward=summary?.reward||{},global=summary?.global||{},value=Math.max(0,Math.min(100,Math.floor(Number(reward.progressPercent)||0)));percent.textContent=value+'%';countValue.textContent=String(Math.max(0,Math.floor(Number(reward.totalEquals)||0)));workedValue.textContent=formatDuration(global.totalActiveSeconds);idleValue.textContent=formatDuration(global.totalIdleSeconds);updateProgress(value);main.classList.remove('offline')}
+function render(summary){const reward=summary?.reward||{},global=summary?.global||{},value=Math.max(0,Math.min(100,Math.floor(Number(reward.progressPercent)||0))),cycle=Number.isSafeInteger(reward.cycle)&&reward.cycle>1?reward.cycle:null,ended=reward.campaign?.ended===true;brandSecond.textContent=ended?'ENDED':cycle===null?'COUNTER':'CYCLE '+cycle;brandLabel.setAttribute('aria-label',ended?'KitCode campaign ended':cycle===null?'KitCode Counter':'KitCode cycle '+cycle);percent.textContent=value+'%';countValue.textContent=String(Math.max(0,Math.floor(Number(reward.totalEquals)||0)));workedValue.textContent=formatDuration(global.totalActiveSeconds);idleValue.textContent=formatDuration(global.totalIdleSeconds);updateProgress(value);main.classList.remove('offline')}
 function offline(){percent.textContent='--';countValue.textContent='--';workedValue.textContent='--';idleValue.textContent='--';updateProgress(0);main.classList.add('offline')}
 async function sync(){try{const response=await fetch(API_BASE+'/api/summary');if(!response.ok)throw new Error();render(await response.json())}catch{offline()}}
 const hideButton=document.getElementById('hideButton');function hideCompanion(){try{const result=window.kitcodeCompanion?.hide?.();if(result&&typeof result.catch==='function')result.catch(()=>window.close());if(!result)window.close()}catch{window.close()}}
@@ -45,6 +45,12 @@ dashboardButton.addEventListener('click',()=>{if(window.kitcodeCompanion?.openDa
 sync();const events=new EventSource(API_BASE+'/api/events');events.addEventListener('summary',(event)=>{try{render(JSON.parse(event.data))}catch{offline()}});events.onerror=offline;
 `;
 
+  // Since 2026-10-22 its label names the cycle counted in from cycle 2 on, "KITCODE CYCLE 2" where it says "KITCODE COUNTER",
+  // on the same two lines, so that the counters keep their room (docs/reward-rules.md §2, "Cycles"); its percent is that
+  // cycle's, as the summary's is. Since 2026-10-23 (tracking/2-cli; D4 of docs/plans/2026-10-22-server-tracking-config.md) it
+  // reads "KITCODE ENDED" once the summary says the campaign has ended, `reward.campaign.ended`, whatever the cycle; the counters
+  // go on, as counting does.
+  //
   // The button opens the dashboard, where each milestone reached shows its message: "See more". Until 2026-10-01 it was
   // "Show code", and lit while a 10–30 % code was ready to show there; the break codes are gone (the operator's decision
   // 6), and a milestone reached stays reached, so nothing lights it now. The Mini cannot show a message itself: the
@@ -55,5 +61,5 @@ sync();const events=new EventSource(API_BASE+'/api/events');events.addEventListe
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="${contentSecurityPolicy({script, style, connect: [apiBase || "'self'"]})}"><meta name="viewport" content="width=device-width, initial-scale=1">
 <title>KitCode Counter</title><style>${style}</style></head>
-<body><main class="widget-window" id="main" data-testid="companion-counter-bar">${renderCompanionTitleBar()}<div class="widget-body"><div class="brand-label" aria-label="KitCode Counter">KITCODE<br>COUNTER</div><strong class="percentage" id="percent" data-testid="mini-percent">--</strong><div class="progress-box" aria-hidden="true"><div class="progress-fill" id="progressFill"><div class="progress-row">========================</div><div class="progress-row">========================</div></div></div><div class="metrics-group" aria-label="KitCode counters"><div class="metric-item"><div class="metric-value" id="countValue" data-testid="mini-count">--</div><div class="metric-label">= COUNT</div></div><div class="metric-item"><div class="metric-value" id="workedValue" data-testid="mini-worked">--</div><div class="metric-label">WORKED</div></div><div class="metric-item"><div class="metric-value" id="idleValue" data-testid="mini-idle">--</div><div class="metric-label">IDLE</div></div></div><button class="claim-btn" id="dashboardButton" data-testid="companion-dashboard" type="button" title="Open the dashboard, where each milestone reached shows its message">See more</button></div></main><script>${script}</script></body></html>`;
+<body><main class="widget-window" id="main" data-testid="companion-counter-bar">${renderCompanionTitleBar()}<div class="widget-body"><div class="brand-label" id="brandLabel" aria-label="KitCode Counter" data-testid="mini-brand">KITCODE<br><span id="brandSecond">COUNTER</span></div><strong class="percentage" id="percent" data-testid="mini-percent">--</strong><div class="progress-box" aria-hidden="true"><div class="progress-fill" id="progressFill"><div class="progress-row">========================</div><div class="progress-row">========================</div></div></div><div class="metrics-group" aria-label="KitCode counters"><div class="metric-item"><div class="metric-value" id="countValue" data-testid="mini-count">--</div><div class="metric-label">= COUNT</div></div><div class="metric-item"><div class="metric-value" id="workedValue" data-testid="mini-worked">--</div><div class="metric-label">WORKED</div></div><div class="metric-item"><div class="metric-value" id="idleValue" data-testid="mini-idle">--</div><div class="metric-label">IDLE</div></div></div><button class="claim-btn" id="dashboardButton" data-testid="companion-dashboard" type="button" title="Open the dashboard, where each milestone reached shows its message">See more</button></div></main><script>${script}</script></body></html>`;
 }

package/src/cors.mjs

@@ -1,5 +1,7 @@
 // The origins a tracker allows with nothing configured: the hosted dashboard's and the local development
-// servers'. Pinned by local-api.test.mjs.
+// servers'. Pinned by local-api.test.mjs. Since 2026-10-22 (production/1-cli) the hosted dashboard is production's,
+// https://kitcode.vn, where it was https://kitcode.vercel.app, the previous project's site; a tester build's copy has the
+// staging site's in its place (scripts/tester-build.mjs).
 export const DEFAULT_ALLOWED_ORIGINS = new Set([
   // The staging dashboard this tester build is for (scripts/tester-build.mjs in the repository).
   "https://staging.kitcode.vn",

package/src/cycle-receipt.mjs

@@ -0,0 +1,97 @@
+import crypto from 'node:crypto';
+
+// A cycle receipt (docs/backend.md, "The cycle receipt"; the plan of 2026-10-21, phase 2): what the claim backend signs once it
+// has issued a voucher, and the dashboard hands to this tracker, so that the tracker begins the next cycle, whose milestones
+// count fresh from that moment (decision 1). Its words are the server's: the install id the claim's bundle carried, the cycle
+// the server counted for it, the claim's id and when its voucher was issued, signed with an Ed25519 key that exists on the
+// claim backend's server alone. This file only reads one, with the matching public key, which a tester build carries
+// (integration-spec.mjs, CYCLE_RECEIPT_PUBLIC_KEY). Pure: it reads no file, keeps nothing, and asks nothing of the network;
+// whether the receipt is this install's, and of the cycle it is in, is the caller's to judge, against the record
+// (milestones-reached.mjs, beginNextCycle).
+//
+//   <payload>.<signature>
+//
+// `payload` is base64url (no padding) of the UTF-8 JSON {"v":1,"installId":…,"cycle":…,"claimId":…,"issuedAt":…}, those five
+// fields alone; `signature`, base64url of the 64-byte Ed25519 signature of the ASCII text `kitcode-cycle-receipt-1.` followed
+// by `payload` as it stands. The signature is checked over the bytes as they came, before anything in them is read: nothing is
+// put in a canonical form, and no field the server did not sign is read. The text names what it is, so that the key signs
+// nothing else that could pass for one. The server's side is apps/api/src/cycle-receipts.ts.
+
+export const CYCLE_RECEIPT_CONTEXT = 'kitcode-cycle-receipt-1.';
+
+// The longest text read: a receipt is about 300 characters.
+export const MAX_CYCLE_RECEIPT_LENGTH = 1024;
+
+const RECEIPT_TEXT = /^([A-Za-z0-9_-]{16,900})\.([A-Za-z0-9_-]{86})$/u;
+const PUBLIC_KEY_TEXT = /^[A-Za-z0-9_-]{43}$/u;
+const INSTALL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const CLAIM_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+const PAYLOAD_KEYS = ['v', 'installId', 'cycle', 'claimId', 'issuedAt'];
+
+function isInstant(value) {
+  if (typeof value !== 'string' || !INSTANT.test(value)) {
+    return false;
+  }
+
+  const time = Date.parse(value);
+  return Number.isFinite(time) && new Date(time).toISOString() === value;
+}
+
+// The public key a build carries: base64url of its 32 raw bytes, the JWK's `x`. Null when it is not one.
+export function cycleReceiptKey(text) {
+  if (typeof text !== 'string' || !PUBLIC_KEY_TEXT.test(text)) {
+    return null;
+  }
+
+  try {
+    const key = crypto.createPublicKey({key: {kty: 'OKP', crv: 'Ed25519', x: text}, format: 'jwk'});
+    return key.asymmetricKeyType === 'ed25519' && key.export({format: 'jwk'}).x === text ? key : null;
+  } catch {
+    return null;
+  }
+}
+
+// Reads `text` with `publicKey` (a KeyObject, cycleReceiptKey's): {ok: true, receipt: {installId, cycle, claimId, issuedAt}},
+// or {ok: false, problem}: 'unreadable', not the shape of a receipt, or its signed words not a receipt's; 'signature', not
+// signed with the key's pair.
+export function readCycleReceipt(text, publicKey) {
+  const parts = typeof text === 'string' && text.length <= MAX_CYCLE_RECEIPT_LENGTH ? RECEIPT_TEXT.exec(text) : null;
+
+  if (parts === null) {
+    return {ok: false, problem: 'unreadable'};
+  }
+
+  const [, payload, signature] = parts;
+  let signed;
+
+  try {
+    signed = crypto.verify(null, Buffer.from(`${CYCLE_RECEIPT_CONTEXT}${payload}`, 'ascii'), publicKey, Buffer.from(signature, 'base64url'));
+  } catch {
+    signed = false;
+  }
+
+  if (!signed) {
+    return {ok: false, problem: 'signature'};
+  }
+
+  let words;
+
+  try {
+    words = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+  } catch {
+    return {ok: false, problem: 'unreadable'};
+  }
+
+  const shaped = words !== null && typeof words === 'object' && !Array.isArray(words)
+    && Object.keys(words).length === PAYLOAD_KEYS.length && PAYLOAD_KEYS.every((key) => Object.hasOwn(words, key))
+    && words.v === 1
+    && typeof words.installId === 'string' && INSTALL_ID.test(words.installId)
+    && Number.isSafeInteger(words.cycle) && words.cycle >= 1
+    && typeof words.claimId === 'string' && CLAIM_ID.test(words.claimId)
+    && isInstant(words.issuedAt);
+
+  return shaped
+    ? {ok: true, receipt: {installId: words.installId, cycle: words.cycle, claimId: words.claimId, issuedAt: words.issuedAt}}
+    : {ok: false, problem: 'unreadable'};
+}

package/src/fonts/jetbrains-mono/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/hook-prompt.mjs

@@ -7,6 +7,7 @@ import {getDiskRewardSummary, getReadyUnannouncedTiers, markTiersAnnounced} from
 import {STORE_DIR, StateLockError, withStateLock} from './store.mjs';
 import {isProcessAlive, readTrackerRecord} from './tracker-instance.mjs';
 import {problemSentences, TRACKER_STOPPED} from './tracker-problems.mjs';
+import {campaignEnded, trackingConfigInForce} from './tracking-config.mjs';
 
 export const HOOK_LOG_PATH = path.join(STORE_DIR, 'hook.log');
 
@@ -104,11 +105,21 @@ function notify(title, message) {
 // A milestone reached is said in neutral words (the operator's decisions 5 and 6 of 2026-10-01): its message, from the
 // campaign, is on the dashboard, and no milestone is a reward ready, or a code. Until then this said "Reward ready at",
 // and the announcement below "KitCode break code ready".
+//
+// Since 2026-10-22 (rewards/3-repeat-vouchers, phase 2) the milestones are those of the cycle counted in (reward.mjs): from cycle
+// 2 on the context names it, "KitCode progress (cycle 2): …", and the milestones it lists and announces are that cycle's; the =
+// and the time are the totals, which keep counting. Cycle 1 reads as it always has. The cycle is the record's, read with the
+// rest of the file: no receipt is checked here (hard rule 7).
+function cycleOf(reward) {
+  return Number.isSafeInteger(reward?.cycle) && reward.cycle > 1 ? reward.cycle : null;
+}
+
 function progressContextFor(reward) {
   const nextBreak = reward.nextBreak ?? nextBreakReminder(reward);
   const ready = reward.milestones.filter((entry) => entry.status === 'ready' && !entry.redeemed);
+  const cycle = cycleOf(reward);
   const parts = [
-    `KitCode progress: ${reward.totalEquals} = counted, ${formatBreakDuration(reward.earnedSeconds)} active.`,
+    `KitCode progress${cycle === null ? '' : ` (cycle ${cycle})`}: ${reward.totalEquals} = counted, ${formatBreakDuration(reward.earnedSeconds)} active.`,
   ];
 
   if (ready.length > 0) {
@@ -140,7 +151,8 @@ function hookOutputFor({tiers = [], reward = null}) {
     };
   }
 
-  const labels = tiers.map((tier) => `${tier.percent}%`).join(', ');
+  const cycle = cycleOf(reward);
+  const labels = `${tiers.map((tier) => `${tier.percent}%`).join(', ')}${cycle === null ? '' : `, cycle ${cycle}`}`;
   const command = 'kitcode dashboard';
   const additionalContext = [
     progressContext,
@@ -198,6 +210,14 @@ export async function runPromptHook({source}) {
       return;
     }
 
+    // After the campaign's end, by this computer's clock (since 2026-10-23, tracking/2-cli; D4 of
+    // docs/plans/2026-10-22-server-tracking-config.md), the hook adds nothing: no progress, no milestone, no notification, and nothing
+    // written. The end is the last good copy's, read from disk with its bounds checked and no signature: the hook never fetches
+    // (src/tracking-config.mjs; hard rule 7). Counting goes on in the tracker, so an end moved later brings every word back.
+    if (campaignEnded(trackingConfigInForce())) {
+      return;
+    }
+
     const {reward, announced} = collectPromptProgress(source);
 
     if (announced.length === 0) {
@@ -206,7 +226,8 @@ export async function runPromptHook({source}) {
     }
 
     const label = announced.map((tier) => `${tier.percent}%`).join(', ');
-    notify('KitCode milestone reached', `Milestone ${label} unlocked. Open kitcode dashboard.`);
+    const cycle = cycleOf(reward);
+    notify('KitCode milestone reached', `Milestone ${label}${cycle === null ? '' : ` of cycle ${cycle}`} unlocked. Open kitcode dashboard.`);
     process.stdout.write(`${JSON.stringify(hookOutputFor({tiers: announced, reward}))}\n`);
   } catch (error) {
     failure = error;