@kitkat-vn/kitcode 0.2.0-staging.3

package/src/next-break-reminder.mjs

@@ -0,0 +1,78 @@
+import {milestoneProgressPercent} from './break-progress.mjs';
+
+export function formatBreakDuration(seconds) {
+  const totalSeconds = Math.max(0, Math.floor(Number(seconds) || 0));
+
+  if (totalSeconds < 60) {
+    return `${totalSeconds}s`;
+  }
+
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+
+  if (hours > 0) {
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  }
+
+  return `${minutes}m`;
+}
+
+export function equalsToBreakCopy(equalsLeft) {
+  const remaining = Math.max(0, Math.floor(Number(equalsLeft) || 0));
+  return remaining === 0 ? '= done' : `${remaining} = to break`;
+}
+
+export function timeToBreakCopy(secondsLeft, durationLeft = formatBreakDuration(secondsLeft)) {
+  const remaining = Math.max(0, Math.floor(Number(secondsLeft) || 0));
+  return remaining === 0 ? 'time done' : `${durationLeft} to break`;
+}
+
+export function findNextBreakMilestone(milestones = []) {
+  const list = Array.isArray(milestones) ? milestones : [];
+
+  return list.find((milestone) => (
+    !milestone.redeemed &&
+    milestone.status !== 'ready' &&
+    milestone.status !== 'redeemed' &&
+    !milestone.unlocked
+  )) ?? list.find((milestone) => !milestone.redeemed && milestone.status === 'locked') ?? null;
+}
+
+export function nextBreakReminder(reward) {
+  if (!reward || typeof reward !== 'object') {
+    return null;
+  }
+
+  const milestone = findNextBreakMilestone(reward.milestones);
+  if (!milestone) {
+    return null;
+  }
+
+  const earnedSeconds = Math.max(0, Number(reward.earnedSeconds) || 0);
+  const totalEquals = Math.max(0, Number(reward.totalEquals) || 0);
+  const requiredSeconds = Math.max(0, Number(milestone.requiredSeconds) || 0);
+  const requiredEquals = Math.max(0, Number(milestone.requiredEquals) || 0);
+  // Floored, so it reads 100 only once the milestone is unlocked (docs/reward-rules.md §10).
+  const progressPercent = milestoneProgressPercent(reward, milestone);
+  const equalsLeft = Math.max(0, requiredEquals - totalEquals);
+  const secondsLeft = Math.max(0, requiredSeconds - earnedSeconds);
+  const durationLeft = formatBreakDuration(secondsLeft);
+  const almost = progressPercent >= 80;
+  const equalsCopy = equalsToBreakCopy(equalsLeft);
+  const timeCopy = timeToBreakCopy(secondsLeft, durationLeft);
+  const shortLine = `${equalsCopy} · ${timeCopy}`;
+
+  return {
+    percent: milestone.percent,
+    equalsLeft,
+    secondsLeft,
+    progressPercent,
+    almost,
+    durationLeft,
+    equalsCopy,
+    timeCopy,
+    shortLine,
+    mentionLine: `Break next: ${shortLine} (${milestone.percent}%).`,
+    metaLine: shortLine,
+  };
+}

package/src/onboarding-electron.mjs

