@sunshinelife83/hearth 1.0.0

package/dist/db/client.js

@@ -0,0 +1,29 @@
+import { chmodSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import * as schema from "./schema.js";
+import { migrateDatabase } from "./migrations.js";
+export function databasePath(stateDir) {
+    return join(stateDir, "hearth.sqlite");
+}
+export function openDatabase(stateDir) {
+    mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    chmodSync(stateDir, 0o700);
+    const path = databasePath(stateDir);
+    const sqlite = new Database(path);
+    chmodSync(path, 0o600);
+    sqlite.pragma("journal_mode = WAL");
+    sqlite.pragma("synchronous = NORMAL");
+    sqlite.pragma("busy_timeout = 5000");
+    sqlite.pragma("foreign_keys = ON");
+    migrateDatabase(sqlite);
+    return {
+        sqlite,
+        db: createDrizzleDatabase(sqlite),
+        close: () => sqlite.close(),
+    };
+}
+function createDrizzleDatabase(sqlite) {
+    return drizzle(sqlite, { schema });
+}

package/dist/db/migrations.js

@@ -0,0 +1,262 @@
+const migrations = [
+    {
+        version: 1,
+        name: "workspace-state",
+        up: migrateWorkspaceState,
+    },
+    {
+        version: 2,
+        name: "oauth-state",
+        up: migrateOAuthState,
+    },
+    {
+        version: 3,
+        name: "local-agent-sessions",
+        up: migrateLocalAgentSessions,
+    },
+    {
+        version: 4,
+        name: "workspace-conversation-bindings",
+        up: migrateWorkspaceConversationBindings,
+    },
+    {
+        version: 5,
+        name: "local-agent-structured-errors",
+        up: migrateLocalAgentStructuredErrors,
+    },
+    {
+        version: 6,
+        name: "local-agent-effort-rename",
+        up: migrateLocalAgentEffortRename,
+    },
+    {
+        version: 7,
+        name: "local-agent-lifecycle-output",
+        up: migrateLocalAgentLifecycleOutput,
+    },
+    {
+        version: 8,
+        name: "device-tokens",
+        up: migrateDeviceTokens,
+    },
+    {
+        version: 9,
+        name: "task-runtime",
+        up: migrateTaskRuntime,
+    },
+];
+export function migrateDatabase(sqlite) {
+    const migrate = sqlite.transaction(() => {
+        sqlite.exec(`
+      create table if not exists hearth_schema_migrations (
+        version integer primary key,
+        name text not null,
+        applied_at text not null
+      );
+    `);
+        const applied = new Set(sqlite.prepare("select version from hearth_schema_migrations").all().map((row) => row.version));
+        const recordMigration = sqlite.prepare("insert into hearth_schema_migrations (version, name, applied_at) values (?, ?, ?)");
+        for (const migration of migrations) {
+            if (applied.has(migration.version))
+                continue;
+            migration.up(sqlite);
+            recordMigration.run(migration.version, migration.name, new Date().toISOString());
+        }
+    });
+    migrate.immediate();
+}
+function migrateWorkspaceState(sqlite) {
+    sqlite.exec(`
+    create table if not exists workspace_sessions (
+      id text primary key,
+      root text not null,
+      status text not null default 'active',
+      mode text not null default 'checkout',
+      source_root text,
+      base_ref text,
+      base_sha text,
+      managed text not null default 'false',
+      created_at text not null,
+      last_used_at text not null
+    );
+
+    create index if not exists workspace_sessions_root_idx
+      on workspace_sessions(root, last_used_at desc);
+
+    create index if not exists workspace_sessions_status_idx
+      on workspace_sessions(status, last_used_at desc);
+
+    create table if not exists loaded_agent_files (
+      workspace_session_id text not null,
+      path text not null,
+      content_hash text not null,
+      content text not null,
+      loaded_at text not null,
+      last_seen_at text not null,
+      primary key (workspace_session_id, path),
+      foreign key (workspace_session_id)
+        references workspace_sessions(id)
+        on delete cascade
+    );
+
+    create index if not exists loaded_agent_files_path_idx
+      on loaded_agent_files(path);
+  `);
+    addColumnIfMissing(sqlite, "workspace_sessions", "mode", "text not null default 'checkout'");
+    addColumnIfMissing(sqlite, "workspace_sessions", "source_root", "text");
+    addColumnIfMissing(sqlite, "workspace_sessions", "base_ref", "text");
+    addColumnIfMissing(sqlite, "workspace_sessions", "base_sha", "text");
+    addColumnIfMissing(sqlite, "workspace_sessions", "managed", "text not null default 'false'");
+}
+function migrateOAuthState(sqlite) {
+    sqlite.exec(`
+    create table if not exists oauth_clients (
+      client_id text primary key,
+      client_json text not null,
+      issued_at integer not null
+    );
+
+    create index if not exists oauth_clients_issued_at_idx
+      on oauth_clients(issued_at desc);
+
+    create table if not exists oauth_access_tokens (
+      token_hash text primary key,
+      client_id text not null,
+      scopes_json text not null,
+      expires_at integer not null,
+      resource text,
+      foreign key (client_id) references oauth_clients(client_id) on delete cascade
+    );
+
+    create index if not exists oauth_access_tokens_client_id_idx
+      on oauth_access_tokens(client_id);
+
+    create index if not exists oauth_access_tokens_expires_at_idx
+      on oauth_access_tokens(expires_at);
+
+    create table if not exists oauth_refresh_tokens (
+      token_hash text primary key,
+      client_id text not null,
+      scopes_json text not null,
+      expires_at integer not null,
+      resource text,
+      foreign key (client_id) references oauth_clients(client_id) on delete cascade
+    );
+
+    create index if not exists oauth_refresh_tokens_client_id_idx
+      on oauth_refresh_tokens(client_id);
+
+    create index if not exists oauth_refresh_tokens_expires_at_idx
+      on oauth_refresh_tokens(expires_at);
+  `);
+}
+function migrateLocalAgentSessions(sqlite) {
+    sqlite.exec(`
+    create table if not exists local_agent_sessions (
+      id text primary key,
+      workspace_id text,
+      workspace_root text not null,
+      profile_name text not null,
+      provider text not null,
+      model text,
+      effort text,
+      provider_session_id text,
+      status text not null,
+      latest_response text,
+      error text,
+      created_at text not null,
+      updated_at text not null
+    );
+
+    create index if not exists local_agent_sessions_workspace_id_idx
+      on local_agent_sessions(workspace_id, updated_at desc);
+
+    create index if not exists local_agent_sessions_workspace_root_idx
+      on local_agent_sessions(workspace_root, updated_at desc);
+
+    create index if not exists local_agent_sessions_provider_session_id_idx
+      on local_agent_sessions(provider_session_id);
+  `);
+    addColumnIfMissing(sqlite, "local_agent_sessions", "effort", "text");
+}
+function migrateWorkspaceConversationBindings(sqlite) {
+    sqlite.exec(`
+    create table if not exists workspace_conversation_bindings (
+      conversation_scope_id text not null,
+      target_key text not null,
+      workspace_session_id text not null,
+      created_at text not null,
+      last_used_at text not null,
+      primary key (conversation_scope_id, target_key),
+      foreign key (workspace_session_id)
+        references workspace_sessions(id)
+        on delete cascade
+    );
+
+    create index if not exists workspace_conversation_bindings_workspace_idx
+      on workspace_conversation_bindings(workspace_session_id);
+  `);
+}
+function migrateLocalAgentStructuredErrors(sqlite) {
+    addColumnIfMissing(sqlite, "local_agent_sessions", "error_code", "text");
+    addColumnIfMissing(sqlite, "local_agent_sessions", "error_retryable", "text");
+}
+function migrateLocalAgentEffortRename(sqlite) {
+    const columns = sqlite.prepare("pragma table_info(local_agent_sessions)").all();
+    const names = new Set(columns.map((column) => column.name));
+    if (names.has("effort")) {
+        if (names.has("thinking")) {
+            sqlite.exec(`
+        update local_agent_sessions
+        set effort = thinking
+        where effort is null and thinking is not null
+      `);
+        }
+        return;
+    }
+    if (!names.has("thinking")) {
+        addColumnIfMissing(sqlite, "local_agent_sessions", "effort", "text");
+        return;
+    }
+    sqlite.exec("alter table local_agent_sessions rename column thinking to effort");
+}
+function migrateLocalAgentLifecycleOutput(sqlite) {
+    addColumnIfMissing(sqlite, "local_agent_sessions", "latest_output", "text");
+}
+function migrateDeviceTokens(sqlite) {
+    sqlite.exec(`
+    create table if not exists device_tokens (
+      token_hash text primary key,
+      name text not null,
+      created_at text not null,
+      last_used_at text
+    );
+  `);
+}
+function migrateTaskRuntime(sqlite) {
+    sqlite.exec(`
+    create table if not exists tasks (
+      id text primary key,
+      workspace_id text,
+      workspace_root text not null,
+      goal text not null,
+      status text not null,
+      completion_state text,
+      mode text not null,
+      plan text,
+      evidence text,
+      error text,
+      tool_calls integer not null default 0,
+      created_at text not null,
+      updated_at text not null
+    );
+    create index if not exists tasks_workspace_idx on tasks(workspace_id, updated_at desc);
+    create index if not exists tasks_status_idx on tasks(status, updated_at desc);
+  `);
+}
+function addColumnIfMissing(sqlite, table, column, definition) {
+    const columns = sqlite.prepare(`pragma table_info(${table})`).all();
+    if (columns.some((existingColumn) => existingColumn.name === column))
+        return;
+    sqlite.exec(`alter table ${table} add column ${column} ${definition}`);
+}

package/dist/db/schema.js

@@ -0,0 +1,85 @@
+import { index, integer, primaryKey, sqliteTable, text } from "drizzle-orm/sqlite-core";
+export const workspaceSessions = sqliteTable("workspace_sessions", {
+    id: text("id").primaryKey(),
+    root: text("root").notNull(),
+    status: text("status").notNull().default("active"),
+    mode: text("mode").notNull().default("checkout"),
+    sourceRoot: text("source_root"),
+    baseRef: text("base_ref"),
+    baseSha: text("base_sha"),
+    managed: text("managed").notNull().default("false"),
+    createdAt: text("created_at").notNull(),
+    lastUsedAt: text("last_used_at").notNull(),
+}, (table) => [
+    index("workspace_sessions_root_idx").on(table.root, table.lastUsedAt),
+    index("workspace_sessions_status_idx").on(table.status, table.lastUsedAt),
+]);
+export const loadedAgentFiles = sqliteTable("loaded_agent_files", {
+    workspaceSessionId: text("workspace_session_id")
+        .notNull()
+        .references(() => workspaceSessions.id, { onDelete: "cascade" }),
+    path: text("path").notNull(),
+    contentHash: text("content_hash").notNull(),
+    content: text("content").notNull(),
+    loadedAt: text("loaded_at").notNull(),
+    lastSeenAt: text("last_seen_at").notNull(),
+}, (table) => [
+    primaryKey({ columns: [table.workspaceSessionId, table.path] }),
+    index("loaded_agent_files_path_idx").on(table.path),
+]);
+export const workspaceConversationBindings = sqliteTable("workspace_conversation_bindings", {
+    conversationScopeId: text("conversation_scope_id").notNull(),
+    targetKey: text("target_key").notNull(),
+    workspaceSessionId: text("workspace_session_id")
+        .notNull()
+        .references(() => workspaceSessions.id, { onDelete: "cascade" }),
+    createdAt: text("created_at").notNull(),
+    lastUsedAt: text("last_used_at").notNull(),
+}, (table) => [
+    primaryKey({ columns: [table.conversationScopeId, table.targetKey] }),
+    index("workspace_conversation_bindings_workspace_idx").on(table.workspaceSessionId),
+]);
+export const oauthClients = sqliteTable("oauth_clients", {
+    clientId: text("client_id").primaryKey(),
+    clientJson: text("client_json").notNull(),
+    issuedAt: integer("issued_at").notNull(),
+});
+export const oauthAccessTokens = sqliteTable("oauth_access_tokens", {
+    tokenHash: text("token_hash").primaryKey(),
+    clientId: text("client_id")
+        .notNull()
+        .references(() => oauthClients.clientId, { onDelete: "cascade" }),
+    scopesJson: text("scopes_json").notNull(),
+    expiresAt: integer("expires_at").notNull(),
+    resource: text("resource"),
+});
+export const oauthRefreshTokens = sqliteTable("oauth_refresh_tokens", {
+    tokenHash: text("token_hash").primaryKey(),
+    clientId: text("client_id")
+        .notNull()
+        .references(() => oauthClients.clientId, { onDelete: "cascade" }),
+    scopesJson: text("scopes_json").notNull(),
+    expiresAt: integer("expires_at").notNull(),
+    resource: text("resource"),
+});
+export const localAgentSessions = sqliteTable("local_agent_sessions", {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id"),
+    workspaceRoot: text("workspace_root").notNull(),
+    profileName: text("profile_name").notNull(),
+    provider: text("provider").notNull(),
+    model: text("model"),
+    effort: text("effort"),
+    providerSessionId: text("provider_session_id"),
+    status: text("status").notNull(),
+    latestResponse: text("latest_response"),
+    error: text("error"),
+    errorCode: text("error_code"),
+    errorRetryable: text("error_retryable"),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+}, (table) => [
+    index("local_agent_sessions_workspace_id_idx").on(table.workspaceId, table.updatedAt),
+    index("local_agent_sessions_workspace_root_idx").on(table.workspaceRoot, table.updatedAt),
+    index("local_agent_sessions_provider_session_id_idx").on(table.providerSessionId),
+]);

package/dist/device-tokens.js

@@ -0,0 +1,61 @@
+import { randomBytes } from "node:crypto";
+import { createHash } from "node:crypto";
+import { openDatabase } from "./db/client.js";
+const DEVICE_TOKEN_PREFIX = "dvst_";
+export class DeviceTokenStore {
+    database;
+    constructor(stateDir) {
+        this.database = openDatabase(stateDir);
+    }
+    /** Returns the plaintext token exactly once; only the hash is persisted. */
+    create(name) {
+        const token = `${DEVICE_TOKEN_PREFIX}${randomBytes(32).toString("base64url")}`;
+        const now = new Date().toISOString();
+        this.database.sqlite
+            .prepare(`insert into device_tokens (token_hash, name, created_at) values (?, ?, ?)
+         on conflict(token_hash) do nothing`)
+            .run(hashToken(token), name, now);
+        return { token, record: { name, createdAt: now } };
+    }
+    /** Verifies a presented token, refreshing last_used_at. */
+    verify(token) {
+        if (!token.startsWith(DEVICE_TOKEN_PREFIX))
+            return undefined;
+        const hash = hashToken(token);
+        const row = this.database.sqlite
+            .prepare("select name, created_at, last_used_at from device_tokens where token_hash = ?")
+            .get(hash);
+        if (!row)
+            return undefined;
+        this.database.sqlite
+            .prepare("update device_tokens set last_used_at = ? where token_hash = ?")
+            .run(new Date().toISOString(), hash);
+        return {
+            name: row.name,
+            createdAt: row.created_at,
+            ...(row.last_used_at ? { lastUsedAt: row.last_used_at } : {}),
+        };
+    }
+    list() {
+        const rows = this.database.sqlite
+            .prepare("select name, created_at, last_used_at from device_tokens order by created_at desc")
+            .all();
+        return rows.map((row) => ({
+            name: row.name,
+            createdAt: row.created_at,
+            ...(row.last_used_at ? { lastUsedAt: row.last_used_at } : {}),
+        }));
+    }
+    revoke(name) {
+        const result = this.database.sqlite
+            .prepare("delete from device_tokens where name = ?")
+            .run(name);
+        return Number(result.changes) > 0;
+    }
+    close() {
+        this.database.close();
+    }
+}
+function hashToken(token) {
+    return createHash("sha256").update(token).digest("base64url");
+}

package/dist/git-worktrees.js

@@ -0,0 +1,134 @@
+import { randomBytes } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdir, realpath, rm, stat } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import { assertAllowedPath, isPathInsideRoot } from "./roots.js";
+const execFileAsync = promisify(execFile);
+export class GitWorktreeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "GitWorktreeError";
+    }
+}
+export async function createManagedWorktree(input) {
+    const sourcePath = assertAllowedPath(input.sourcePath, input.config.allowedRoots);
+    try {
+        const sourceStats = await stat(sourcePath);
+        if (!sourceStats.isDirectory()) {
+            throw new GitWorktreeError("GIT_REPOSITORY_NOT_FOUND", `Cannot open workspace in worktree mode because the source path is not a directory: ${input.sourcePath}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof GitWorktreeError)
+            throw error;
+        throw new GitWorktreeError("GIT_REPOSITORY_NOT_FOUND", `Cannot open workspace in worktree mode because the source path does not exist: ${input.sourcePath}`);
+    }
+    const sourceRoot = await resolveGitRoot(sourcePath, input.config.allowedRoots);
+    const baseRef = input.baseRef ?? "HEAD";
+    const baseSha = await resolveBaseCommit(sourceRoot, baseRef);
+    const dirtySource = (await git(["status", "--porcelain=v1"], sourceRoot)).trim().length > 0;
+    const worktreePath = managedWorktreePath({
+        worktreeRoot: input.config.worktreeRoot,
+        repoRoot: sourceRoot,
+    });
+    await mkdir(input.config.worktreeRoot, { recursive: true });
+    assertAllowedPath(worktreePath, [input.config.worktreeRoot]);
+    try {
+        await git(["worktree", "add", "--detach", worktreePath, baseSha], sourceRoot);
+    }
+    catch (error) {
+        await rm(worktreePath, { recursive: true, force: true });
+        const message = error instanceof Error ? error.message : String(error);
+        throw new GitWorktreeError("GIT_WORKTREE_CREATE_FAILED", `Git failed to create the managed worktree. ${message}`);
+    }
+    return {
+        sourceRoot,
+        path: worktreePath,
+        baseRef,
+        baseSha,
+        dirtySource,
+        detached: true,
+        managed: true,
+    };
+}
+async function resolveGitRoot(path, allowedRoots) {
+    try {
+        const output = await git(["rev-parse", "--show-toplevel"], path);
+        return await assertGitRootAllowed(output.trim(), allowedRoots);
+    }
+    catch (error) {
+        if (isGitUnavailable(error)) {
+            throw new GitWorktreeError("GIT_NOT_AVAILABLE", "Cannot open workspace in worktree mode because Git is not available on this machine.");
+        }
+        throw new GitWorktreeError("GIT_REPOSITORY_NOT_FOUND", `Cannot open workspace in worktree mode because this path is not inside a Git repository: ${path}. Use mode=\"checkout\" to work directly in this directory, or initialize Git and create an initial commit first.`);
+    }
+}
+async function assertGitRootAllowed(gitRoot, allowedRoots) {
+    try {
+        return assertAllowedPath(gitRoot, allowedRoots);
+    }
+    catch {
+        const canonicalGitRoot = await realpath(gitRoot);
+        for (const allowedRoot of allowedRoots) {
+            const canonicalAllowedRoot = await realpath(allowedRoot).catch(() => undefined);
+            if (!canonicalAllowedRoot || !isPathInsideRoot(canonicalGitRoot, canonicalAllowedRoot)) {
+                continue;
+            }
+            const logicalGitRoot = resolve(allowedRoot, relative(canonicalAllowedRoot, canonicalGitRoot));
+            return assertAllowedPath(logicalGitRoot, allowedRoots);
+        }
+        return assertAllowedPath(canonicalGitRoot, allowedRoots);
+    }
+}
+async function resolveBaseCommit(sourceRoot, baseRef) {
+    try {
+        return (await git(["rev-parse", "--verify", `${baseRef}^{commit}`], sourceRoot)).trim();
+    }
+    catch (error) {
+        if (baseRef === "HEAD") {
+            throw new GitWorktreeError("GIT_REPOSITORY_HAS_NO_COMMITS", "Cannot open workspace in worktree mode because the repository has no commits yet. Create an initial commit first, or use mode=\"checkout\".");
+        }
+        throw new GitWorktreeError("GIT_INVALID_BASE_REF", `Cannot open workspace in worktree mode because baseRef ${JSON.stringify(baseRef)} does not resolve to a commit.`);
+    }
+}
+function managedWorktreePath(input) {
+    const repoName = sanitizePathSegment(basename(input.repoRoot)) || "repo";
+    const worktreeId = randomBytes(4).toString("hex");
+    return join(input.worktreeRoot, `${repoName}-${worktreeId}`);
+}
+function sanitizePathSegment(value) {
+    return value
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+async function git(args, cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", args, {
+            cwd,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch (error) {
+        if (isGitUnavailable(error))
+            throw error;
+        const stderr = typeof error === "object" && error && "stderr" in error
+            ? String(error.stderr ?? "").trim()
+            : "";
+        const stdout = typeof error === "object" && error && "stdout" in error
+            ? String(error.stdout ?? "").trim()
+            : "";
+        const details = stderr || stdout || (error instanceof Error ? error.message : String(error));
+        throw new Error(details);
+    }
+}
+function isGitUnavailable(error) {
+    return Boolean(typeof error === "object" &&
+        error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/git.js

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export async function git(cwd, args, options = {}) {
+    const { stdout, stderr } = await execFileAsync("git", args, {
+        cwd,
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        maxBuffer: options.maxBuffer ?? 10 * 1024 * 1024,
+    });
+    return { stdout, stderr };
+}
+export async function getGitEligibility(cwd) {
+    try {
+        await git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+    }
+    catch {
+        return {
+            ok: false,
+            reason: "not_git",
+            message: "workspace is not inside a git repository",
+        };
+    }
+    const gitRoot = (await git(cwd, ["rev-parse", "--show-toplevel"])).stdout.trim();
+    try {
+        await git(gitRoot, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+    }
+    catch {
+        return {
+            ok: false,
+            gitRoot,
+            reason: "no_head",
+            message: "repository has no HEAD commit",
+        };
+    }
+    return { ok: true, gitRoot };
+}
+export function safeWorkspaceRefSegment(workspaceId) {
+    const safe = workspaceId.replace(/[^A-Za-z0-9._-]/g, "-");
+    return safe.length > 0 ? safe : createHash("sha256").update(workspaceId).digest("hex").slice(0, 16);
+}