@luuthuong/devboard 0.0.0-stage → 1.0.0

package/server-dist/server/transcripts.js

@@ -0,0 +1,335 @@
+// Transcript reading, file-level session ops (fork / truncate / move) and BM25
+// search. Ports transcript_reader.rs, session_ops.rs, session_mover.rs, bm25.rs.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { readLines, takeChars } from "./util.js";
+// ── Transcript ───────────────────────────────────────────────────────────────
+const PAGE_SIZE = 20;
+function parseContentBlocks(obj) {
+    const blocks = [];
+    const content = obj?.message?.content;
+    if (!Array.isArray(content)) {
+        if (typeof content === "string")
+            blocks.push({ kind: "text", text: content });
+        return blocks;
+    }
+    for (const block of content) {
+        const kind = typeof block?.type === "string" ? block.type : "text";
+        switch (kind) {
+            case "text":
+                blocks.push({ kind: "text", text: typeof block.text === "string" ? block.text : "" });
+                break;
+            case "tool_use":
+                blocks.push({ kind: "tool_use", text: `${block.name ?? "tool"}: ${JSON.stringify(block.input ?? null)}` });
+                break;
+            case "tool_result": {
+                const c = block.content;
+                const text = typeof c === "string" ? c : typeof c?.[0]?.text === "string" ? c[0].text : "";
+                blocks.push({ kind: "tool_result", text });
+                break;
+            }
+            case "thinking":
+                blocks.push({ kind: "thinking", text: typeof block.thinking === "string" ? block.thinking : "" });
+                break;
+            default:
+                break;
+        }
+    }
+    return blocks;
+}
+async function* turnObjects(filePath) {
+    for await (const line of readLines(filePath)) {
+        if (!line)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (obj?.type === "user" || obj?.type === "assistant")
+            yield obj;
+    }
+}
+export async function readTranscript(filePath, offset) {
+    if (!fs.existsSync(filePath))
+        return { turns: [], totalTurns: 0, hasMore: false, nextOffset: 0 };
+    const all = [];
+    let index = 0;
+    for await (const obj of turnObjects(filePath)) {
+        const contentBlocks = parseContentBlocks(obj);
+        const textPreview = takeChars(contentBlocks
+            .filter((b) => b.kind === "text")
+            .map((b) => b.text)
+            .join(" "), 200);
+        all.push({
+            index: index++,
+            role: obj.type,
+            textPreview,
+            timestamp: typeof obj.timestamp === "string" ? obj.timestamp : undefined,
+            contentBlocks,
+        });
+    }
+    const total = all.length;
+    const hasMore = offset + PAGE_SIZE < total;
+    return {
+        turns: all.slice(offset, offset + PAGE_SIZE),
+        totalTurns: total,
+        hasMore,
+        nextOffset: hasMore ? offset + PAGE_SIZE : total,
+    };
+}
+export async function searchTranscriptTurns(filePath, query) {
+    if (!fs.existsSync(filePath))
+        return [];
+    const q = query.toLowerCase();
+    const matches = [];
+    let index = 0;
+    for await (const obj of turnObjects(filePath)) {
+        if (parseContentBlocks(obj).some((b) => b.text.toLowerCase().includes(q)))
+            matches.push(index);
+        index++;
+    }
+    return matches;
+}
+/** Text of the latest assistant turn, capped for an OS notification body. */
+export async function readLastAssistantMessage(filePath, maxChars) {
+    if (!fs.existsSync(filePath))
+        return null;
+    let last = null;
+    for await (const obj of turnObjects(filePath)) {
+        if (obj.type !== "assistant")
+            continue;
+        const text = parseContentBlocks(obj)
+            .filter((b) => b.kind === "text")
+            .map((b) => b.text)
+            .join(" ")
+            .trim();
+        if (text)
+            last = text;
+    }
+    if (last === null)
+        return null;
+    const chars = Array.from(last);
+    return chars.length > maxChars ? chars.slice(0, maxChars).join("") + "…" : last;
+}
+// ── fork / truncate / move ───────────────────────────────────────────────────
+/** Copy a session under a fresh UUID, rewriting the old id. Returns the new id. */
+export async function forkSession(sessionPath, targetDir) {
+    if (!fs.existsSync(sessionPath))
+        throw new Error(`session file not found: ${sessionPath}`);
+    const dir = targetDir || path.dirname(sessionPath);
+    await fs.promises.mkdir(dir, { recursive: true });
+    const newId = crypto.randomUUID().toLowerCase();
+    const oldId = path.basename(sessionPath, path.extname(sessionPath));
+    const newPath = path.join(dir, `${newId}.jsonl`);
+    const contents = await fs.promises.readFile(sessionPath, "utf8");
+    await fs.promises.writeFile(newPath, contents.replaceAll(`"${oldId}"`, `"${newId}"`));
+    // Preserve the source mtime so the activity detector doesn't flag the fork as active.
+    try {
+        const st = await fs.promises.stat(sessionPath);
+        await fs.promises.utimes(newPath, st.atime, st.mtime);
+    }
+    catch {
+        // best effort
+    }
+    return newId;
+}
+/** Keep the first `turnCount` user/assistant turns; original is saved as `.bkp`. */
+export async function truncateSession(sessionPath, turnCount) {
+    if (!fs.existsSync(sessionPath))
+        throw new Error(`session file not found: ${sessionPath}`);
+    if (turnCount < 1)
+        throw new Error("turn_count must be >= 1");
+    const bkp = `${sessionPath}.bkp`;
+    await fs.promises.rm(bkp, { force: true });
+    await fs.promises.copyFile(sessionPath, bkp);
+    const contents = await fs.promises.readFile(sessionPath, "utf8");
+    const kept = [];
+    let seen = 0;
+    let hitTarget = false;
+    for (const line of contents.split(/\r?\n/)) {
+        let role;
+        try {
+            role = JSON.parse(line)?.type;
+        }
+        catch {
+            role = undefined;
+        }
+        const isTurn = role === "user" || role === "assistant";
+        if (hitTarget && isTurn)
+            break;
+        if (isTurn) {
+            seen++;
+            if (seen >= turnCount)
+                hitTarget = true;
+        }
+        kept.push(line);
+    }
+    // A trailing "" from the final newline would add a spurious blank line.
+    while (kept.length && kept[kept.length - 1] === "")
+        kept.pop();
+    await fs.promises.writeFile(sessionPath, kept.length ? kept.join("\n") + "\n" : "");
+}
+/** `/` `\` and `.` → `-`, matching Claude's projects-dir naming. */
+export function encodeProjectPath(p) {
+    return p.replaceAll("\\", "/").replaceAll("/", "-").replaceAll(".", "-");
+}
+/** Move a session jsonl into another project's directory, rewriting `cwd`. */
+export async function moveSession(sessionId, fromPath, toProjectPath) {
+    const projectsDir = path.join(os.homedir(), ".claude", "projects");
+    const targetDir = path.join(projectsDir, encodeProjectPath(toProjectPath));
+    const targetPath = path.join(targetDir, `${sessionId}.jsonl`);
+    await fs.promises.mkdir(targetDir, { recursive: true });
+    const content = await fs.promises.readFile(fromPath, "utf8");
+    const lines = content.split("\n").map((line) => {
+        if (!line.trim())
+            return line;
+        try {
+            const obj = JSON.parse(line);
+            if (obj && typeof obj === "object" && "cwd" in obj)
+                obj.cwd = toProjectPath;
+            return JSON.stringify(obj);
+        }
+        catch {
+            return line;
+        }
+    });
+    await fs.promises.writeFile(targetPath, lines.join("\n"));
+    if (path.resolve(fromPath) !== path.resolve(targetPath))
+        await fs.promises.rm(fromPath, { force: true });
+    return targetPath;
+}
+// ── BM25 ─────────────────────────────────────────────────────────────────────
+const K1 = 1.2;
+const B = 0.4;
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((s) => s.length >= 2);
+}
+export function bm25Score(terms, docTokens, avgDocLength, docCount, docFreqs, recencyBoost) {
+    const docLength = docTokens.length;
+    if (docLength === 0 || avgDocLength === 0)
+        return 0;
+    const tf = new Map();
+    for (const t of docTokens)
+        tf.set(t, (tf.get(t) ?? 0) + 1);
+    let total = 0;
+    for (const term of terms) {
+        let termFreq = 0;
+        let dfCount = 0;
+        if (term.length >= 3) {
+            for (const [k, v] of tf)
+                if (k.startsWith(term))
+                    termFreq += v;
+            for (const [k, v] of docFreqs)
+                if (k.startsWith(term))
+                    dfCount += v;
+        }
+        else {
+            termFreq = tf.get(term) ?? 0;
+            dfCount = docFreqs.get(term) ?? 0;
+        }
+        if (termFreq === 0)
+            continue;
+        const df = Math.max(dfCount, 0.5);
+        const idf = Math.log((docCount - df + 0.5) / (df + 0.5) + 1);
+        const tfNorm = (termFreq * (K1 + 1)) / (termFreq + K1 * (1 - B + (B * docLength) / avgDocLength));
+        total += idf * tfNorm;
+    }
+    return total * recencyBoost;
+}
+/** 3.0 today → 1.0 at ≥30 days, linear. */
+export function recencyBoost(ageSecs) {
+    const days = ageSecs / 86_400;
+    if (days <= 0)
+        return 3;
+    if (days >= 30)
+        return 1;
+    return 3 - (2 * days) / 30;
+}
+export async function searchSessions(allSessions, query) {
+    const q = query.trim();
+    if (!q)
+        return allSessions.slice(0, 20);
+    const terms = tokenize(q);
+    if (terms.length === 0) {
+        const ql = q.toLowerCase();
+        return allSessions
+            .filter((s) => s.id.toLowerCase().includes(ql) ||
+            (s.firstPrompt ?? "").toLowerCase().includes(ql) ||
+            (s.projectPath ?? "").toLowerCase().includes(ql))
+            .slice(0, 20);
+    }
+    const docs = [];
+    for (const s of allSessions) {
+        if (!s.jsonlPath)
+            continue;
+        let content;
+        try {
+            content = await fs.promises.readFile(s.jsonlPath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const tokens = tokenize(content);
+        if (tokens.length === 0)
+            continue;
+        docs.push({ session: s, tokens, ageSecs: (Date.now() - Date.parse(s.modifiedTime)) / 1000 });
+    }
+    if (docs.length === 0)
+        return [];
+    const docCount = docs.length;
+    const avgDocLength = docs.reduce((n, d) => n + d.tokens.length, 0) / docCount;
+    const docFreqs = new Map();
+    for (const d of docs)
+        for (const t of new Set(d.tokens))
+            docFreqs.set(t, (docFreqs.get(t) ?? 0) + 1);
+    return docs
+        .map((d) => ({
+        score: bm25Score(terms, d.tokens, avgDocLength, docCount, docFreqs, recencyBoost(d.ageSecs)),
+        session: d.session,
+    }))
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 20)
+        .map((x) => x.session);
+}
+/** Token usage summed from the `message.usage` of every assistant line. Claude
+ *  writes one line per content block of a message, all repeating the same usage,
+ *  so only the last line of each message id counts. */
+export async function readTranscriptUsage(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    const byMessage = new Map();
+    let last = null;
+    let model = "";
+    let anon = 0;
+    for await (const obj of turnObjects(filePath)) {
+        if (obj.type !== "assistant")
+            continue;
+        const u = obj.message?.usage;
+        if (!u)
+            continue;
+        const input = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
+        const entry = { input, output: u.output_tokens ?? 0 };
+        byMessage.set(obj.message.id ?? `anon-${anon++}`, entry);
+        last = entry;
+        if (typeof obj.message.model === "string" && !obj.message.model.startsWith("<"))
+            model = obj.message.model;
+    }
+    if (!last)
+        return null;
+    let inputTokens = 0;
+    let outputTokens = 0;
+    for (const e of byMessage.values()) {
+        inputTokens += e.input;
+        outputTokens += e.output;
+    }
+    return { contextTokens: last.input + last.output, inputTokens, outputTokens, model };
+}

package/server-dist/server/util.js

@@ -0,0 +1,286 @@
+// Shared plumbing: data dir, logging, KSUID, subprocess helpers, a mutex.
+// Ports coordination_store::devboard_data_dir, logging.rs and ksuid.rs.
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+export const IS_WINDOWS = process.platform === "win32";
+/** %APPDATA%\devboard on Windows, ~/.devboard elsewhere. */
+export function devboardDataDir() {
+    if (process.env.DEVBOARD_DATA_DIR)
+        return process.env.DEVBOARD_DATA_DIR;
+    if (IS_WINDOWS) {
+        const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+        return path.join(appData, "devboard");
+    }
+    return path.join(os.homedir(), ".devboard");
+}
+// ── Logging ──────────────────────────────────────────────────────────────────
+const MAX_LOG_SIZE = 10 * 1024 * 1024;
+const KEEP_AFTER_ROTATION = 5 * 1024 * 1024;
+let logPathCache = null;
+function logPath() {
+    if (logPathCache)
+        return logPathCache;
+    const dir = path.join(devboardDataDir(), "logs");
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        // logging must never throw
+    }
+    const p = path.join(dir, "devboard.log");
+    try {
+        const st = fs.statSync(p);
+        if (st.size > MAX_LOG_SIZE) {
+            const data = fs.readFileSync(p);
+            const tail = data.subarray(Math.max(0, data.length - KEEP_AFTER_ROTATION));
+            const nl = tail.indexOf(0x0a);
+            fs.writeFileSync(p, nl >= 0 ? tail.subarray(nl + 1) : tail);
+        }
+    }
+    catch {
+        // no log yet
+    }
+    logPathCache = p;
+    return p;
+}
+// Console output is for humans: local time, coloured level, aligned subsystem.
+// The log file keeps the plain ISO format so it stays greppable.
+const useColor = !process.env.NO_COLOR && (process.env.FORCE_COLOR ? true : Boolean(process.stderr.isTTY));
+const ANSI = {
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    DEBUG: "\x1b[90m",
+    INFO: "\x1b[32m",
+    WARN: "\x1b[33m",
+    ERROR: "\x1b[1;31m",
+};
+const SUBSYSTEM_COLORS = [36, 35, 34, 96, 95, 94];
+const SUBSYSTEM_WIDTH = 10;
+function subsystemColor(name) {
+    let h = 0;
+    for (let i = 0; i < name.length; i++)
+        h = (h * 31 + name.charCodeAt(i)) >>> 0;
+    return SUBSYSTEM_COLORS[h % SUBSYSTEM_COLORS.length];
+}
+function consoleLine(level, subsystem, message) {
+    const d = new Date();
+    const p2 = (n) => String(n).padStart(2, "0");
+    const time = `${p2(d.getHours())}:${p2(d.getMinutes())}:${p2(d.getSeconds())}`;
+    const lvl = level.padEnd(5);
+    const sub = subsystem.padEnd(SUBSYSTEM_WIDTH);
+    if (!useColor)
+        return `${time} ${lvl} ${sub} ${message}\n`;
+    const msg = level === "ERROR" || level === "WARN" ? `${ANSI[level]}${message}${ANSI.reset}` : message;
+    return (`${ANSI.dim}${time}${ANSI.reset} ${ANSI[level]}${lvl}${ANSI.reset} ` +
+        `\x1b[${subsystemColor(subsystem)}m${sub}${ANSI.reset} ${msg}\n`);
+}
+function writeLog(level, subsystem, message) {
+    const line = `[${new Date().toISOString()}] [${level}] [${subsystem}] ${message}\n`;
+    process.stderr.write(consoleLine(level, subsystem, message));
+    try {
+        fs.appendFileSync(logPath(), line);
+    }
+    catch {
+        // drop the line rather than crash
+    }
+}
+const debugEnabled = process.env.DEVBOARD_DEBUG_LOGS === "1" || process.env.DEVBOARD_DEBUG === "1";
+export const log = {
+    info: (subsystem, message) => writeLog("INFO", subsystem, message),
+    warn: (subsystem, message) => writeLog("WARN", subsystem, message),
+    error: (subsystem, message) => writeLog("ERROR", subsystem, message),
+    debug: (subsystem, message) => {
+        if (debugEnabled)
+            writeLog("DEBUG", subsystem, message);
+    },
+};
+// ── KSUID ────────────────────────────────────────────────────────────────────
+// 4-byte big-endian timestamp (seconds since 1_400_000_000) + 16 random bytes,
+// base62-encoded to 27 chars. Bit-for-bit compatible with the Swift/Rust ports.
+const KSUID_EPOCH = 1_400_000_000;
+const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+export function ksuid(prefix) {
+    const ts = Math.max(0, Math.floor(Date.now() / 1000) - KSUID_EPOCH);
+    const bytes = Buffer.alloc(20);
+    bytes.writeUInt32BE(ts, 0);
+    crypto.randomFillSync(bytes, 4);
+    const num = Uint8Array.from(bytes);
+    const out = new Array(27).fill("0");
+    for (let slot = 26; slot >= 0; slot--) {
+        let remainder = 0;
+        for (let i = 0; i < num.length; i++) {
+            const value = num[i] + remainder * 256;
+            num[i] = Math.floor(value / 62);
+            remainder = value % 62;
+        }
+        out[slot] = BASE62[remainder];
+    }
+    const encoded = out.join("");
+    return prefix ? `${prefix}_${encoded}` : encoded;
+}
+/** Run a command to completion. Never rejects: spawn failures resolve `ok: false`. */
+export function run(cmd, args, opts = {}) {
+    return new Promise((resolve) => {
+        const spawnOpts = {
+            cwd: opts.cwd,
+            env: opts.env ?? process.env,
+            windowsHide: true,
+            stdio: ["pipe", "pipe", "pipe"],
+        };
+        let child;
+        try {
+            child = spawn(cmd, args, spawnOpts);
+        }
+        catch (e) {
+            resolve({ ok: false, code: null, stdout: "", stderr: String(e) });
+            return;
+        }
+        const out = [];
+        const err = [];
+        let timer;
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(r);
+        };
+        if (opts.timeoutMs) {
+            timer = setTimeout(() => {
+                child.kill();
+                finish({ ok: false, code: null, stdout: Buffer.concat(out).toString("utf8"), stderr: "timed out" });
+            }, opts.timeoutMs);
+        }
+        child.stdout?.on("data", (d) => out.push(d));
+        child.stderr?.on("data", (d) => err.push(d));
+        child.on("error", (e) => finish({ ok: false, code: null, stdout: "", stderr: String(e) }));
+        child.on("close", (code) => finish({
+            ok: code === 0,
+            code,
+            stdout: Buffer.concat(out).toString("utf8"),
+            stderr: Buffer.concat(err).toString("utf8"),
+        }));
+        // A command that exits before reading stdin raises EPIPE; ignore it.
+        child.stdin?.on("error", () => { });
+        if (opts.input !== undefined)
+            child.stdin?.end(opts.input);
+        else
+            child.stdin?.end();
+    });
+}
+/** Run a user-supplied command line through the platform shell (merge templates). */
+export function runShell(command, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn(command, { cwd, shell: true, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+        const out = [];
+        const err = [];
+        child.stdout?.on("data", (d) => out.push(d));
+        child.stderr?.on("data", (d) => err.push(d));
+        child.on("error", (e) => resolve({ ok: false, code: null, stdout: "", stderr: String(e) }));
+        child.on("close", (code) => resolve({
+            ok: code === 0,
+            code,
+            stdout: Buffer.concat(out).toString("utf8"),
+            stderr: Buffer.concat(err).toString("utf8"),
+        }));
+    });
+}
+/** Fire-and-forget a detached process (editors, browsers). */
+export function spawnDetached(cmd, args, cwd) {
+    try {
+        const child = spawn(cmd, args, { cwd, detached: true, stdio: "ignore", windowsHide: true });
+        child.on("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Locate an executable on PATH (adds .exe/.cmd/.bat on Windows). */
+export function findOnPath(name) {
+    const exts = IS_WINDOWS ? ["", ".exe", ".cmd", ".bat"] : [""];
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = path.join(dir, name + ext);
+            try {
+                if (fs.statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch {
+                // keep looking
+            }
+        }
+    }
+    return null;
+}
+// ── Mutex ────────────────────────────────────────────────────────────────────
+/** Serialises async critical sections (read-modify-write of JSON stores). */
+export class Mutex {
+    tail = Promise.resolve();
+    run(fn) {
+        const next = this.tail.then(fn, fn);
+        this.tail = next.catch(() => { });
+        return next;
+    }
+}
+// ── File helpers ─────────────────────────────────────────────────────────────
+export async function fileExists(p) {
+    try {
+        await fs.promises.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Write via tmp file + rename so readers never see a half-written file. */
+export async function writeFileAtomic(p, data) {
+    await fs.promises.mkdir(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp-${crypto.randomBytes(6).toString("hex")}`;
+    await fs.promises.writeFile(tmp, data);
+    try {
+        await fs.promises.rename(tmp, p);
+    }
+    catch (e) {
+        await fs.promises.rm(tmp, { force: true });
+        throw e;
+    }
+}
+export async function readJsonFile(p) {
+    try {
+        return JSON.parse(await fs.promises.readFile(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Reads a file line-by-line without loading it all (used for big transcripts). */
+export async function* readLines(p) {
+    const stream = fs.createReadStream(p, { encoding: "utf8" });
+    let buf = "";
+    for await (const chunk of stream) {
+        buf += chunk;
+        let idx;
+        while ((idx = buf.indexOf("\n")) >= 0) {
+            yield buf.slice(0, idx).replace(/\r$/, "");
+            buf = buf.slice(idx + 1);
+        }
+    }
+    if (buf.length > 0)
+        yield buf.replace(/\r$/, "");
+}
+export function errorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** Truncate to `n` Unicode code points (Rust `.chars().take(n)`). */
+export function takeChars(s, n) {
+    return Array.from(s).slice(0, n).join("");
+}

package/server-dist/src/types/index.js

@@ -0,0 +1,53 @@
+// TypeScript types mirroring Rust/Swift domain entities
+export const COLUMN_DISPLAY = {
+    backlog: "Backlog",
+    in_progress: "In Progress",
+    in_review: "In Review",
+    done: "Done",
+    all_sessions: "All Sessions",
+};
+/** Status label for a card: archived cards read "Archived", not their column name. */
+export function statusLabel(link) {
+    return link.manuallyArchived ? "Archived" : COLUMN_DISPLAY[link.column];
+}
+export const COLUMNS = ["backlog", "in_progress", "in_review", "done", "all_sessions"];
+/** Lanes drawn on the board; "All Sessions" lives in the left sidebar instead. */
+export const BOARD_COLUMNS = COLUMNS.filter((col) => col !== "all_sessions");
+export const AIDLC_STAGES = ["requirements", "units", "design", "code", "review"];
+export const KNOWLEDGE_TYPES = [
+    "decision",
+    "convention",
+    "gotcha",
+    "component",
+    "glossary",
+    "runbook",
+];
+export const ASSISTANT_DISPLAY = {
+    claude: "Claude Code",
+};
+export const ASSISTANT_CLI = {
+    claude: "claude",
+};
+/** Mirrors macOS APIService.needsSeparator — a `--` separator before the
+ *  assistant's own flags is required iff a launcher prefix or model flag is
+ *  set. */
+export function apiServiceNeedsSeparator(svc) {
+    return Boolean(svc.launcherPrefix || svc.modelFlag);
+}
+/** Resolves an APIService for a launch. Per-card override → per-assistant
+ *  default → undefined. Mirrors the Rust `Settings::resolve_api_service`
+ *  logic; both must stay in sync. */
+export function resolveAPIService(settings, cardOverride, assistantId) {
+    const services = settings.apiServices ?? [];
+    if (cardOverride) {
+        const hit = services.find((s) => s.id === cardOverride);
+        if (hit)
+            return hit;
+        // stale override — fall through so a deleted service doesn't brick the card
+    }
+    const defaults = settings.defaultAPIServiceIds ?? {};
+    const defaultId = defaults[assistantId];
+    if (!defaultId)
+        return undefined;
+    return services.find((s) => s.id === defaultId);
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.