syndes 0.1.0

package/src/install.mjs

@@ -0,0 +1,95 @@
+/**
+ * Install: copy to a stable home, mint the chain key, open the ledger, wire hooks.
+ *
+ * The copy matters. Pointing settings.json at wherever this is running from
+ * means pointing it at the npm cache under `npx` — which npm prunes — and a hook
+ * whose script has vanished is a broken session on every tool call.
+ *
+ * Order matters too: key and directories first, then the genesis record, then
+ * the hooks. Wiring hooks before the ledger can accept records means the first
+ * tool call after install writes into nothing.
+ *
+ * Idempotent. Re-running repairs drift rather than duplicating anything.
+ */
+
+import { cpSync, existsSync, rmSync, readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import {
+  packageRoot, installDir, installedHookScript, isInstalledCopy,
+  ensureDataDirs, displayPath,
+} from '../runtime/paths.mjs';
+import { ensureKey } from '../ledger/keys.mjs';
+import { append } from '../ledger/append.mjs';
+import { draft, KIND } from '../ledger/schema.mjs';
+import { height } from '../ledger/read.mjs';
+import { installHooks, hookCommand, HOOK_EVENTS } from './settings.mjs';
+import { isSupportedPlatform, platformName } from '../runtime/platform.mjs';
+
+/** Never shipped into the install: tests, VCS, and anything npm would not publish. */
+const SKIP = new Set(['node_modules', '.git', 'test', 'coverage', '.github', '.DS_Store']);
+
+export async function install({ repair = false } = {}) {
+  const steps = [];
+
+  if (!isSupportedPlatform) {
+    throw new Error(`${platformName} is not supported — macOS, Windows and Linux only`);
+  }
+
+  // 1. The stable home.
+  if (isInstalledCopy) {
+    steps.push({ step: 'copy', skipped: true, detail: 'already running from the install directory' });
+  } else {
+    copyPackage();
+    steps.push({ step: 'copy', detail: displayPath(installDir) });
+  }
+
+  // 2. Storage and the key, before anything tries to write a record.
+  ensureDataDirs();
+  const { keyId, created } = ensureKey();
+  steps.push({ step: 'key', detail: created ? `minted ${keyId}` : `existing ${keyId}` });
+
+  // 3. Open the chain. The install itself is the first thing it records.
+  const before = height();
+  await append([draft(KIND.INSTALL, {
+    data: {
+      version: version(),
+      node: process.version,
+      platform: process.platform,
+      events: HOOK_EVENTS,
+      repair,
+    },
+    ...(before.seq < 0 ? { key: keyId } : {}),
+  })]);
+  steps.push({ step: 'ledger', detail: before.seq < 0 ? 'chain opened' : `chain at ${height().seq}` });
+
+  // 4. Hooks last.
+  const { backup, events } = installHooks(hookCommand(installedHookScript));
+  steps.push({ step: 'hooks', detail: `${events.length} events`, backup });
+
+  return { steps, installDir, events, keyId };
+}
+
+function copyPackage() {
+  // Remove first: cpSync merges, so an upgrade that deletes a file would leave
+  // the old one behind to be imported by a stale path somewhere.
+  if (existsSync(installDir)) rmSync(installDir, { recursive: true, force: true });
+
+  cpSync(packageRoot, installDir, {
+    recursive: true,
+    dereference: true,
+    filter: (source) => {
+      const relative = resolve(source).slice(resolve(packageRoot).length + 1);
+      if (!relative) return true;
+      const [top] = relative.split(sep);
+      return !SKIP.has(top);
+    },
+  });
+}
+
+function version() {
+  try {
+    return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
+  } catch {
+    return null;
+  }
+}

package/src/open.mjs

@@ -0,0 +1,23 @@
+/**
+ * Open a URL in the default browser.
+ *
+ * Returns false rather than throwing when there is no browser — the caller then
+ * prints the URL, which is the actually useful outcome on a headless box.
+ */
+
+import { spawn } from 'node:child_process';
+import { openArgs } from '../runtime/platform.mjs';
+import { debug } from '../runtime/log.mjs';
+
+export function openUrl(url) {
+  const target = openArgs(url);
+  if (!target) return false;
+
+  try {
+    spawn(target.command, target.args, { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+    return true;
+  } catch (error) {
+    debug('open failed', error.message);
+    return false;
+  }
+}

package/src/report.mjs

@@ -0,0 +1,120 @@
+/**
+ * The terminal digest — day, week, month.
+ *
+ * Same numbers as the dashboard by construction, because both call
+ * analytics/index.mjs. Nothing here computes a metric.
+ */
+
+import {
+  bold, grey, cyan, green, red, yellow, write, rule, table, bar, sparkline,
+  compact, usd, duration, percent, width, DOT,
+} from './term.mjs';
+import { overview } from '../analytics/index.mjs';
+import { evaluate } from '../practices/engine.mjs';
+import { nameFor } from '../collect/projects.mjs';
+
+export async function report(spec = '7d', { practices = true } = {}) {
+  const data = await overview(spec);
+  const { headline, previousHeadline: before, score, metrics, cost } = data;
+
+  write();
+  write(`${bold('syndes')} ${grey(DOT)} ${data.range.label}`);
+  write(rule(width()));
+
+  // ── The score ─────────────────────────────────────────────────────────────
+  if (score.total === null) {
+    write(`${grey('not enough recorded yet to score — keep going')}`);
+  } else {
+    const delta = data.scoreDelta;
+    const arrow = delta === null ? '' : delta > 0 ? green(`+${delta}`) : delta < 0 ? red(String(delta)) : grey('0');
+    write(`${bold('score')}  ${bar(score.total / 100, 28)}  ${bold(String(score.total))}${grey('/100')} ${arrow} ${grey(`(${score.confidence} confidence)`)}`);
+    write();
+    for (const pillar of score.pillars) {
+      const value = pillar.score === null ? grey('  —') : String(pillar.score).padStart(3);
+      write(`  ${value}  ${bar((pillar.score ?? 0) / 100, 14, tint(pillar.score))}  ${pillar.label}`);
+    }
+  }
+
+  // ── Headline ──────────────────────────────────────────────────────────────
+  write();
+  write(table([
+    [grey('sessions'), String(headline.sessions), delta(headline.sessions, before.sessions)],
+    [grey('prompts'), String(headline.prompts), delta(headline.prompts, before.prompts)],
+    [grey('tool calls'), compact(headline.toolCalls), delta(headline.toolCalls, before.toolCalls)],
+    [grey('active time'), duration(headline.activeMs), grey(`of ${duration(headline.wallMs)} open`)],
+    [grey('tokens'), compact(headline.tokens), grey(`${percent(headline.cacheHitRate)} from cache`)],
+    [grey('cost'), usd(headline.usd) + (cost.estimated ? grey('*') : ''), delta(headline.usd, before.usd, usd)],
+    [grey('files changed'), String(headline.files), headline.commits ? grey(`${headline.commits} commits`) : ''],
+    [grey('interruptions'), String(headline.blocks), headline.compacts ? grey(`${headline.compacts} compactions`) : ''],
+  ], { align: ['left', 'right', 'left'] }).map((line) => `  ${line}`).join('\n'));
+
+  if (cost.estimated) write(grey(`  * priced from the ${cost.tableVersion} table by model family`));
+
+  // ── Trend ─────────────────────────────────────────────────────────────────
+  if (data.series.length > 1) {
+    write();
+    write(`  ${grey('activity')}  ${cyan(sparkline(data.series.map((day) => day.toolCalls)))}  ${grey(`${data.series[0].day} to ${data.series.at(-1).day}`)}`);
+    write(`  ${grey('by hour ')}  ${cyan(sparkline(data.hours))}  ${grey('00 to 23')}`);
+  }
+
+  // ── Where the time went ───────────────────────────────────────────────────
+  const families = Object.entries(metrics.tools.byFamily ?? {}).sort((a, b) => b[1] - a[1]).slice(0, 6);
+  if (families.length) {
+    write();
+    write(`  ${bold('tools')}`);
+    const total = families.reduce((sum, [, count]) => sum + count, 0);
+    write(table(families.map(([family, count]) => [
+      grey(family), bar(count / total, 16), String(count),
+    ]), { align: ['left', 'left', 'right'] }).map((line) => `  ${line}`).join('\n'));
+  }
+
+  // ── What to fix ───────────────────────────────────────────────────────────
+  if (practices) {
+    const findings = await evaluate();
+    write();
+    if (!findings.length) {
+      write(`  ${green('nothing flagged')} ${grey('— practice rules found no pattern worth changing')}`);
+    } else {
+      write(`  ${bold('worth changing')}`);
+      for (const finding of findings.slice(0, 3)) {
+        write(`  ${severity(finding.severity)} ${bold(finding.title)}${finding.muted ? grey(' (muted)') : ''}`);
+        write(`     ${grey(finding.evidence)}`);
+        write(`     ${cyan('→')} ${finding.fix}`);
+      }
+      if (findings.length > 3) write(grey(`     …and ${findings.length - 3} more — syndes practices`));
+    }
+  }
+
+  write();
+  return data;
+}
+
+function tint(score) {
+  if (score === null) return grey;
+  if (score >= 75) return green;
+  if (score >= 50) return yellow;
+  return red;
+}
+
+function severity(level) {
+  return level >= 3 ? red('!!') : level === 2 ? yellow(' !') : grey(' ·');
+}
+
+function delta(now, then, format = compact) {
+  if (!then) return '';
+  const change = now - then;
+  if (!change) return grey('=');
+  const text = `${change > 0 ? '+' : ''}${format(change)}`;
+  return change > 0 ? green(text) : red(text);
+}
+
+/** Per-project breakdown, printed by `syndes projects`. */
+export function projectTable(projects) {
+  return table([
+    [grey('project'), grey('sessions'), grey('prompts'), grey('tools'), grey('tokens')],
+    ...projects.slice(0, 15).map((project) => [
+      nameFor(project.id), String(project.sessions), String(project.prompts),
+      compact(project.toolCalls), compact(project.tokens),
+    ]),
+  ], { align: ['left', 'right', 'right', 'right', 'right'] });
+}

package/src/settings.mjs

@@ -0,0 +1,173 @@
+/**
+ * Surgery on <claudeDir>/settings.json. This file is shared.
+ *
+ * The user has permissions, a status line, MCP servers and quite possibly other
+ * hook-based tools in it — on this author's machine claude-noti and claude-tts
+ * already own Stop and SessionStart hooks. So the rules are:
+ *
+ *   • Merge into what is there; never rewrite wholesale.
+ *   • Never touch a hook that is not ours, on any event, including shared ones.
+ *   • Back it up before every write.
+ *   • Refuse to write at all if the existing file does not parse, rather than
+ *     overwrite something a human hand-edited and left a trailing comma in.
+ */
+
+import { readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { settingsFile, installedHookScript } from '../runtime/paths.mjs';
+
+/**
+ * Every event syndes listens to.
+ *
+ * PreToolUse and PostToolUse are the expensive pair — they fire on every tool
+ * call — and they are wired anyway, because "every single move" is the product.
+ * That choice is what buys runtime/hook.mjs its budget, and it is the reason
+ * that file has no local imports. See DESIGN.md §1.
+ */
+export const HOOK_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'PermissionRequest',
+  'Notification',
+  'PreCompact',
+  'Stop',
+  'SubagentStop',
+  'SessionEnd',
+];
+
+/** Generous for a hook that does one small write; short enough to never hang a session. */
+const HOOK_TIMEOUT_SECONDS = 5;
+
+/** @returns {{data: object|null, error: string|null, exists: boolean}} */
+export function readSettings() {
+  if (!existsSync(settingsFile)) return { data: {}, error: null, exists: false };
+  try {
+    return { data: JSON.parse(readFileSync(settingsFile, 'utf8')), error: null, exists: true };
+  } catch (error) {
+    return { data: null, error: error.message, exists: true };
+  }
+}
+
+export function backupSettings() {
+  if (!existsSync(settingsFile)) return null;
+  const backup = `${settingsFile}.syndes-backup`;
+  try {
+    copyFileSync(settingsFile, backup);
+    return backup;
+  } catch {
+    return null;
+  }
+}
+
+function writeSettings(data) {
+  const backup = backupSettings();
+  mkdirSync(dirname(settingsFile), { recursive: true });
+  writeFileSync(settingsFile, `${JSON.stringify(data, null, 2)}\n`);
+  return backup;
+}
+
+/**
+ * The command Claude Code runs.
+ *
+ * process.execPath rather than the bare word `node`: the PATH inside a hook is
+ * not the user's shell PATH, and a hook that cannot find node fails on every
+ * event. The cost of that choice is that switching Node versions with nvm can
+ * leave the path dangling — which is exactly what `doctor` checks for, and what
+ * `install --repair` fixes.
+ *
+ * Both parts are quoted so a path containing spaces survives cmd.exe.
+ */
+export function hookCommand(script = installedHookScript, node = process.execPath) {
+  return `"${node}" "${script}"`;
+}
+
+/** True when a hook entry is one of ours and nobody else's. */
+function isOurs(hook) {
+  const command = typeof hook?.command === 'string' ? hook.command : '';
+  return command.includes('syndes') && command.includes('hook.mjs');
+}
+
+function stripOurs(groups) {
+  return (groups ?? [])
+    .map((group) => ({ ...group, hooks: (group.hooks ?? []).filter((hook) => !isOurs(hook)) }))
+    .filter((group) => group.hooks.length > 0);
+}
+
+/**
+ * Wire our hook into every event we listen to, leaving everyone else's alone.
+ *
+ * @returns {{backup: string|null, events: string[]}}
+ */
+export function installHooks(command, events = HOOK_EVENTS) {
+  const { data, error } = readSettings();
+  if (error) throw new Error(`${settingsFile} is not valid JSON (${error}) — fix it and re-run`);
+
+  const hooks = { ...(data.hooks ?? {}) };
+  const wanted = new Set(events);
+
+  for (const event of new Set([...HOOK_EVENTS, ...events])) {
+    const groups = stripOurs(hooks[event]);
+    if (wanted.has(event)) {
+      groups.push({ hooks: [{ type: 'command', command, timeout: HOOK_TIMEOUT_SECONDS }] });
+    }
+    if (groups.length) hooks[event] = groups;
+    else delete hooks[event];
+  }
+
+  const backup = writeSettings({ ...data, hooks });
+  return { backup, events: [...events] };
+}
+
+/** Remove every syndes hook. Everyone else's survives untouched. */
+export function uninstallHooks() {
+  const { data, error, exists } = readSettings();
+  if (!exists) return { backup: null, removed: [] };
+  if (error) throw new Error(`${settingsFile} is not valid JSON (${error}) — fix it and re-run`);
+
+  const hooks = { ...(data.hooks ?? {}) };
+  const removed = [];
+
+  for (const event of Object.keys(hooks)) {
+    const before = countOurs(hooks[event]);
+    if (!before) continue;
+    const groups = stripOurs(hooks[event]);
+    if (groups.length) hooks[event] = groups;
+    else delete hooks[event];
+    removed.push(event);
+  }
+  if (!removed.length) return { backup: null, removed };
+
+  const backup = writeSettings({ ...data, hooks });
+  return { backup, removed };
+}
+
+function countOurs(groups) {
+  return (groups ?? []).reduce((sum, group) => sum + (group.hooks ?? []).filter(isOurs).length, 0);
+}
+
+/** Which events currently carry one of our hooks, and where they point. */
+export function installedEvents() {
+  const { data, error } = readSettings();
+  if (error || !data) return { events: [], commands: [], error };
+
+  const events = [];
+  const commands = new Set();
+  for (const [event, groups] of Object.entries(data.hooks ?? {})) {
+    for (const group of groups ?? []) {
+      for (const hook of group.hooks ?? []) {
+        if (!isOurs(hook)) continue;
+        if (!events.includes(event)) events.push(event);
+        commands.add(hook.command);
+      }
+    }
+  }
+  return { events, commands: [...commands], error: null };
+}
+
+export function isInstalled() {
+  return installedEvents().events.length > 0;
+}
+
+export { isOurs };

package/src/status.mjs

@@ -0,0 +1,61 @@
+/**
+ * One screen: today, the score, the streak, and whether the machine is healthy.
+ * What `syndes` with no arguments prints.
+ */
+
+import { overview } from '../analytics/index.mjs';
+import { rangeFor, localDay, shiftDay } from '../analytics/ranges.mjs';
+import { rollupsFor } from '../analytics/rollup.mjs';
+import { height } from '../ledger/read.mjs';
+import { pendingCount } from '../runtime/spool.mjs';
+import { isInstalled } from './settings.mjs';
+import { mode as authMode } from '../dashboard/auth.mjs';
+import { existsSync, readFileSync } from 'node:fs';
+import { pauseFile } from '../runtime/paths.mjs';
+
+export async function statusData(spec = '7d') {
+  const data = await overview(spec);
+  const today = await overview('today');
+
+  return {
+    ...data,
+    today: today.headline,
+    todayScore: today.score,
+    streak: await streak(),
+    installed: isInstalled(),
+    lock: authMode(),
+    pending: pendingCount(),
+    ledger: height(),
+    paused: pausedState(),
+  };
+}
+
+/** Consecutive local days, ending today, with any activity. */
+export async function streak(max = 365) {
+  let day = localDay(Date.now());
+  let count = 0;
+
+  for (let index = 0; index < max; index += 1) {
+    const [rollup] = await rollupsFor(rangeFor(day));
+    if (!rollup?.records) {
+      // Today not having started yet must not break a streak that is still alive.
+      if (index === 0) { day = shiftDay(day, -1); continue; }
+      break;
+    }
+    count += 1;
+    day = shiftDay(day, -1);
+  }
+  return count;
+}
+
+export function pausedState() {
+  if (!existsSync(pauseFile)) return null;
+  try {
+    const raw = readFileSync(pauseFile, 'utf8').trim();
+    if (!raw) return { until: null, indefinite: true };
+    const until = Number(JSON.parse(raw).until);
+    return Date.now() < until ? { until, indefinite: false } : null;
+  } catch {
+    return { until: null, indefinite: true };
+  }
+}

package/src/systemauth.mjs

@@ -0,0 +1,179 @@
+/**
+ * System authentication — the OS decides, not us.
+ *
+ * The best password is the one the user has already set up. On a Mac with Touch
+ * ID that means a fingerprint; everywhere else we say so plainly instead of
+ * pretending, because a lock that silently does nothing is worse than no lock.
+ *
+ * macOS: LocalAuthentication via a tiny Swift helper compiled on first use.
+ *        swiftc ships with the Xcode command line tools, which most developers
+ *        already have; when it is absent this reports unavailable and the caller
+ *        falls back rather than failing.
+ *
+ * Windows / Linux: no dependency-free way to reach Windows Hello or polkit from
+ *        Node exists, so `available()` returns false and the caller uses a PIN.
+ *        Claiming otherwise would be the exact failure this codebase avoids.
+ */
+
+import { execFileSync, execFile } from 'node:child_process';
+import { writeFileSync, existsSync, mkdirSync, chmodSync, copyFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { dataDir } from '../runtime/paths.mjs';
+import { isMac, which } from '../runtime/platform.mjs';
+import { debug } from '../runtime/log.mjs';
+
+const run = promisify(execFile);
+/**
+ * The helper is a real .app bundle, not a bare binary.
+ *
+ * LocalAuthentication names the requesting process in its dialog. A loose
+ * executable called `touchid` produced "touchid is trying to…" beside the
+ * generic exec icon, which tells the user nothing about who is asking and looks
+ * like something that escaped from a terminal. A bundle with CFBundleName and
+ * an icon makes the prompt say SynDes and show the SynDes mark.
+ */
+const HELPER_DIR = join(dataDir, 'bin');
+const BUNDLE = join(HELPER_DIR, 'SynDes.app');
+const HELPER = join(BUNDLE, 'Contents', 'MacOS', 'SynDes');
+const ICON_SOURCE = join(dirname(fileURLToPath(import.meta.url)), '..', 'dashboard', 'web', 'SynDes.icns');
+
+const SWIFT_SOURCE = `
+import LocalAuthentication
+import Foundation
+
+let context = LAContext()
+context.localizedFallbackTitle = ""
+var error: NSError?
+
+// deviceOwnerAuthentication (not ...WithBiometrics) lets the system fall back to
+// the login password, which is what the user expects when a finger does not read.
+guard context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &error) else {
+    FileHandle.standardError.write("unavailable\\n".data(using: .utf8)!)
+    exit(2)
+}
+
+let reason = CommandLine.arguments.count > 1 ? CommandLine.arguments[1] : "open your dashboard"
+let semaphore = DispatchSemaphore(value: 0)
+var ok = false
+
+context.evaluatePolicy(.deviceOwnerAuthentication, localizedReason: reason) { success, _ in
+    ok = success
+    semaphore.signal()
+}
+semaphore.wait()
+exit(ok ? 0 : 1)
+`;
+
+let cachedAvailability = null;
+
+/** @returns {{available: boolean, reason: string, method: string|null}} */
+export function available() {
+  if (cachedAvailability) return cachedAvailability;
+  cachedAvailability = probe();
+  return cachedAvailability;
+}
+
+function probe() {
+  if (!isMac) {
+    return {
+      available: false,
+      method: null,
+      reason: 'system unlock is macOS-only for now — no dependency-free way to reach Windows Hello or polkit from Node',
+    };
+  }
+
+  if (existsSync(HELPER)) return { available: true, method: 'Touch ID', reason: 'ready' };
+
+  if (!which('swiftc')) {
+    return {
+      available: false,
+      method: null,
+      reason: 'swiftc not found — install the Xcode command line tools (xcode-select --install) to enable Touch ID',
+    };
+  }
+
+  // Enrolment is a separate question from capability: a Mac can support Touch ID
+  // with no finger registered, and evaluatePolicy would then fall back to the
+  // login password, which is still a legitimate system unlock.
+  return { available: true, method: 'Touch ID', reason: 'ready (helper will be built on first use)' };
+}
+
+const INFO_PLIST = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>CFBundleName</key><string>SynDes</string>
+  <key>CFBundleDisplayName</key><string>SynDes</string>
+  <key>CFBundleExecutable</key><string>SynDes</string>
+  <key>CFBundleIdentifier</key><string>dev.syndes.unlock</string>
+  <key>CFBundleIconFile</key><string>SynDes</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleShortVersionString</key><string>1.0</string>
+  <key>LSUIElement</key><true/>
+  <key>NSHumanReadableCopyright</key><string>Local unlock helper for the SynDes dashboard.</string>
+</dict></plist>
+`;
+
+/** Build the helper bundle. Cached; only ever runs once per install. */
+function build() {
+  if (existsSync(HELPER)) return true;
+  const swiftc = which('swiftc');
+  if (!swiftc) return false;
+
+  try {
+    const contents = join(BUNDLE, 'Contents');
+    mkdirSync(join(contents, 'MacOS'), { recursive: true });
+    mkdirSync(join(contents, 'Resources'), { recursive: true });
+
+    writeFileSync(join(contents, 'Info.plist'), INFO_PLIST);
+    if (existsSync(ICON_SOURCE)) copyFileSync(ICON_SOURCE, join(contents, 'Resources', 'SynDes.icns'));
+
+    const source = join(HELPER_DIR, 'unlock.swift');
+    writeFileSync(source, SWIFT_SOURCE);
+    execFileSync(swiftc, ['-O', '-o', HELPER, source], { timeout: 90_000, stdio: 'ignore' });
+    chmodSync(HELPER, 0o700);
+    return true;
+  } catch (error) {
+    debug('touch id helper build failed', error.message);
+    return false;
+  }
+}
+
+/**
+ * Build the helper without prompting.
+ *
+ * Called when the user chooses system unlock, so the swiftc compile happens
+ * once at configure time rather than adding ninety seconds to the first unlock
+ * — which would look like the dashboard had hung.
+ *
+ * @returns {{ok: boolean, reason: string|null, bundle: string}}
+ */
+export function prepare() {
+  const probe = available();
+  if (!probe.available) return { ok: false, reason: probe.reason, bundle: BUNDLE };
+  return build()
+    ? { ok: true, reason: null, bundle: BUNDLE }
+    : { ok: false, reason: 'could not build the unlock helper', bundle: BUNDLE };
+}
+
+/**
+ * Prompt the user. Resolves true only on a real system confirmation.
+ *
+ * @param {string} reason  shown in the system dialog
+ */
+export async function authenticate(reason = 'open your dashboard') {
+  if (!available().available) return { ok: false, reason: available().reason };
+  if (!build()) return { ok: false, reason: 'could not build the Touch ID helper' };
+
+  try {
+    await run(HELPER, [reason], { timeout: 60_000 });
+    return { ok: true, reason: null };
+  } catch (error) {
+    // exit 1 = the user cancelled or failed; exit 2 = policy unavailable.
+    if (error.code === 2) return { ok: false, reason: 'no Touch ID or login password is configured' };
+    return { ok: false, reason: 'authentication cancelled' };
+  }
+}
+
+export { HELPER };