@@ -0,0 +1,240 @@
+import fs from 'node:fs';
+import {spawn} from 'node:child_process';
+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 {DASHBOARD_URL} from './integration-spec.mjs';
+import {onboardingPreferences, saveOnboardingPreferences, STORE_DIR} from './store.mjs';
+import {resolveSetupPlatform} from './onboarding-platform.mjs';
+import {renderOnboardingWindow} from './onboarding-window.mjs';
+import {keepWindowOnItsPage} from './window-guards.mjs';
+
+const sourceDirectory = path.dirname(fileURLToPath(import.meta.url));
+const preloadPath = path.join(sourceDirectory, 'onboarding-preload.cjs');
+const cliEntry = process.env.KITCODE_CLI_ENTRY;
+const companionEntry = path.join(sourceDirectory, 'companion-electron.mjs');
+const host = process.env.KITCODE_HOST ?? '127.0.0.1';
+const port = process.env.KITCODE_PORT ?? '4747';
+let window;
+let pendingFocus = false;
+const gotSingleInstanceLock = app.requestSingleInstanceLock();
+
+function focusSetupWindow(platform) {
+  if (!window || window.isDestroyed()) {
+    return;
+  }
+  if (window.isMinimized()) {
+    window.restore();
+  }
+  if (platform === 'darwin') {
+    app.dock?.show();
+  }
+  window.show();
+  window.focus();
+}
+
+if (!gotSingleInstanceLock) {
+  app.quit();
+  process.exit(0);
+} else {
+  app.on('second-instance', () => {
+    if (window && !window.isDestroyed()) {
+      focusSetupWindow(resolveSetupPlatform());
+    } else {
+      pendingFocus = true;
+    }
+  });
+}
+
+function validFolders(folders) {
+  return [...new Set((Array.isArray(folders) ? folders : []).map((folder) => path.resolve(String(folder))))]
+    .filter((folder) => {
+      try { return fs.statSync(folder).isDirectory(); } catch { return false; }
+    });
+}
+
+function runCli(args) {
+  return new Promise((resolve) => {
+    if (!cliEntry) return resolve(false);
+    const child = spawn(process.env.KITCODE_NODE_PATH ?? process.execPath, [cliEntry, ...args], {
+      detached: true,
+      env: {
+        ...process.env,
+        KITCODE_NO_OPEN: '1',
+        NO_COLOR: process.env.NO_COLOR ?? '1',
+      },
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.once('error', () => resolve(false));
+    child.once('exit', (code) => resolve(code === 0));
+    child.unref();
+  });
+}
+
+function openCompanion() {
+  const child = spawn(process.execPath, [companionEntry], {
+    detached: true, stdio: 'ignore',
+    env: {
+      ...process.env,
+      KITCODE_HOST: host,
+      KITCODE_PORT: port,
+      KITCODE_DASHBOARD_URL: DASHBOARD_URL,
+      KITCODE_NO_OPEN: '1',
+    },
+    windowsHide: true,
+  });
+  child.unref();
+}
+
+function onboardingHtmlPath(platform) {
+  const cacheDir = path.join(STORE_DIR, 'cache');
+  fs.mkdirSync(cacheDir, {recursive: true});
+  const htmlPath = path.join(cacheDir, 'welcome.html');
+  fs.writeFileSync(htmlPath, renderOnboardingWindow(platform), 'utf8');
+  return htmlPath;
+}
+
+function loadOnboardingContent(window, platform) {
+  try {
+    window.loadFile(onboardingHtmlPath(platform));
+    return;
+  } catch {
+    // Fall back when local cache is unavailable.
+  }
+
+  window.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(renderOnboardingWindow(platform))}`);
+}
+
+function initialSuggestedProjects() {
+  const raw = process.env.KITCODE_INITIAL_PROJECT?.trim();
+  if (!raw) {
+    return [];
+  }
+
+  const project = resolveInitialProjectSuggestion(raw);
+  return project ? [project] : [];
+}
+
+function setupWindowOptions(platform) {
+  return {
+    width: 960,
+    height: 640,
+    resizable: false,
+    maximizable: false,
+    movable: true,
+    center: true,
+    show: false,
+    frame: false,
+    transparent: true,
+    hasShadow: false,
+    backgroundColor: '#00000000',
+    title: 'Welcome to KitCode',
+    webPreferences: {preload: preloadPath, contextIsolation: true, nodeIntegration: false, sandbox: true},
+  };
+}
+
+app.whenReady().then(() => {
+  if (!gotSingleInstanceLock) {
+    return;
+  }
+
+  const platform = resolveSetupPlatform(process.env.KITCODE_SETUP_PLATFORM || process.platform);
+  nativeTheme.themeSource = 'dark';
+  if (platform === 'darwin') {
+    app.dock?.hide();
+  }
+  window = new BrowserWindow(setupWindowOptions(platform));
+  keepWindowOnItsPage(window);
+  // Project records carry absolute paths: only Welcome's own page gets them.
+  ipcMain.handle('kitcode:onboarding-initial-state', (event) => {
+    if (event.sender !== window.webContents) return {ok: false, error: 'Invalid setup request.', projects: [], suggestedProjects: []};
+    return {
+      ...onboardingPreferences(),
+      projects: listProjectRecords(),
+      suggestedProjects: initialSuggestedProjects(),
+    };
+  });
+  ipcMain.handle('kitcode:onboarding-select-folders', async (event) => {
+    if (event.sender !== window.webContents) return {canceled: true, paths: []};
+    const result = await dialog.showOpenDialog({properties: ['openDirectory', 'multiSelections', 'createDirectory']});
+    const paths = validFolders(result.filePaths);
+    return {canceled: result.canceled, paths, projects: describeProjects(paths)};
+  });
+  ipcMain.handle('kitcode:onboarding-submit', async (event, input) => {
+    if (event.sender !== window.webContents) return {ok: false, error: 'Invalid setup request.'};
+    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.'}; }
+    const selection = {autoTrack: input?.autoTrack === true, companionView: 'mini'};
+    if (selection.autoTrack && !(await runCli(['track', '--host', host, '--port', port]))) {
+      saveOnboardingPreferences({...selection, completed: false});
+      return {
+        ok: false,
+        error: 'Projects were saved, but the tracker could not start. Free the local port and retry.',
+        projects: listProjectRecords(),
+      };
+    }
+    const preferences = saveOnboardingPreferences(selection);
+    const projects = listProjectRecords();
+    setTimeout(() => {
+      openCompanion();
+      window?.close();
+    }, 450);
+    return {ok: true, projects};
+  });
+  ipcMain.handle('kitcode:onboarding-remove-project', async (event, projectId) => {
+    if (event.sender !== window.webContents) return {ok: false, error: 'Invalid setup request.'};
+    if (!projectId) return {ok: false, error: 'Project not found.'};
+    try {
+      const removed = removeProject(projectId);
+      if (!removed) return {ok: false, error: 'Project not found.'};
+      return {ok: true, projects: listProjectRecords()};
+    } catch {
+      return {ok: false, error: 'KitCode could not remove that project.'};
+    }
+  });
+  ipcMain.handle('kitcode:onboarding-close', (event) => {
+    if (event.sender === window.webContents) window.close();
+    return {closed: true};
+  });
+
+  let revealed = false;
+  let readyToShow = false;
+  let contentLoaded = false;
+
+  function revealSetupWindow() {
+    if (revealed || window.isDestroyed() || !readyToShow || !contentLoaded) {
+      return;
+    }
+    revealed = true;
+    focusSetupWindow(platform);
+    pendingFocus = false;
+  }
+
+  window.webContents.on('preload-error', (_event, preloadScript, error) => {
+    console.error(`KitCode Welcome preload failed (${preloadScript}):`, error?.message ?? error);
+  });
+  window.webContents.on('did-fail-load', (_event, code, description, url) => {
+    console.error(`KitCode Welcome failed to load (${code}):`, description, url);
+  });
+  window.once('ready-to-show', () => {
+    readyToShow = true;
+    revealSetupWindow();
+  });
+  window.webContents.once('did-finish-load', () => {
+    contentLoaded = true;
+    revealSetupWindow();
+  });
+  loadOnboardingContent(window, platform);
+});
+
+app.on('window-all-closed', () => {
+  ipcMain.removeHandler('kitcode:onboarding-initial-state');
+  ipcMain.removeHandler('kitcode:onboarding-select-folders');
+  ipcMain.removeHandler('kitcode:onboarding-submit');
+  ipcMain.removeHandler('kitcode:onboarding-remove-project');
+  ipcMain.removeHandler('kitcode:onboarding-close');
+  app.quit();
+});

package/src/onboarding-platform.mjs

@@ -0,0 +1,50 @@
+const PLATFORM_CHROME = {
+  darwin: {
+    id: 'darwin',
+    marker: 'macos',
+    chromeClass: 'title-bar',
+  },
+  win32: {
+    id: 'win32',
+    marker: 'windows',
+    chromeClass: 'title-bar',
+  },
+  linux: {
+    id: 'linux',
+    marker: 'linux',
+    chromeClass: 'title-bar',
+  },
+};
+
+const PLATFORM_ALIASES = {
+  darwin: 'darwin',
+  macos: 'darwin',
+  mac: 'darwin',
+  win32: 'win32',
+  windows: 'win32',
+  win: 'win32',
+  linux: 'linux',
+};
+
+export function normalizeSetupPlatform(value) {
+  if (value == null || value === '') {
+    return null;
+  }
+  return PLATFORM_ALIASES[String(value).trim().toLowerCase()] ?? null;
+}
+
+export function resolveSetupPlatform(platform = process.platform) {
+  return normalizeSetupPlatform(platform) ?? 'linux';
+}
+
+export function setupPlatformTheme(platform) {
+  return PLATFORM_CHROME[resolveSetupPlatform(platform)];
+}
+
+export function renderPlatformChrome(theme = setupPlatformTheme()) {
+  return `<div class="${theme.chromeClass}" title="Drag window">
+    <button class="dot filled dot-close" id="closeButton" type="button" aria-label="Close setup" title="Close"></button>
+    <span class="dot" aria-hidden="true"></span>
+    <span class="dot" aria-hidden="true"></span>
+  </div>`;
+}

package/src/onboarding-preload.cjs

@@ -0,0 +1,19 @@
+const {contextBridge, ipcRenderer} = require('electron');
+
+contextBridge.exposeInMainWorld('kitcodeOnboarding', {
+  selectFolders() {
+    return ipcRenderer.invoke('kitcode:onboarding-select-folders');
+  },
+  submit(input) {
+    return ipcRenderer.invoke('kitcode:onboarding-submit', input);
+  },
+  removeProject(projectId) {
+    return ipcRenderer.invoke('kitcode:onboarding-remove-project', projectId);
+  },
+  initialState() {
+    return ipcRenderer.invoke('kitcode:onboarding-initial-state');
+  },
+  close() {
+    return ipcRenderer.invoke('kitcode:onboarding-close');
+  },
+});