@loompad/cli 0.1.0

package/dist/core/eventlog.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Append-only per-project event log — Loom's source of truth.
+ *
+ * Primary store: node:sqlite (built into Node >= 22.5, zero native deps).
+ * Fallback store: JSONL (if node:sqlite is unavailable, or LOOM_STORE=jsonl).
+ */
+import type { EventKind, LoomEvent, NewEvent } from "../types.js";
+export interface ListOpts {
+    since?: number;
+    limit?: number;
+    kinds?: EventKind[];
+    /**
+     * Only this conversation. Asking for the main chat also returns events
+     * written before chats existed — they have no id and belong to it.
+     * Omit to read the whole project, which is what the brain wants.
+     */
+    chat?: string;
+}
+/** The store behind a project's log. Exported so search can take a narrow
+ * slice of it (list) rather than the whole EventLog — a searcher has no
+ * business being able to append. */
+export interface EventStore {
+    append(e: Required<Omit<NewEvent, "agentId" | "chat">> & {
+        agentId?: string;
+        chat?: string;
+    }): LoomEvent;
+    list(opts?: ListOpts): LoomEvent[];
+    lastId(): number;
+    close(): void;
+}
+export declare class EventLog {
+    private store;
+    private emitter;
+    private constructor();
+    /** Open (or create) the log inside a project's .loom directory. */
+    static open(loomDir: string): Promise<EventLog>;
+    append(e: NewEvent): LoomEvent;
+    list(opts?: ListOpts): LoomEvent[];
+    lastId(): number;
+    /** Live subscription to appended events; returns unsubscribe. */
+    onEvent(cb: (e: LoomEvent) => void): () => void;
+    close(): void;
+}

package/dist/core/eventlog.js

