akm-cli 0.10.261005-beta → 0.10.261007-beta

package/dist/commands/ui/api.js

@@ -0,0 +1,556 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The read-only JSON API behind `akm ui`. (The three proposal writes live in
+ * `proposal-actions.ts`; nothing in this file writes.) Every handler calls the function the
+ * matching CLI command renders (`akmHealth`, `akmMetrics`, `akmSearch`,
+ * `akmShowUnified`, the proposal repository, ...), so the UI and the CLI never
+ * disagree and there is no second data layer. Documented in
+ * `docs/reference/ui-api.md`.
+ *
+ * Read-only is enforced here, not hoped for: `state.db` and `index.db` are
+ * opened read-only and never created or migrated, search and show run with
+ * `readOnly` (no usage events, no index build), and git is only queried.
+ */
+import fs from "node:fs";
+import { parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
+import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
+import { resolveStashDir } from "../../core/common.js";
+import { getConfigValueSource, loadConfig } from "../../core/config/config.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { getConfigPath, getDataDir, getDbPath } from "../../core/paths.js";
+import { getStateDbPath, listPendingStateMigrations } from "../../core/state-db.js";
+import { DURATION_UNITS, parseDuration } from "../../core/time.js";
+import { resolveWriteTarget } from "../../core/write-source.js";
+import { openDatabase } from "../../storage/database.js";
+import { listRecentImproveRuns } from "../../storage/repositories/improve-runs-repository.js";
+import { closeDatabase, openReadonlyExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { getEntryIdByFilePath, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
+import { getEmbeddingCount } from "../../storage/repositories/index-vec-repository.js";
+import { countFeedbackBySignal, listFeedbackEventRows, listUsageEventRows, } from "../../storage/repositories/metrics-repository.js";
+import { listStateProposals } from "../../storage/repositories/proposals-repository.js";
+import { applyReadonlyPragmas } from "../../storage/sqlite-pragmas.js";
+import { pkgVersion } from "../../version.js";
+import { listConfig } from "../config-cli.js";
+import { akmHealth } from "../health.js";
+import { computeAcceptRateBySource } from "../health/accept-rate.js";
+import { akmMetrics } from "../metrics/metrics-cli.js";
+import { isRetireProposal, proposalWaitingSince } from "../proposal/proposal-types.js";
+import { diffLoadedProposal, resolveProposalIdIn } from "../proposal/repository.js";
+import { validateProposal } from "../proposal/validators/proposals.js";
+import { akmSearch } from "../read/search.js";
+import { akmShowUnified } from "../read/show.js";
+import { assembleInfo } from "../sources/info.js";
+import { akmListSources } from "../sources/installed-stashes.js";
+import { readBundleGitStatus, readRecentCommits } from "./git-read.js";
+import { isSecretEnvName, redactForUi } from "./redact.js";
+const DEFAULT_LIST_LIMIT = 50;
+const MAX_LIST_LIMIT = 200;
+const IMPROVE_RUNS_SHOWN = 10;
+const USAGE_DAYS = 14;
+const DAY_MS = 86_400_000;
+// ── Parameters ───────────────────────────────────────────────────────────────
+function limitParam(query, fallback = DEFAULT_LIST_LIMIT) {
+    const raw = query.get("limit");
+    if (raw === null || raw === "")
+        return fallback;
+    const parsed = parsePositiveIntFlag(raw, "limit");
+    if (parsed === undefined)
+        return fallback;
+    return Math.min(parsed, MAX_LIST_LIMIT);
+}
+function flag(query, name) {
+    const raw = query.get(name);
+    return raw === "1" || raw === "true";
+}
+// ── Read-only databases ──────────────────────────────────────────────────────
+/**
+ * Run `fn` against `state.db` opened read-only, or return `fallback` when it
+ * does not exist or is behind on migrations (a read-only open must not apply
+ * them; `akm health` reports that state). The handle is closed before returning,
+ * so no request holds a lock past its own read.
+ */
+function withReadonlyStateDb(fn, fallback) {
+    const dbPath = getStateDbPath();
+    if (!fs.existsSync(dbPath) || listPendingStateMigrations(dbPath).length > 0)
+        return fallback;
+    const db = openDatabase(dbPath, { readonly: true, create: false });
+    try {
+        applyReadonlyPragmas(db);
+        return fn(db);
+    }
+    finally {
+        db.close();
+    }
+}
+function tryStashDir() {
+    try {
+        return resolveStashDir();
+    }
+    catch {
+        return null;
+    }
+}
+/** Run each section of a composite response on its own: one failing store degrades one section, not the page. */
+async function section(errors, name, fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        errors[name] = error instanceof Error ? error.message : String(error);
+        return null;
+    }
+}
+// ── /api/meta ────────────────────────────────────────────────────────────────
+function meta(_query, info) {
+    return {
+        version: pkgVersion,
+        runtime: process.versions.bun ? "bun" : "node",
+        stashDir: tryStashDir(),
+        dataDir: getDataDir(),
+        configPath: getConfigPath(),
+        stateDbPath: getStateDbPath(),
+        indexDbPath: getDbPath(),
+        startedAt: info.startedAt,
+        host: info.host,
+        port: info.port,
+    };
+}
+// ── /api/overview ────────────────────────────────────────────────────────────
+/** One persisted improve run, projected to what the overview shows. Tolerant: a row from an older release just has fewer fields. */
+function summarizeImproveRun(row) {
+    let result = {};
+    try {
+        const parsed = JSON.parse(row.result_json);
+        if (parsed && typeof parsed === "object")
+            result = parsed;
+    }
+    catch {
+        // An unparseable result still has a row worth listing.
+    }
+    const byProcess = {};
+    const usage = result.usageReport;
+    for (const entry of Array.isArray(usage?.byProcessEngineModel) ? usage.byProcessEngineModel : []) {
+        const { process, calls, failures } = entry;
+        if (!process)
+            continue;
+        const bucket = byProcess[process] ?? { calls: 0, failures: 0 };
+        bucket.calls += calls ?? 0;
+        bucket.failures += failures ?? 0;
+        byProcess[process] = bucket;
+    }
+    const started = Date.parse(row.started_at);
+    const completed = Date.parse(row.completed_at);
+    return {
+        id: row.id,
+        startedAt: row.started_at,
+        completedAt: row.completed_at,
+        ok: row.ok === 1,
+        durationMs: Number.isFinite(started) && Number.isFinite(completed) && completed >= started ? completed - started : null,
+        strategy: row.strategy,
+        scope: { mode: row.scope_mode, ...(row.scope_value ? { value: row.scope_value } : {}) },
+        modelCalls: {
+            total: Object.values(byProcess).reduce((sum, bucket) => sum + bucket.calls, 0),
+            failures: Object.values(byProcess).reduce((sum, bucket) => sum + bucket.failures, 0),
+            byProcess,
+        },
+        preRunSync: result.preRunSync ?? null,
+        sync: result.sync ?? null,
+        triage: result.triage ?? null,
+    };
+}
+/** User-attributed search / curate / show / feedback counts per UTC day for the last {@link USAGE_DAYS} days, oldest first. */
+function usageByDay(db, nowMs) {
+    const days = new Map();
+    for (let i = USAGE_DAYS - 1; i >= 0; i--) {
+        const date = new Date(nowMs - i * DAY_MS).toISOString().slice(0, 10);
+        days.set(date, { search: 0, curate: 0, show: 0, feedbackPositive: 0, feedbackNegative: 0 });
+    }
+    const first = [...days.keys()][0];
+    const rows = listUsageEventRows(db, {
+        sinceIso: `${first}T00:00:00.000Z`,
+        untilIso: new Date(nowMs).toISOString(),
+        source: "user",
+    });
+    for (const row of rows) {
+        // `created_at` is `YYYY-MM-DD HH:MM:SS` (UTC).
+        const bucket = days.get(row.created_at.slice(0, 10));
+        if (!bucket)
+            continue;
+        if (row.event_type === "feedback") {
+            if (row.signal === "positive")
+                bucket.feedbackPositive = (bucket.feedbackPositive ?? 0) + 1;
+            else if (row.signal === "negative")
+                bucket.feedbackNegative = (bucket.feedbackNegative ?? 0) + 1;
+        }
+        else if (row.event_type === "search" || row.event_type === "curate" || row.event_type === "show") {
+            bucket[row.event_type] = (bucket[row.event_type] ?? 0) + 1;
+        }
+    }
+    return [...days.entries()].map(([date, counts]) => ({ date, ...counts }));
+}
+async function overview(query) {
+    const errors = {};
+    const since = query.get("since") || "24h";
+    // The comparison window is the report window, like `akm health --report`; an absolute `since` has no duration to compare.
+    const sinceIsDuration = parseDuration(since, DURATION_UNITS) !== null;
+    const health = await section(errors, "health", async () => {
+        const base = await akmHealth({
+            since,
+            groupBy: "run",
+            windowCompare: sinceIsDuration ? since : undefined,
+            probe: flag(query, "probe"),
+            readOnly: true,
+        });
+        const report = withReadonlyStateDb((db) => ({
+            window: since,
+            compare: sinceIsDuration ? since : null,
+            pendingProposals: listStateProposals(db, { stashDir: tryStashDir() ?? "", status: "pending" }).map(({ ref, source, createdAt }) => ({ ref, source, createdAt })),
+            acceptRateBySource: computeAcceptRateBySource(undefined, { db }),
+        }), null);
+        return { ...base, ...(report ? { report } : {}) };
+    });
+    const metrics = await section(errors, "metrics", () => akmMetrics({ since: query.get("metricsSince") || "30d", indexSnapshot: false }));
+    const stateReads = await section(errors, "state", () => withReadonlyStateDb((db) => ({
+        improveRuns: listRecentImproveRuns(db, IMPROVE_RUNS_SHOWN).map(summarizeImproveRun),
+        usageByDay: usageByDay(db, Date.now()),
+    }), null));
+    return {
+        health,
+        metrics,
+        improveRuns: stateReads?.improveRuns ?? [],
+        usageByDay: stateReads?.usageByDay ?? [],
+        ...(Object.keys(errors).length > 0 ? { errors } : {}),
+    };
+}
+// ── /api/bundles ─────────────────────────────────────────────────────────────
+async function bundles() {
+    const config = loadConfig();
+    const listing = await akmListSources({ stashDir: tryStashDir() ?? "" });
+    const cards = await Promise.all(listing.sources.map(async (source) => ({
+        name: source.name,
+        kind: source.kind,
+        default: source.default,
+        source: source.source,
+        path: source.path ?? null,
+        writable: source.writable,
+        version: source.version ?? null,
+        exists: source.status.exists,
+        itemCount: source.itemCount,
+        byType: source.byType,
+        git: source.path ? await readBundleGitStatus(source.path) : null,
+    })));
+    const info = assembleInfo();
+    let embeddingCount = null;
+    try {
+        const db = openReadonlyExistingDatabase(getDbPath());
+        if (db) {
+            try {
+                embeddingCount = getEmbeddingCount(db);
+            }
+            finally {
+                closeDatabase(db);
+            }
+        }
+    }
+    catch {
+        // An index without an embeddings table (older layout) has none.
+    }
+    const entryCount = info.indexStats.entryCount;
+    return {
+        defaultBundle: config.defaultBundle ?? null,
+        defaultWriteTarget: config.defaultWriteTarget ?? null,
+        bundles: cards,
+        index: {
+            entryCount,
+            byType: info.indexStats.byType,
+            lastBuiltAt: info.indexStats.lastBuiltAt,
+            hasEmbeddings: info.indexStats.hasEmbeddings,
+            embeddingCount,
+            embeddingCoverage: embeddingCount !== null && entryCount > 0 ? Math.min(1, embeddingCount / entryCount) : null,
+            semanticSearch: info.semanticSearch,
+            ...(info.indexStats.links ? { links: info.indexStats.links } : {}),
+            ...(info.indexStats.unavailable ? { unavailable: info.indexStats.unavailable } : {}),
+            ...(info.indexStats.unreadable ? { unreadable: info.indexStats.unreadable } : {}),
+        },
+    };
+}
+/** Flatten to dotted leaf paths. Arrays and empty objects are leaves, matching how config layers merge. */
+function configLeaves(value, prefix, out) {
+    if (value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length > 0) {
+        for (const [key, child] of Object.entries(value))
+            configLeaves(child, [...prefix, key], out);
+        return;
+    }
+    out.push({ path: prefix, value });
+}
+function configSource(path) {
+    // `getConfigValueSource` takes a dotted path; a key that contains a dot cannot be told apart from two keys.
+    if (path.some((segment) => segment.includes(".")))
+        return null;
+    try {
+        const source = getConfigValueSource(path.join("."));
+        return source === "local" ? "file" : source;
+    }
+    catch {
+        return null;
+    }
+}
+function config() {
+    const effective = redactForUi(listConfig(loadConfig()));
+    const leaves = [];
+    configLeaves(effective, [], leaves);
+    const entries = leaves.map(({ path, value }) => ({
+        path: path.join("."),
+        value,
+        source: configSource(path),
+    }));
+    const engines = Object.entries((effective.engines ?? {})).map(([name, engine]) => ({
+        name,
+        ...engine,
+    }));
+    const env = Object.keys(process.env)
+        .filter((name) => name.startsWith("AKM_"))
+        .sort()
+        .map((name) => ({ name, value: isSecretEnvName(name) ? "[redacted]" : (process.env[name] ?? "") }));
+    const configPath = getConfigPath();
+    return { path: configPath, exists: fs.existsSync(configPath), config: effective, entries, engines, env };
+}
+// ── /api/proposals ───────────────────────────────────────────────────────────
+export function proposalSummary(proposal) {
+    const retirement = proposal.retirement;
+    return {
+        id: proposal.id,
+        source: proposal.source,
+        ref: proposal.ref,
+        status: proposal.status,
+        createdAt: proposal.createdAt,
+        updatedAt: proposal.updatedAt,
+        waitingSince: proposalWaitingSince(proposal),
+        confidence: proposal.confidence ?? null,
+        gateDecision: proposal.gateDecision ?? null,
+        review: proposal.review ?? null,
+        isRetire: isRetireProposal(proposal),
+        retirement: retirement
+            ? {
+                retiredRef: retirement.retiredRef,
+                successorRef: retirement.successorRef,
+                reason: retirement.reason,
+                judgeLabel: retirement.judgeLabel,
+                judgeReason: retirement.judgeReason,
+                cosine: retirement.cosine,
+                onlyInRetired: retirement.onlyInRetired ?? [],
+                onlyInSuccessor: retirement.onlyInSuccessor ?? [],
+                continuityRisk: retirement.continuityRisk ?? null,
+            }
+            : null,
+    };
+}
+const RECENT_STATUSES = new Set(["accepted", "rejected", "reverted"]);
+function proposals(query) {
+    const status = query.get("status") || "pending";
+    if (status !== "pending" && status !== "recent") {
+        throw new UsageError(`Invalid status "${status}". Expected pending or recent.`, "INVALID_FLAG_VALUE");
+    }
+    const limit = limitParam(query, 100);
+    return withReadonlyStateDb((db) => {
+        const all = listStateProposals(db, { stashDir: resolveStashDir() });
+        const picked = status === "pending"
+            ? all
+                .filter((p) => p.status === "pending")
+                .sort((a, b) => Date.parse(proposalWaitingSince(a)) - Date.parse(proposalWaitingSince(b)))
+            : all
+                .filter((p) => RECENT_STATUSES.has(p.status))
+                .sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt));
+        const bySource = {};
+        for (const proposal of picked)
+            bySource[proposal.source] = (bySource[proposal.source] ?? 0) + 1;
+        return {
+            status,
+            totalCount: picked.length,
+            bySource,
+            proposals: picked.slice(0, limit).map(proposalSummary),
+        };
+    }, { status, totalCount: 0, bySource: {}, proposals: [] });
+}
+/** Most characters of either side the detail view returns; a larger file is cut and flagged `truncated`. */
+export const DIFF_SIDE_MAX_CHARS = 512 * 1024;
+/** True when the proposal's target is an env or secret asset, whose content never leaves the machine's files via the UI. */
+function targetsSensitiveAsset(proposal) {
+    try {
+        const type = typeNameFromConceptId(parseBundleRef(proposal.ref).conceptId)?.type;
+        return type === "env" || type === "secret";
+    }
+    catch {
+        return false;
+    }
+}
+function capSide(text) {
+    if (text === null || text.length <= DIFF_SIDE_MAX_CHARS)
+        return { text, truncated: false };
+    return { text: text.slice(0, DIFF_SIDE_MAX_CHARS), truncated: true };
+}
+/**
+ * The diff for the detail view: akm's unified text plus both sides, so the client can line them up itself.
+ * `before`/`after` come from the same read as `unified` ({@link diffLoadedProposal}); they are `null` for a retire
+ * proposal (the file leaves, nothing is proposed) and, with `redacted`, for an env or secret target.
+ */
+function proposalDiffView(proposal) {
+    const result = diffLoadedProposal(loadConfig(), proposal);
+    const base = { isNew: result.isNew, targetPath: result.targetPath ?? null };
+    if (targetsSensitiveAsset(proposal)) {
+        return {
+            unified: "Env and secret values are never shown in the UI.",
+            ...base,
+            before: null,
+            after: null,
+            truncated: false,
+            redacted: true,
+        };
+    }
+    if (isRetireProposal(proposal)) {
+        return { unified: result.unified, ...base, before: null, after: null, truncated: false, redacted: false };
+    }
+    const before = capSide(result.existing);
+    const after = capSide(result.proposed);
+    return {
+        unified: result.unified,
+        ...base,
+        before: before.text,
+        after: after.text,
+        truncated: before.truncated || after.truncated,
+        redacted: false,
+    };
+}
+function proposalDetail(id) {
+    const detail = withReadonlyStateDb((db) => {
+        const proposal = resolveProposalIdIn(db, resolveStashDir(), id);
+        let diff = null;
+        let diffError = null;
+        try {
+            diff = proposalDiffView(proposal);
+        }
+        catch (error) {
+            diffError = error instanceof Error ? error.message : String(error);
+        }
+        // Content lives in the diff; `backupContent` is "never shown" by contract and the accept intent is internal.
+        const { backupContent: _backup, retireAcceptIntent: _intent, payload, changes, ...rest } = proposal;
+        return {
+            proposal: {
+                ...proposalSummary(proposal),
+                ...rest,
+                payload: { frontmatter: payload.frontmatter ?? null },
+                changes: changes.map((change) => ({ op: change.op, path: change.path })),
+            },
+            validation: validateProposal(proposal),
+            diff,
+            diffError,
+        };
+    }, null);
+    if (!detail)
+        throw new NotFoundError(`Proposal "${id}" not found: state.db is not available.`, "PROPOSAL_NOT_FOUND");
+    return detail;
+}
+// ── /api/changes ─────────────────────────────────────────────────────────────
+async function changes(query) {
+    const limit = limitParam(query);
+    const target = resolveWriteTarget(loadConfig(), undefined, { requireWritable: false });
+    const commits = await readRecentCommits(target.source.path, limit);
+    return {
+        bundle: target.source.name,
+        path: target.source.path,
+        git: commits !== null,
+        commits: commits ?? [],
+    };
+}
+// ── /api/search and /api/asset ───────────────────────────────────────────────
+async function search(query) {
+    const type = query.get("type") || undefined;
+    const bundle = query.get("bundle") || undefined;
+    return akmSearch({
+        query: (query.get("q") ?? "").trim(),
+        type,
+        limit: limitParam(query, 20),
+        // `--from <name>` narrows to one configured bundle; absent means every local bundle, as `akm search` does.
+        source: bundle ?? "local",
+        readOnly: true,
+    });
+}
+/** The durable `bundle//conceptId` of the indexed asset at `filePath`, the key feedback rows use. */
+function durableRefForPath(filePath) {
+    const db = openReadonlyExistingDatabase(getDbPath());
+    if (!db)
+        return null;
+    try {
+        const id = getEntryIdByFilePath(db, filePath);
+        return id === undefined ? null : getItemRefById(db, id);
+    }
+    finally {
+        closeDatabase(db);
+    }
+}
+function feedbackFor(durableRef) {
+    const empty = { counts: {}, history: [] };
+    if (!durableRef)
+        return empty;
+    return withReadonlyStateDb((db) => {
+        const history = listFeedbackEventRows(db, durableRef, 50).map((row) => {
+            let detail = {};
+            try {
+                detail = row.metadata ? JSON.parse(row.metadata) : {};
+            }
+            catch {
+                // Metadata is optional.
+            }
+            return {
+                // `created_at` is SQLite's `YYYY-MM-DD HH:MM:SS` in UTC.
+                at: new Date(`${row.created_at.replace(" ", "T")}Z`).toISOString(),
+                signal: row.signal,
+                source: row.source,
+                ...(typeof detail.reason === "string" ? { reason: detail.reason } : {}),
+                ...(Array.isArray(detail.tags) ? { tags: detail.tags } : {}),
+            };
+        });
+        return { counts: countFeedbackBySignal(db, durableRef), history };
+    }, empty);
+}
+async function asset(query) {
+    const ref = (query.get("ref") ?? "").trim();
+    if (!ref)
+        throw new UsageError("An asset ref is required: /api/asset?ref=<ref>.", "MISSING_REQUIRED_ARGUMENT");
+    const parsed = parseBundleRef(ref);
+    const type = typeNameFromConceptId(parsed.conceptId)?.type;
+    if (type === "env" || type === "secret") {
+        // Values never leave the machine's own files through the UI, whatever the renderers would show.
+        return { redacted: true, type, ref, note: "Env and secret values are never shown in the UI." };
+    }
+    const shown = await akmShowUnified({ ref, readOnly: true });
+    const durableRef = shown.path ? durableRefForPath(shown.path) : null;
+    return { redacted: false, durableRef, asset: shown, feedback: feedbackFor(durableRef) };
+}
+// ── Routing ──────────────────────────────────────────────────────────────────
+const ROUTES = {
+    "/api/meta": meta,
+    "/api/overview": overview,
+    "/api/bundles": bundles,
+    "/api/config": config,
+    "/api/proposals": proposals,
+    "/api/changes": changes,
+    "/api/search": search,
+    "/api/asset": asset,
+};
+const PROPOSAL_ROUTE = /^\/api\/proposals\/([^/]+)$/;
+/** What {@link handleApiRequest} returns for a path that is not an API route. */
+export const NO_SUCH_ROUTE = Symbol("no-such-route");
+/** Dispatch one `/api/...` request; handler errors propagate, an unknown route is {@link NO_SUCH_ROUTE}. */
+export async function handleApiRequest(pathname, query, info) {
+    const route = ROUTES[pathname];
+    if (route)
+        return route(query, info);
+    const proposalMatch = PROPOSAL_ROUTE.exec(pathname);
+    if (proposalMatch)
+        return proposalDetail(decodeURIComponent(proposalMatch[1]));
+    return NO_SUCH_ROUTE;
+}

