becki 0.5.0

package/LICENSE

@@ -0,0 +1,32 @@
+becki — Becki Core admin TUI
+Copyright © 2026 BECKI.IO LLC
+
+All rights reserved.
+
+This npm package and its compiled JavaScript are distributed as a runtime
+client for the Becki service (https://www.becki.io). Use of this software
+requires a valid paid subscription and is governed by the Becki Terms of
+Service at https://www.becki.io/terms and the End User License Agreement
+at https://www.becki.io/eula.
+
+You are permitted to:
+  - Install this package and run the `becki` binary on machines you own
+    or control, for personal or business use, in conjunction with a valid
+    Becki subscription tied to your account.
+  - Inspect the compiled JavaScript for security or compatibility purposes.
+
+You are NOT permitted to:
+  - Redistribute this package, its source, or modified versions.
+  - Reverse-engineer, decompile, or extract the binary for purposes of
+    creating a competing product or service.
+  - Use this software with any backend other than the official Becki
+    backend operated by BECKI.IO LLC, except where explicitly authorized
+    in writing.
+  - Remove or modify the copyright notices, the LICENSE file, or any
+    notices embedded in the source.
+
+This software is provided "as-is" without warranty of any kind, express or
+implied. BECKI.IO LLC will not be liable for any damages arising from the
+use or inability to use this software.
+
+For licensing inquiries, contact: legal@becki.io

package/README.md

@@ -0,0 +1,57 @@
+# becki
+
+A terminal command that runs before your AI CLI. It reads your **local Becki
+vault** from the filesystem, shows a splash (vault entry count, last-ingested
+entry, your open threads), optionally asks "what are you working on today?",
+then spawns your configured AI CLI — passing the typed focus as the CLI's
+first prompt arg.
+
+It never injects context into the CLI and never makes a network call. The CLI
+already has Becki via its own MCP connection; `becki` just makes the invisible
+memory layer visible for ten seconds and launches you in oriented.
+
+## Install (local, dogfood)
+
+```sh
+cd ~/Repos/becki-shell
+npm install
+npm run build
+npm link        # makes `becki` available on your PATH
+```
+
+Then just run:
+
+```sh
+becki                 # splash → prompt → launch claude
+becki --resume        # passthrough args flow to the CLI after the focus
+```
+
+## Config
+
+`~/.becki/config.json` is auto-created with defaults on first run.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `cli` | `claude` | CLI command to hand off to |
+| `vault_path` | `~/Documents/Becki` | Local Becki vault directory to read |
+| `show_open_threads` | `true` | Show the open-threads list on the splash |
+| `max_open_threads` | `5` | How many open threads to list |
+| `skip_prompt` | `false` | Skip the "what are you working on?" prompt |
+| `pass_focus_to_cli` | `true` | Pass a typed focus as the CLI's first prompt arg |
+
+## Graceful degradation
+
+`becki` is a launcher first. A missing/unreadable vault, a malformed config,
+or a non-TTY environment all degrade to a one-line warning — `becki` still
+launches the CLI. The one loud failure is a `cli` binary that cannot be
+found: it exits 127 with a clear message rather than launching nothing.
+
+## Modules
+
+- `src/config.ts` — load / create / validate `~/.becki/config.json`
+- `src/vault.ts` — local vault read: entry count, last ingest, open threads
+- `src/splash.tsx` — Ink UI: mark, vault stats, open-threads list
+- `src/prompt.tsx` — Ink UI: the focus prompt + the App that ties it together
+- `src/handoff.ts` — spawn the CLI, inherit the TTY, propagate the exit code
+- `src/cli.ts` — orchestrator (config → vault → splash → handoff)
+- `bin/becki.js` — package `bin` entry (shebang; delegates to `dist/cli.js`)

package/bin/becki.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * becki — terminal dashboard + launcher for your Becki operational brain.
+ *
+ * This is the package `bin` entry. It is intentionally tiny: it delegates to
+ * the compiled orchestrator in dist/. Run `npm run build` first so dist/
+ * exists. Any unexpected crash is caught here so becki fails with a clear
+ * message rather than a raw stack trace.
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const entry = join(here, '..', 'dist', 'cli.js');
+
+if (!existsSync(entry)) {
+  process.stderr.write(
+    'becki: build output missing — run "npm run build" in the becki-shell repo.\n',
+  );
+  process.exit(1);
+}
+
+try {
+  const { main } = await import(entry);
+  await main();
+} catch (err) {
+  process.stderr.write(`becki: unexpected error — ${err?.message ?? err}\n`);
+  process.exit(1);
+}

package/dist/cli.js

@@ -0,0 +1,77 @@
+/**
+ * cli.ts — entry point. Compiled to dist/cli.js, invoked by bin/becki.js.
+ *
+ * Modes:
+ *   `becki`                  → open admin TUI (the menu router)
+ *   `becki ask|loops|save|resolve …`  → operate on the vault and exit
+ *   `becki --help`           → usage
+ *   `becki --version`        → npm package version
+ *
+ * The launcher mode (splash → prompt → handoff to claude) was stripped on
+ * 2026-05-28 — Bryan found it redundant ("I prefer to cut right into resuming
+ * my session"). See [[becki-shell-repurposed-as-admin-tui]].
+ */
+import React from 'react';
+import { render } from 'ink';
+import { isCommand, runCommand } from './commands.js';
+import { MenuApp } from './menu.js';
+const HELP_TEXT = `becki — Becki Core admin TUI + vault CLI
+
+Usage:
+  becki                      Open admin TUI (Status / Watch folders / Backfills / ...)
+  becki ask <query>           Semantic search the vault
+  becki loops                 List open threads
+  becki save --type <t> ...   Save an entry to the vault
+  becki resolve <row-id>      Mark a vault row resolved
+  becki --help, -h            Show this help
+  becki --version, -v         Show version
+
+Companion daemon:
+  becki-mcp                   The MCP server AI clients connect to
+  becki-mcp init              Set up cache + register projects (programmatic)
+  becki-mcp digest            Run today's session digest
+  becki-mcp bootstrap [N]     Historical ingest (default 90 days)
+
+Docs:  https://www.becki.io
+`;
+export async function main() {
+    const rawArgs = process.argv.slice(2);
+    if (rawArgs[0] === '--help' || rawArgs[0] === '-h') {
+        process.stdout.write(HELP_TEXT);
+        process.exit(0);
+    }
+    if (rawArgs[0] === '--version' || rawArgs[0] === '-v') {
+        // Lazy import so plain --version doesn't trigger a config-load side effect.
+        try {
+            const { readFileSync } = await import('node:fs');
+            const { fileURLToPath } = await import('node:url');
+            const { dirname, join } = await import('node:path');
+            const here = dirname(fileURLToPath(import.meta.url));
+            const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+            process.stdout.write(`becki ${pkg.version}\n`);
+        }
+        catch {
+            process.stdout.write('becki (version unknown)\n');
+        }
+        process.exit(0);
+    }
+    // Subcommand mode — bypass the TUI entirely.
+    if (isCommand(rawArgs[0])) {
+        process.exit(await runCommand(rawArgs[0], rawArgs.slice(1)));
+    }
+    // No subcommand → admin TUI.
+    if (!process.stdout.isTTY || !process.stdin.isTTY) {
+        process.stderr.write('becki: admin TUI needs an interactive terminal\n');
+        process.stderr.write('       use `becki --help` for non-interactive subcommands\n');
+        process.exit(1);
+    }
+    const { waitUntilExit } = render(React.createElement(MenuApp), {
+        exitOnCtrlC: true,
+    });
+    await waitUntilExit();
+    // Quick goodbye after the TUI tears down so the exit doesn't feel
+    // like a crash. stdout (not stderr) so it stays visible on success
+    // and goes to the terminal even with shells that redirect stderr.
+    process.stdout.write('\n  ◆ becki — see you soon.\n\n');
+    process.exit(0);
+}

package/dist/client.js

@@ -0,0 +1,286 @@
+/**
+ * client.ts — becki vault API client (chunk 1a: install-token auth).
+ *
+ * Talks to the hosted Becki vault (Supabase) over HTTP, authenticating with
+ * the install token + user-id that Becki.app writes to
+ * ~/Library/Application Support/Becki/. This is the same credential path the
+ * Mac-app-bundled becki-mcp stdio server uses — so `becki ask/loops/save/
+ * resolve` work on any Mac with Becki.app installed and signed in once.
+ *
+ * Cross-platform note: a genuine non-Mac machine has no Becki.app and no
+ * install token — that's chunk 1b, an OAuth device flow against the hosted
+ * MCP. Everything here takes { userId, ingestToken } via resolveAuth(), so a
+ * future OAuth resolver can supply the same shape with no other change.
+ */
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, statSync, mkdirSync, } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+export const SUPABASE_URL = 'https://mbutedmgtkmoigfbrthr.supabase.co';
+// Publishable anon key — the same one bundled in becki-mcp. Every read RPC is
+// scoped by an explicit pp_user_id, so the anon key alone grants nothing.
+export const SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im1idXRlZG1ndGttb2lnZmJydGhyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzY4Mjk1NTYsImV4cCI6MjA5MjQwNTU1Nn0.FHMSjKrwSgglGa6__ykxuPjxCrjmj8gKqwpEbJoVvgk';
+/**
+ * Cross-platform Becki home directory.
+ *
+ * Resolution order matches becki-mcp's resolveBeckiHome():
+ *   1. BECKI_HOME env var override
+ *   2. On macOS with the legacy Application Support dir present (Becki.app
+ *      is installed), keep using it — shared state with the Mac app
+ *   3. Otherwise ~/.becki/ (Core default everywhere else)
+ */
+export function resolveBeckiHome() {
+    const envOverride = process.env.BECKI_HOME;
+    if (envOverride && envOverride.length > 0)
+        return envOverride;
+    if (platform() === 'darwin') {
+        const legacy = join(homedir(), 'Library', 'Application Support', 'Becki');
+        if (existsSync(legacy))
+            return legacy;
+    }
+    return join(homedir(), '.becki');
+}
+const APP_SUPPORT_DIR = resolveBeckiHome();
+const USER_ID_PATH = join(APP_SUPPORT_DIR, 'mcp-user-id');
+const INGEST_TOKEN_PATH = join(APP_SUPPORT_DIR, 'mcp-ingest-token');
+const INSTALL_ID_PATH = join(homedir(), '.becki', 'install-id');
+export const PATHS = {
+    beckiHome: APP_SUPPORT_DIR,
+    userId: USER_ID_PATH,
+    ingestToken: INGEST_TOKEN_PATH,
+    installId: INSTALL_ID_PATH,
+};
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** match_vault_v5 returns RRF-fused scores; this ceiling normalizes to 0..1. */
+const RRF_CEILING = 0.0328;
+/** Vault entry types accepted by `becki save --type`. */
+export const SOURCE_TYPES = [
+    'decision',
+    'commitment',
+    'note',
+    'open_loop',
+    'dead_end',
+];
+// --- Auth --------------------------------------------------------------
+/**
+ * Read a 0600-protected credential file Becki.app wrote. Any other mode means
+ * the file was touched by something else — refuse it. Mirrors becki-mcp.
+ */
+function readProtected(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        if ((statSync(path).mode & 0o777) !== 0o600)
+            return null;
+        return readFileSync(path, 'utf8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve vault credentials from the local Becki.app install. */
+export function resolveAuth() {
+    const rawUser = readProtected(USER_ID_PATH);
+    return {
+        userId: rawUser && UUID_RE.test(rawUser) ? rawUser : null,
+        ingestToken: readProtected(INGEST_TOKEN_PATH),
+    };
+}
+/** A stable per-machine id for anon embed-quota attribution. Created once. */
+function installId() {
+    try {
+        if (existsSync(INSTALL_ID_PATH)) {
+            const v = readFileSync(INSTALL_ID_PATH, 'utf8').trim();
+            if (v)
+                return v;
+        }
+    }
+    catch {
+        // fall through to mint a fresh one
+    }
+    const id = randomUUID();
+    try {
+        mkdirSync(join(homedir(), '.becki'), { recursive: true });
+        writeFileSync(INSTALL_ID_PATH, id + '\n', 'utf8');
+    }
+    catch {
+        // non-fatal — a fresh id each run still works, just no quota continuity
+    }
+    return id;
+}
+// --- HTTP helpers ------------------------------------------------------
+/** Headers for a PostgREST RPC call on the `becki` schema. */
+function rpcHeaders() {
+    return {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        apikey: SUPABASE_ANON_KEY,
+        Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
+        'Content-Profile': 'becki',
+    };
+}
+async function failBody(res, label) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`${label} ${res.status}: ${body.slice(0, 200)}`);
+}
+/** Embed query text via the voyage-embed edge function (anon query path). */
+async function embedQuery(text) {
+    const res = await fetch(`${SUPABASE_URL}/functions/v1/voyage-embed`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            apikey: SUPABASE_ANON_KEY,
+            Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
+            'X-Becki-Install-Id': installId(),
+        },
+        body: JSON.stringify({ texts: [text], input_type: 'query' }),
+    });
+    if (res.status === 429) {
+        throw new Error('NeuraVault is rate-limited — daily query quota exhausted. Try again later.');
+    }
+    if (!res.ok)
+        await failBody(res, 'voyage-embed');
+    const json = (await res.json());
+    if (!Array.isArray(json.vectors?.[0])) {
+        throw new Error('voyage-embed returned no vector');
+    }
+    return json.vectors[0];
+}
+// --- Vault operations --------------------------------------------------
+/** Semantic vault search. Embeds the query, then calls match_vault_v5. */
+export async function query(userId, text, limit) {
+    const embedding = await embedQuery(text);
+    const res = await fetch(`${SUPABASE_URL}/rest/v1/rpc/match_vault_v5`, {
+        method: 'POST',
+        headers: rpcHeaders(),
+        body: JSON.stringify({
+            pp_query_embedding: embedding,
+            pp_query_text: text,
+            pp_match_threshold: 0.2,
+            pp_match_count: limit,
+            pp_filter_source_types: null,
+            pp_filter_project_id: null,
+            pp_knowledge_boost: 0,
+            pp_candidate_pool: 60,
+            pp_include_resolved: false,
+            pp_recency_half_life_days: 90,
+            pp_since: null,
+            pp_until: null,
+            pp_recency_floor: 0.1,
+            pp_user_id: userId,
+            pp_resolution_filter: null,
+        }),
+    });
+    if (!res.ok)
+        await failBody(res, 'match_vault_v5');
+    const raw = (await res.json());
+    return raw.map((c) => ({
+        ...c,
+        similarity: Math.min(1, c.similarity / RRF_CEILING),
+    }));
+}
+/** List open threads — chronological dump of unresolved open_loop rows. */
+export async function listLoops(userId, limit) {
+    const res = await fetch(`${SUPABASE_URL}/rest/v1/rpc/list_vault_rows`, {
+        method: 'POST',
+        headers: rpcHeaders(),
+        body: JSON.stringify({
+            p_project_id: null,
+            p_since: null,
+            p_until: null,
+            p_types: ['open_loop'],
+            p_limit: limit,
+            p_user_id: userId,
+        }),
+    });
+    if (!res.ok)
+        await failBody(res, 'list_vault_rows');
+    return (await res.json());
+}
+/** Ingest a vault entry via the ingest-vault-row edge function. */
+export async function save(ingestToken, opts) {
+    const sourceId = opts.title ? `${todayStr()}-${toSlug(opts.title)}` : undefined;
+    const metadata = {};
+    const project = normProject(opts.project);
+    if (project)
+        metadata.project_name = project;
+    const res = await fetch(`${SUPABASE_URL}/functions/v1/ingest-vault-row`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${ingestToken}`,
+            'User-Agent': 'becki-shell',
+        },
+        body: JSON.stringify({
+            content: opts.content,
+            source_type: opts.type,
+            source_id: sourceId,
+            metadata,
+        }),
+    });
+    if (!res.ok)
+        await failBody(res, 'ingest-vault-row');
+    return (await res.json());
+}
+/** Mark a vault row resolved (close an open loop). */
+export async function resolve(userId, rowId, note) {
+    const res = await fetch(`${SUPABASE_URL}/rest/v1/rpc/resolve_vault_row`, {
+        method: 'POST',
+        headers: rpcHeaders(),
+        body: JSON.stringify({
+            pp_row_id: rowId,
+            pp_resolved_by: 'cli',
+            pp_note: note ?? null,
+            pp_user_id: userId,
+        }),
+    });
+    if (!res.ok)
+        await failBody(res, 'resolve_vault_row');
+    const rows = (await res.json());
+    if (!Array.isArray(rows) || rows.length === 0) {
+        throw new Error(`row ${rowId} not found, not owned by you, or already resolved`);
+    }
+}
+/** Vault projects, via the get_viz_substrate RPC's project rollup. */
+export async function listProjects(userId) {
+    const res = await fetch(`${SUPABASE_URL}/rest/v1/rpc/get_viz_substrate`, {
+        method: 'POST',
+        headers: rpcHeaders(),
+        // Tiny sample — the project rollup is what we want, not atomic items.
+        body: JSON.stringify({ p_user_id: userId, p_atomic_sample_size: 1 }),
+    });
+    if (!res.ok)
+        await failBody(res, 'get_viz_substrate');
+    const data = (await res.json());
+    return Array.isArray(data.projects) ? data.projects : [];
+}
+/** The most recent daily briefing, or null when none has been computed. */
+export async function getBriefing(userId) {
+    const res = await fetch(`${SUPABASE_URL}/rest/v1/rpc/get_daily_briefing`, {
+        method: 'POST',
+        headers: rpcHeaders(),
+        body: JSON.stringify({ pp_user_id: userId }),
+    });
+    if (!res.ok)
+        await failBody(res, 'get_daily_briefing');
+    const rows = (await res.json());
+    return rows.length > 0 ? rows[0] : null;
+}
+// --- Small helpers (mirror becki-mcp) ----------------------------------
+function todayStr() {
+    return new Date().toISOString().slice(0, 10);
+}
+function toSlug(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 60);
+}
+/** Canonical project-slug form on write — mirrors becki.norm_project_slug. */
+function normProject(raw) {
+    if (!raw)
+        return undefined;
+    const n = raw.trim().toLowerCase().replace(/_/g, '-');
+    return n || undefined;
+}