@@ -0,0 +1,211 @@
+/**
+ * Append-only per-project event log — Loom's source of truth.
+ *
+ * Primary store: node:sqlite (built into Node >= 22.5, zero native deps).
+ * Fallback store: JSONL (if node:sqlite is unavailable, or LOOM_STORE=jsonl).
+ */
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+import { MAIN_CHAT } from "../types.js";
+class SqliteStore {
+    db;
+    constructor(sqlite, file) {
+        this.db = new sqlite.DatabaseSync(file);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts INTEGER NOT NULL,
+        kind TEXT NOT NULL,
+        agent_id TEXT,
+        chat TEXT,
+        payload TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_events_kind ON events(kind, id);
+    `);
+        // Migrate BEFORE indexing chat. A log written before chats existed already
+        // has an `events` table, so CREATE TABLE IF NOT EXISTS is a no-op and the
+        // column is still missing — indexing it here would throw "no such column"
+        // and take the whole log down with it. Add the column, then index.
+        // The log is append-only and those events are history: a NULL chat reads
+        // as the main conversation rather than being rewritten.
+        const cols = this.db.prepare("PRAGMA table_info(events)").all();
+        if (!cols.some((c) => c.name === "chat")) {
+            this.db.exec("ALTER TABLE events ADD COLUMN chat TEXT");
+        }
+        this.db.exec("CREATE INDEX IF NOT EXISTS idx_events_chat ON events(chat, id)");
+    }
+    append(e) {
+        const stmt = this.db.prepare("INSERT INTO events (ts, kind, agent_id, chat, payload) VALUES (?, ?, ?, ?, ?)");
+        const res = stmt.run(e.ts, e.kind, e.agentId ?? null, e.chat ?? null, JSON.stringify(e.payload));
+        return {
+            id: Number(res.lastInsertRowid),
+            ts: e.ts,
+            kind: e.kind,
+            ...(e.agentId ? { agentId: e.agentId } : {}),
+            ...(e.chat ? { chat: e.chat } : {}),
+            payload: e.payload,
+        };
+    }
+    list(opts = {}) {
+        const clauses = [];
+        const params = [];
+        if (opts.since !== undefined) {
+            clauses.push("id > ?");
+            params.push(opts.since);
+        }
+        if (opts.kinds?.length) {
+            clauses.push(`kind IN (${opts.kinds.map(() => "?").join(",")})`);
+            params.push(...opts.kinds);
+        }
+        if (opts.chat !== undefined) {
+            if (opts.chat === MAIN_CHAT) {
+                // pre-chat history has no id and belongs to the main conversation
+                clauses.push("(chat = ? OR chat IS NULL)");
+            }
+            else {
+                clauses.push("chat = ?");
+            }
+            params.push(opts.chat);
+        }
+        const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+        // When limiting, we want the *most recent* N in ascending order.
+        const sql = opts.limit
+            ? `SELECT * FROM (SELECT * FROM events ${where} ORDER BY id DESC LIMIT ?) ORDER BY id ASC`
+            : `SELECT * FROM events ${where} ORDER BY id ASC`;
+        if (opts.limit)
+            params.push(opts.limit);
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map((r) => ({
+            id: Number(r.id),
+            ts: r.ts,
+            kind: r.kind,
+            ...(r.agent_id ? { agentId: r.agent_id } : {}),
+            ...(r.chat ? { chat: r.chat } : {}),
+            payload: JSON.parse(r.payload),
+        }));
+    }
+    lastId() {
+        const row = this.db.prepare("SELECT MAX(id) AS m FROM events").get();
+        return row?.m ? Number(row.m) : 0;
+    }
+    close() {
+        this.db.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// JSONL fallback store
+// ---------------------------------------------------------------------------
+class JsonlStore {
+    file;
+    nextId;
+    cache;
+    constructor(file) {
+        this.file = file;
+        this.cache = [];
+        if (fs.existsSync(file)) {
+            for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+                if (!line.trim())
+                    continue;
+                try {
+                    this.cache.push(JSON.parse(line));
+                }
+                catch {
+                    // Skip torn trailing writes; the log stays usable.
+                }
+            }
+        }
+        this.nextId = (this.cache[this.cache.length - 1]?.id ?? 0) + 1;
+    }
+    append(e) {
+        const ev = {
+            id: this.nextId++,
+            ts: e.ts,
+            kind: e.kind,
+            ...(e.agentId ? { agentId: e.agentId } : {}),
+            ...(e.chat ? { chat: e.chat } : {}),
+            payload: e.payload,
+        };
+        fs.appendFileSync(this.file, JSON.stringify(ev) + "\n");
+        this.cache.push(ev);
+        return ev;
+    }
+    list(opts = {}) {
+        let out = this.cache;
+        if (opts.since !== undefined)
+            out = out.filter((e) => e.id > opts.since);
+        if (opts.kinds?.length)
+            out = out.filter((e) => opts.kinds.includes(e.kind));
+        // must match SqliteStore exactly: an event with no chat is main's
+        if (opts.chat !== undefined) {
+            out = out.filter((e) => opts.chat === MAIN_CHAT ? (e.chat ?? MAIN_CHAT) === MAIN_CHAT : e.chat === opts.chat);
+        }
+        if (opts.limit && out.length > opts.limit)
+            out = out.slice(-opts.limit);
+        return [...out];
+    }
+    lastId() {
+        return this.cache[this.cache.length - 1]?.id ?? 0;
+    }
+    close() { }
+}
+// ---------------------------------------------------------------------------
+// EventLog facade
+// ---------------------------------------------------------------------------
+export class EventLog {
+    store;
+    emitter = new EventEmitter();
+    constructor(store) {
+        this.store = store;
+        this.emitter.setMaxListeners(100);
+    }
+    /** Open (or create) the log inside a project's .loom directory. */
+    static async open(loomDir) {
+        fs.mkdirSync(loomDir, { recursive: true });
+        if (process.env.LOOM_STORE !== "jsonl") {
+            let sqlite;
+            try {
+                sqlite = await import("node:sqlite");
+            }
+            catch {
+                // No node:sqlite in this runtime — the JSONL store is the whole point
+                // of the fallback. This is the ONLY thing it catches.
+                return new EventLog(new JsonlStore(path.join(loomDir, "log.jsonl")));
+            }
+            // Deliberately outside the catch. If node:sqlite exists but the log won't
+            // open — corrupt file, failed migration, bad permissions — falling back
+            // would silently start an EMPTY jsonl log beside a database full of your
+            // history, and write new events there. Losing the thread is worse than
+            // failing loudly, so this throws.
+            return new EventLog(new SqliteStore(sqlite, path.join(loomDir, "log.db")));
+        }
+        return new EventLog(new JsonlStore(path.join(loomDir, "log.jsonl")));
+    }
+    append(e) {
+        const ev = this.store.append({
+            ts: e.ts ?? Date.now(),
+            kind: e.kind,
+            payload: e.payload,
+            ...(e.agentId ? { agentId: e.agentId } : {}),
+            ...(e.chat ? { chat: e.chat } : {}),
+        });
+        this.emitter.emit("event", ev);
+        return ev;
+    }
+    list(opts) {
+        return this.store.list(opts);
+    }
+    lastId() {
+        return this.store.lastId();
+    }
+    /** Live subscription to appended events; returns unsubscribe. */
+    onEvent(cb) {
+        this.emitter.on("event", cb);
+        return () => this.emitter.off("event", cb);
+    }
+    close() {
+        this.emitter.removeAllListeners();
+        this.store.close();
+    }
+}
+//# sourceMappingURL=eventlog.js.map

package/dist/core/eventlog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventlog.js","sourceRoot":"","sources":["../../src/core/eventlog.ts"],"names":[],"mappings":"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"}

package/dist/core/git.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Source control that does something.
+ *
+ * worktree.ts reads: what changed, what the patch is. This writes: stage,
+ * unstage, discard, commit. The split is deliberate — reading is safe and runs
+ * on a timer, writing touches your repository and only ever happens because you
+ * clicked something.
+ *
+ * ## Why every path is checked instead of trusted
+ *
+ * These take file paths from an HTTP body, and `git checkout -- <path>` deletes
+ * your work. A path that escapes the project ("../../etc/…") would let a paired
+ * device discard files outside the repo entirely. Every path is resolved and
+ * confirmed to sit inside the project before git sees it, and `--` separates
+ * paths from flags so a file named `-f` can't become one.
+ *
+ * ## Why errors come back instead of being swallowed
+ *
+ * worktree.ts's git() resolves "" on failure, which is right for a read — a
+ * missing branch name isn't worth an exception. It is wrong for a write: a
+ * commit that silently does nothing is the worst outcome available. These throw
+ * with git's own stderr, which is nearly always the actual answer ("nothing to
+ * commit", "please tell me who you are").
+ */
+export declare class GitError extends Error {
+    readonly stderr: string;
+    constructor(message: string, stderr: string);
+}
+/**
+ * Keep a path inside the project.
+ *
+ * `git checkout -- <path>` is destructive and these paths arrive over HTTP from
+ * a device that could be anywhere on your tailnet. Resolve, then prove it's
+ * within the root — a prefix check on the un-normalised string would wave
+ * "../.." straight through.
+ */
+export declare function safeRelPath(dir: string, rel: string): string;
+export declare function isRepo(dir: string): Promise<boolean>;
+export declare function stage(dir: string, paths: string[]): Promise<{
+    staged: string[];
+}>;
+export declare function unstage(dir: string, paths: string[]): Promise<{
+    unstaged: string[];
+}>;
+/**
+ * Throw work away.
+ *
+ * The one operation here that can lose something you can't get back, so it is
+ * the one that is loudest in the log. Tracked files are restored from the
+ * index; untracked ones have nothing to restore to and must be deleted, which
+ * `git checkout` won't do — hence `clean -f` for those, and hence the split.
+ */
+export declare function discard(dir: string, paths: string[], untracked?: string[]): Promise<{
+    discarded: string[];
+}>;
+export interface CommitResult {
+    sha: string;
+    subject: string;
+    files: number;
+}
+/**
+ * Commit what's staged.
+ *
+ * Nothing is staged for you. "Commit all" is a convenience that has ended more
+ * afternoons than it saved — an agent's stray file swept into your commit
+ * because the button was easier than looking. If you want it in, stage it.
+ */
+export declare function commit(dir: string, message: string): Promise<CommitResult>;
+export interface GitStatus {
+    branch: string;
+    /** Commits ahead / behind the upstream, when there is one. */
+    ahead: number;
+    behind: number;
+    upstream: string | null;
+    staged: {
+        status: string;
+        path: string;
+    }[];
+    unstaged: {
+        status: string;
+        path: string;
+    }[];
+    untracked: string[];
+}
+/**
+ * The status the UI needs: staged and unstaged as separate lists.
+ *
+ * Porcelain's XY is two columns for a reason — X is the index, Y is the working
+ * tree — and a file can be in both at once (staged, then edited again). Flatten
+ * that into one list and you get a checkbox that lies about what a commit will
+ * contain.
+ */
+export declare function status(dir: string): Promise<GitStatus>;
+/**
+ * Start version control here.
+ *
+ * Refuses if the directory is already inside a repo, so an accidental click
+ * can't nest one repo inside another. Renames the initial branch to `main` when
+ * git left it on `master` — safe because a just-init'd repo has no commits, and
+ * it matches what remotes expect.
+ */
+export declare function init(dir: string): Promise<{
+    branch: string;
+}>;
+export interface Commit {
+    sha: string;
+    short: string;
+    subject: string;
+    author: string;
+    /** "2 hours ago" — git's own relative time. */
+    relative: string;
+    ts: number;
+}
+/** Recent commits, newest first. Empty in a repo whose first commit hasn't landed. */
+export declare function log(dir: string, limit?: number): Promise<Commit[]>;
+/**
+ * The unified diff for one file, HEAD → working tree (both staged and unstaged
+ * changes). Before the first commit there's no HEAD, so it diffs against the
+ * index instead. Empty string when nothing differs.
+ */
+export declare function fileDiff(dir: string, rel: string): Promise<string>;
+/**
+ * The diff a commit would capture — staged changes, or the whole working tree
+ * when nothing is staged yet. Used to write a commit message from. Bounded so a
+ * giant refactor doesn't blow the LLM's context (the summary only needs the
+ * shape of the change, not every line).
+ */
+export declare function stagedDiff(dir: string, maxChars?: number): Promise<string>;
+export interface Branches {
+    current: string;
+    all: string[];
+}
+/** Local branches and which one is checked out — for the checkout picker. */
+export declare function branches(dir: string): Promise<Branches>;
+/**
+ * Switch to a branch or commit.
+ *
+ * git refuses on its own when the switch would overwrite uncommitted changes,
+ * and that refusal (with its list of the files at risk) is exactly the message
+ * to surface — so we don't second-guess it, we just pass its stderr back. The
+ * ref is character-validated because it reaches a git command, though `--`
+ * already stops it being read as a flag.
+ */
+export declare function checkout(dir: string, ref: string): Promise<{
+    ref: string;
+    branch: string;
+}>;
+/**
+ * How far behind (and ahead of) the upstream this checkout is — for "check for
+ * updates". Fetches first (bounded), so it reflects the remote, not a stale
+ * local ref. null when the dir isn't a git checkout; behind 0 with no upstream
+ * means "nothing to compare against", not "up to date".
+ */
+export declare function remoteBehind(dir: string): Promise<{
+    behind: number;
+    ahead: number;
+    branch: string;
+    hasUpstream: boolean;
+} | null>;
+/**
+ * Push to the upstream, setting it on the first push.
+ *
+ * A branch with no upstream needs `-u origin <branch>` once; after that a bare
+ * `git push` is enough. Either way the network is bounded (gitNet) and auth is
+ * the user's own credential helper. A repo with no remote at all fails with
+ * git's "No configured push destination", which is the honest answer.
+ */
+export declare function push(dir: string): Promise<{
+    branch: string;
+    detail: string;
+}>;
+export interface Worktree {
+    path: string;
+    /** null when the worktree is detached (e.g. mid-review of a fork PR). */
+    branch: string | null;
+    head: string;
+    /** The repo's own main working tree — you can't remove this one. */
+    main?: boolean;
+}
+/** Where a new worktree for this repo goes: `<repo>--<slug>`, a sibling. */
+export declare function worktreePath(dir: string, slug: string): string;
+export declare function listWorktrees(dir: string): Promise<Worktree[]>;
+/**
+ * Open a worktree. Three shapes:
+ *  - `newBranch`: cut a fresh branch off `base` (default HEAD) — used for an
+ *    issue or a card you want to start.
+ *  - `branch`: check out an existing (or DWIM-remote) branch.
+ *  - `detached`: park at HEAD, for the caller to `gh pr checkout` into (handles
+ *    fork PRs, which have no local branch).
+ * Returns the created path; `git worktree add` refuses to clobber, so an
+ * existing path surfaces git's own error rather than overwriting work.
+ */
+export declare function addWorktree(dir: string, opts: {
+    slug: string;
+    branch?: string;
+    newBranch?: string;
+    base?: string;
+    detached?: boolean;
+}): Promise<{
+    path: string;
+    branch: string | null;
+}>;
+export declare function removeWorktree(dir: string, wtPath: string, force?: boolean): Promise<void>;