package/dist/commands/ui/git-read.js

@@ -0,0 +1,101 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Read-only git queries for `akm ui`: a bundle's branch, ahead/behind and last
+ * commit, and the write-target stash's recent commits.
+ *
+ * Nothing here fetches, and nothing takes a lock: `GIT_OPTIONAL_LOCKS=0` keeps
+ * `git status` from refreshing the index, and ahead/behind is measured against
+ * the remote-tracking branch as the last `akm sync` left it. Calls are async so
+ * a slow repository stalls only its own request, not the server.
+ */
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+const GIT_TIMEOUT_MS = 10_000;
+/** `git log` output for a large accept can be big; cap what we buffer. */
+const GIT_MAX_BUFFER = 16 * 1024 * 1024;
+/** Paths listed per commit; `pathCount` still counts them all. */
+const PATHS_PER_COMMIT = 50;
+function git(repoDir, args) {
+    return new Promise((resolve) => {
+        execFile("git", ["-C", repoDir, "-c", "core.quotepath=false", ...args], {
+            encoding: "utf8",
+            timeout: GIT_TIMEOUT_MS,
+            maxBuffer: GIT_MAX_BUFFER,
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" },
+        }, (error, stdout) => resolve(error ? null : stdout));
+    });
+}
+/** Whether `dir` is the root of its own git repository (a bundle inside a larger repo is not reported as git-backed). */
+export function isGitRoot(dir) {
+    return fs.existsSync(path.join(dir, ".git"));
+}
+export async function readBundleGitStatus(repoDir) {
+    if (!isGitRoot(repoDir))
+        return null;
+    const [branch, upstream, status, last] = await Promise.all([
+        // symbolic-ref also names the branch of a repository with no commits yet; a detached HEAD has none.
+        git(repoDir, ["symbolic-ref", "--short", "-q", "HEAD"]),
+        git(repoDir, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]),
+        git(repoDir, ["status", "--porcelain"]),
+        git(repoDir, ["log", "-1", "--format=%H%x1f%cI%x1f%s"]),
+    ]);
+    let ahead = null;
+    let behind = null;
+    if (upstream?.trim()) {
+        const counts = (await git(repoDir, ["rev-list", "--left-right", "--count", "HEAD...@{u}"]))?.trim().split(/\s+/);
+        if (counts?.length === 2) {
+            ahead = Number(counts[0]);
+            behind = Number(counts[1]);
+        }
+    }
+    const [sha, time, subject] = (last ?? "").trim().split("\x1f");
+    return {
+        branch: branch?.trim() || null,
+        upstream: upstream?.trim() || null,
+        ahead,
+        behind,
+        dirtyPaths: status ? status.split("\n").filter((line) => line.trim() !== "").length : 0,
+        lastCommit: sha && time ? { sha, time, subject: subject ?? "" } : null,
+    };
+}
+export function classifyCommitOrigin(subject) {
+    if (/^akm improve\b/i.test(subject))
+        return "improve-sync";
+    if (/^akm (accept|proposal)\b/i.test(subject))
+        return "accept";
+    if (/\bremember\b/i.test(subject))
+        return "remember";
+    if (/^akm (save|sync)\b/i.test(subject))
+        return "sync";
+    return "other";
+}
+/** The `limit` most recent commits of the repository at `repoDir`, newest first; `null` when it is not a git root. */
+export async function readRecentCommits(repoDir, limit) {
+    if (!isGitRoot(repoDir))
+        return null;
+    const out = await git(repoDir, ["log", "-n", String(limit), "--name-only", "--format=%x1e%H%x1f%cI%x1f%an%x1f%s"]);
+    if (out === null)
+        return [];
+    const commits = [];
+    for (const record of out.split("\x1e")) {
+        if (!record.trim())
+            continue;
+        const [header = "", ...pathLines] = record.split("\n");
+        const [sha = "", time = "", author = "", subject = ""] = header.split("\x1f");
+        const paths = pathLines.map((line) => line.trim()).filter(Boolean);
+        commits.push({
+            sha,
+            shortSha: sha.slice(0, 8),
+            time,
+            author,
+            subject,
+            origin: classifyCommitOrigin(subject),
+            paths: paths.slice(0, PATHS_PER_COMMIT),
+            pathCount: paths.length,
+        });
+    }
+    return commits;
+}

package/dist/commands/ui/open-browser.js

@@ -0,0 +1,30 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { spawn } from "node:child_process";
+/** The command that opens `url` in the default browser on `platform`. */
+export function browserOpener(url, platform = process.platform) {
+    if (platform === "darwin")
+        return ["open", [url]];
+    // `start` is a cmd builtin; its first quoted argument is the window title, hence the empty one.
+    if (platform === "win32")
+        return ["cmd", ["/c", "start", '""', url]];
+    return ["xdg-open", [url]];
+}
+/** Open `url` in the default browser. Resolves `false` when no opener could be started; the caller prints the URL either way. */
+export function openBrowser(url) {
+    return new Promise((resolve) => {
+        const [command, args] = browserOpener(url);
+        try {
+            const child = spawn(command, args, { detached: true, stdio: "ignore", windowsVerbatimArguments: true });
+            child.once("error", () => resolve(false));
+            child.once("spawn", () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}