@sunshinelife83/hearth 1.0.0

package/dist/review-checkpoints.js

@@ -0,0 +1,349 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { git, getGitEligibility, safeWorkspaceRefSegment } from "./git.js";
+const REVIEW_REF_PREFIX = "refs/hearth/review";
+export function createReviewCheckpointManager() {
+    const states = new Map();
+    const initializations = new Map();
+    return {
+        async initializeWorkspace({ workspaceId, root }) {
+            const existingState = states.get(workspaceId);
+            assertWorkspaceRoot(existingState, workspaceId, root);
+            if (existingState?.root === root && existingState.gitRoot !== undefined) {
+                return reviewAvailability(existingState);
+            }
+            const pending = initializations.get(workspaceId);
+            if (pending) {
+                await pending;
+                const initializedState = states.get(workspaceId);
+                assertWorkspaceRoot(initializedState, workspaceId, root);
+                return reviewAvailability(initializedState);
+            }
+            const initialize = initializeWorkspaceState(states, workspaceId, root);
+            initializations.set(workspaceId, initialize);
+            try {
+                await initialize;
+            }
+            finally {
+                if (initializations.get(workspaceId) === initialize) {
+                    initializations.delete(workspaceId);
+                }
+            }
+            return reviewAvailability(states.get(workspaceId));
+        },
+        async reviewChanges({ workspaceId, root, since = "last_shown", markReviewed = true }) {
+            let state = states.get(workspaceId);
+            assertWorkspaceRoot(state, workspaceId, root);
+            if (!isReadyState(state)) {
+                await this.initializeWorkspace({ workspaceId, root });
+                state = states.get(workspaceId);
+            }
+            assertWorkspaceRoot(state, workspaceId, root);
+            if (!state?.gitRoot) {
+                throw new Error(state?.diagnostic ?? "show_changes requires a Git workspace in this version.");
+            }
+            let effectiveSince = since;
+            let usedWorkspaceOpenFallback = false;
+            if (since === "last_shown" && !state.baselineRefAvailable) {
+                if (!state.openRefAvailable) {
+                    throw new Error("Review checkpoints are missing; show_changes cannot reconstruct that history safely.");
+                }
+                effectiveSince = "workspace_open";
+                usedWorkspaceOpenFallback = true;
+            }
+            else if (since === "workspace_open" && !state.openRefAvailable) {
+                throw new Error("The workspace-open review checkpoint is missing; show_changes cannot reconstruct that history safely.");
+            }
+            const baselineRef = effectiveSince === "workspace_open" ? state.openRef : state.baselineRef;
+            const baseline = (await git(state.gitRoot, ["rev-parse", "--verify", `${baselineRef}^{commit}`])).stdout.trim();
+            const current = await createWorkingTreeSnapshot(state.gitRoot, baseline);
+            const review = await readReviewBetween(state.gitRoot, baseline, current);
+            if (markReviewed) {
+                await git(state.gitRoot, ["update-ref", state.baselineRef, current]);
+                state.baselineRefAvailable = true;
+            }
+            const fallbackNote = usedWorkspaceOpenFallback
+                ? ` The last-shown checkpoint was missing, so changes were compared from workspace open${markReviewed ? " and the baseline was re-established" : ""}.`
+                : "";
+            return {
+                reviewRef: current,
+                result: `${review.summary.files === 0
+                    ? `No changes since ${effectiveSince === "workspace_open" ? "workspace open" : "last shown changes"}.`
+                    : formatChangedFiles(review.summary)}${fallbackNote}`,
+                ...review,
+            };
+        },
+        async reviewByRef({ workspaceId, root, reviewRef }) {
+            let state = states.get(workspaceId);
+            assertWorkspaceRoot(state, workspaceId, root);
+            if (!isReadyState(state)) {
+                await this.initializeWorkspace({ workspaceId, root });
+                state = states.get(workspaceId);
+            }
+            assertWorkspaceRoot(state, workspaceId, root);
+            if (!state?.gitRoot) {
+                throw new Error(state?.diagnostic ?? "show_changes requires a Git workspace in this version.");
+            }
+            const [openCommit, baselineCommit, reviewCommit] = await Promise.all([
+                commitForRef(state.gitRoot, state.openRef),
+                commitForRef(state.gitRoot, state.baselineRef),
+                resolveReviewCommitOrUndefined(state.gitRoot, reviewRef),
+            ]);
+            if (!openCommit
+                || !baselineCommit
+                || !reviewCommit
+                || reviewCommit === openCommit) {
+                throw new Error(`Unknown review reference for workspace ${workspaceId}: ${reviewRef}`);
+            }
+            const [isAfterOpen, isBeforeBaseline] = await Promise.all([
+                isAncestor(state.gitRoot, openCommit, reviewCommit),
+                isAncestor(state.gitRoot, reviewCommit, baselineCommit),
+            ]);
+            if (!isAfterOpen || !isBeforeBaseline) {
+                throw new Error(`Unknown review reference for workspace ${workspaceId}: ${reviewRef}`);
+            }
+            return readReviewCommit(state.gitRoot, reviewCommit);
+        },
+    };
+}
+export async function readReviewRef(root, reviewRef) {
+    const eligibility = await getGitEligibility(root);
+    if (!eligibility.ok || !eligibility.gitRoot) {
+        throw new Error(eligibility.message ?? "show-changes requires a Git workspace.");
+    }
+    const commit = await resolveReviewCommit(eligibility.gitRoot, reviewRef);
+    if (!await isKnownReviewCommit(eligibility.gitRoot, commit)) {
+        throw new Error(`Unknown Hearth review reference: ${reviewRef}`);
+    }
+    return readReviewCommit(eligibility.gitRoot, commit);
+}
+function assertWorkspaceRoot(state, workspaceId, root) {
+    if (state && state.root !== root) {
+        throw new Error(`Review checkpoint workspace root mismatch for ${workspaceId}.`);
+    }
+}
+async function initializeWorkspaceState(states, workspaceId, root) {
+    const refs = reviewRefs(workspaceId);
+    const state = {
+        root,
+        ...refs,
+        openRefAvailable: false,
+        baselineRefAvailable: false,
+    };
+    try {
+        const eligibility = await getGitEligibility(root);
+        if (!eligibility.ok || !eligibility.gitRoot) {
+            state.diagnostic = eligibility.message ?? "show_changes requires a Git workspace in this version.";
+            return;
+        }
+        const [openCommit, baselineCommit] = await Promise.all([
+            commitForRef(eligibility.gitRoot, state.openRef),
+            commitForRef(eligibility.gitRoot, state.baselineRef),
+        ]);
+        if (!openCommit && !baselineCommit) {
+            const head = (await git(eligibility.gitRoot, ["rev-parse", "--verify", "HEAD^{commit}"])).stdout.trim();
+            const initialCommit = await createWorkingTreeSnapshot(eligibility.gitRoot, head);
+            await git(eligibility.gitRoot, ["update-ref", state.openRef, initialCommit]);
+            await git(eligibility.gitRoot, ["update-ref", state.baselineRef, initialCommit]);
+            state.openRefAvailable = true;
+            state.baselineRefAvailable = true;
+        }
+        else {
+            state.openRefAvailable = openCommit !== undefined;
+            state.baselineRefAvailable = baselineCommit !== undefined;
+        }
+        state.gitRoot = eligibility.gitRoot;
+    }
+    catch (error) {
+        state.diagnostic = error instanceof Error ? error.message : String(error);
+    }
+    finally {
+        states.set(workspaceId, state);
+    }
+}
+function reviewAvailability(state) {
+    return state?.gitRoot
+        ? { available: true }
+        : {
+            available: false,
+            reason: state?.diagnostic ?? "show_changes is unavailable for this workspace.",
+        };
+}
+function isReadyState(state) {
+    return state?.gitRoot !== undefined;
+}
+async function commitForRef(gitRoot, ref) {
+    try {
+        return (await git(gitRoot, ["rev-parse", "--verify", `${ref}^{commit}`])).stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function reviewRefs(workspaceId) {
+    const segment = safeWorkspaceRefSegment(workspaceId);
+    return {
+        openRef: `${REVIEW_REF_PREFIX}/${segment}/open`,
+        baselineRef: `${REVIEW_REF_PREFIX}/${segment}/baseline`,
+    };
+}
+async function createWorkingTreeSnapshot(gitRoot, parent) {
+    const tempDir = await mkdtemp(join(tmpdir(), "hearth-review-index-"));
+    const indexPath = join(tempDir, "index");
+    const env = checkpointEnv(indexPath);
+    try {
+        await git(gitRoot, ["read-tree", "HEAD"], { env });
+        await git(gitRoot, ["add", "-A", "--", "."], { env });
+        const tree = (await git(gitRoot, ["write-tree"], { env })).stdout.trim();
+        return (await git(gitRoot, ["commit-tree", tree, "-p", parent, "-m", "Hearth review snapshot"], { env })).stdout.trim();
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+async function readReviewCommit(gitRoot, reviewRef) {
+    const parent = (await git(gitRoot, ["rev-parse", "--verify", `${reviewRef}^1`])).stdout.trim();
+    const review = await readReviewBetween(gitRoot, parent, reviewRef);
+    return {
+        reviewRef,
+        result: review.summary.files === 0 ? "No changes in this review." : formatChangedFiles(review.summary),
+        ...review,
+    };
+}
+async function readReviewBetween(gitRoot, before, after) {
+    const patch = (await git(gitRoot, ["diff", "--binary", "--no-color", before, after], {
+        maxBuffer: 50 * 1024 * 1024,
+    })).stdout;
+    const numstat = (await git(gitRoot, ["diff", "--numstat", "-z", before, after], {
+        maxBuffer: 50 * 1024 * 1024,
+    })).stdout;
+    const files = parseNumstat(numstat);
+    return {
+        summary: summarizeFiles(files),
+        files,
+        patch,
+    };
+}
+async function resolveReviewCommit(gitRoot, reviewRef) {
+    if (!isReviewRef(reviewRef)) {
+        throw new Error(`Invalid review reference: ${reviewRef}`);
+    }
+    return (await git(gitRoot, ["rev-parse", "--verify", `${reviewRef}^{commit}`])).stdout.trim();
+}
+async function resolveReviewCommitOrUndefined(gitRoot, reviewRef) {
+    try {
+        return await resolveReviewCommit(gitRoot, reviewRef);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function isAncestor(gitRoot, ancestor, descendant) {
+    try {
+        await git(gitRoot, ["merge-base", "--is-ancestor", ancestor, descendant]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function isKnownReviewCommit(gitRoot, reviewCommit) {
+    const refs = (await git(gitRoot, [
+        "for-each-ref",
+        "--format=%(refname)\t%(objectname)",
+        REVIEW_REF_PREFIX,
+    ])).stdout.trim();
+    if (!refs)
+        return false;
+    const histories = new Map();
+    for (const line of refs.split("\n")) {
+        const [ref, commit] = line.split("\t");
+        if (!ref || !commit)
+            continue;
+        const match = ref.match(/^refs\/hearth\/review\/(.+)\/(open|baseline)$/);
+        if (!match)
+            continue;
+        const [, workspace, kind] = match;
+        if (!workspace || !kind)
+            continue;
+        const history = histories.get(workspace) ?? {};
+        history[kind] = commit;
+        histories.set(workspace, history);
+    }
+    const memberships = await Promise.all([...histories.values()].map(async ({ open, baseline }) => {
+        if (!open || !baseline || reviewCommit === open)
+            return false;
+        const [isAfterOpen, isBeforeBaseline] = await Promise.all([
+            isAncestor(gitRoot, open, reviewCommit),
+            isAncestor(gitRoot, reviewCommit, baseline),
+        ]);
+        return isAfterOpen && isBeforeBaseline;
+    }));
+    return memberships.some(Boolean);
+}
+function isReviewRef(value) {
+    return /^[0-9a-f]{40,64}$/.test(value);
+}
+function formatChangedFiles(summary) {
+    return `Changed ${summary.files} ${summary.files === 1 ? "file" : "files"} (+${summary.additions} -${summary.removals}).`;
+}
+function checkpointEnv(indexPath) {
+    return {
+        GIT_INDEX_FILE: indexPath,
+        GIT_AUTHOR_NAME: "Hearth",
+        GIT_AUTHOR_EMAIL: "hearth@users.noreply.local",
+        GIT_COMMITTER_NAME: "Hearth",
+        GIT_COMMITTER_EMAIL: "hearth@users.noreply.local",
+    };
+}
+function parseNumstat(output) {
+    const fields = output.split("\0").filter((field) => field.length > 0);
+    const files = [];
+    for (let index = 0; index < fields.length;) {
+        const header = fields[index++] ?? "";
+        const parts = header.split("\t");
+        const additions = parseStatNumber(parts[0]);
+        const removals = parseStatNumber(parts[1]);
+        if (parts.length >= 3) {
+            const path = parts[2] ?? "";
+            if (path)
+                files.push({ path, type: fileType(path, undefined, additions, removals), additions, removals });
+            continue;
+        }
+        const previousPath = fields[index++];
+        const path = fields[index++];
+        if (!path)
+            continue;
+        files.push({
+            path,
+            previousPath,
+            type: fileType(path, previousPath, additions, removals),
+            additions,
+            removals,
+        });
+    }
+    return files;
+}
+function parseStatNumber(value) {
+    if (!value || value === "-")
+        return 0;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function fileType(path, previousPath, additions, removals) {
+    if (previousPath)
+        return additions === 0 && removals === 0 ? "rename-pure" : "rename-changed";
+    if (additions > 0 && removals === 0)
+        return "new";
+    if (additions === 0 && removals > 0)
+        return "deleted";
+    return "change";
+}
+function summarizeFiles(files) {
+    return files.reduce((summary, file) => ({
+        files: summary.files + 1,
+        additions: summary.additions + file.additions,
+        removals: summary.removals + file.removals,
+    }), { files: 0, additions: 0, removals: 0 });
+}

package/dist/roots.js

@@ -0,0 +1,37 @@
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+export class AccessDeniedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AccessDeniedError";
+    }
+}
+export function expandHomePath(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/") || path.startsWith("~\\")) {
+        return resolve(homedir(), path.slice(2));
+    }
+    return path;
+}
+export function isPathInsideRoot(path, root) {
+    const resolvedPath = resolve(expandHomePath(path));
+    const resolvedRoot = resolve(expandHomePath(root));
+    const relationship = relative(resolvedRoot, resolvedPath);
+    return (relationship === "" ||
+        (!isAbsolute(relationship) &&
+            !relationship.startsWith("..") &&
+            relationship !== ".." &&
+            !relationship.includes(`..${sep}`)));
+}
+export function assertAllowedPath(path, allowedRoots) {
+    const resolvedPath = resolve(expandHomePath(path));
+    if (allowedRoots.some((root) => isPathInsideRoot(resolvedPath, root))) {
+        return resolvedPath;
+    }
+    throw new AccessDeniedError(`Path is outside allowed roots: ${path}`);
+}
+export function resolveAllowedPath(inputPath, cwd, allowedRoots) {
+    const absolutePath = resolve(cwd, inputPath);
+    return assertAllowedPath(absolutePath, allowedRoots);
+}

package/dist/server-shutdown.js

@@ -0,0 +1,12 @@
+export async function shutdownHttpServer(httpServer, closeApplication) {
+    const httpClosed = new Promise((resolve, reject) => {
+        httpServer.close((error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+    await closeApplication();
+    await httpClosed;
+}