@xfey/tutti 0.1.0

package/dist/workspace-ops/run-workspaces.js

@@ -0,0 +1,271 @@
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { classifyViewerPath } from "@tutti/shared/utils";
+import { WorkspaceOpsError } from "./errors.js";
+import { runGit, runGitRaw, runGitText, stagedChangesExist, summarizeGitFailure, tryGitText, } from "./git.js";
+import { requireMainlineWriteReady } from "./mainline.js";
+const MAX_RUN_DIFF_SUMMARY_BYTES = 32 * 1024;
+function runWorkspaceTempBranch(taskId, activityRef) {
+    return `tutti/run/${taskId}/${activityRef}`;
+}
+function mergeWorkspaceTempBranch(taskId, activityRef) {
+    return `tutti/merge/${taskId}/${activityRef}`;
+}
+function truncateText(text, maxBytes) {
+    const buffer = Buffer.from(text, "utf8");
+    if (buffer.byteLength <= maxBytes) {
+        return text;
+    }
+    return `${buffer.subarray(0, maxBytes).toString("utf8")}\n[truncated]`;
+}
+function parsePorcelainChangedPaths(output) {
+    const entries = output
+        .toString("utf8")
+        .split("\0")
+        .filter((entry) => entry.length > 0);
+    const paths = new Set();
+    for (const entry of entries) {
+        const pathText = entry.slice(3);
+        const path = pathText.includes(" -> ") ? pathText.split(" -> ").at(-1) : pathText;
+        if (path !== undefined && classifyViewerPath(path).kind === "allowed") {
+            paths.add(path);
+        }
+    }
+    return [...paths].sort((left, right) => left.localeCompare(right, "en"));
+}
+function collectWorkspaceDiff(repoRoot) {
+    const status = runGitRaw(["status", "--porcelain=v1", "-z"], repoRoot);
+    if (status.status !== 0) {
+        throw new WorkspaceOpsError("git_failed", summarizeGitFailure(["status"], status));
+    }
+    const changedPaths = parsePorcelainChangedPaths(status.stdout);
+    const summaryParts = [];
+    const statusText = runGitText(["status", "--short"], repoRoot);
+    if (statusText.length > 0) {
+        summaryParts.push(statusText);
+    }
+    const unstagedStat = tryGitText(["diff", "--stat"], repoRoot);
+    if (unstagedStat !== null && unstagedStat.length > 0) {
+        summaryParts.push(unstagedStat);
+    }
+    const stagedStat = tryGitText(["diff", "--cached", "--stat"], repoRoot);
+    if (stagedStat !== null && stagedStat.length > 0) {
+        summaryParts.push(stagedStat);
+    }
+    return {
+        changed_paths: changedPaths,
+        summary: truncateText(summaryParts.join("\n\n"), MAX_RUN_DIFF_SUMMARY_BYTES),
+    };
+}
+export function prepareRunWorkspace(options) {
+    requireMainlineWriteReady(options.workspaceRoot);
+    const baseRef = runGitText(["rev-parse", "--verify", "HEAD"], options.workspaceRoot);
+    const tempBranch = runWorkspaceTempBranch(options.taskId, options.activityRef);
+    const runWorkspaceRoot = join(options.runWorkspaceRoot, options.activityRef);
+    const repoRoot = join(runWorkspaceRoot, "repo");
+    if (existsSync(runWorkspaceRoot)) {
+        throw new WorkspaceOpsError("conflict", "Run workspace already exists");
+    }
+    mkdirSync(options.runWorkspaceRoot, { recursive: true });
+    runGit(["worktree", "add", "-b", tempBranch, repoRoot, baseRef], options.workspaceRoot);
+    return {
+        activity_ref: options.activityRef,
+        task_id: options.taskId,
+        workspace_root: options.workspaceRoot,
+        run_workspace_root: runWorkspaceRoot,
+        repo_root: repoRoot,
+        base_ref: baseRef,
+        temp_branch: tempBranch,
+    };
+}
+export function collectRunDiff(handle) {
+    return collectWorkspaceDiff(handle.repo_root);
+}
+function createCandidateCommit(input) {
+    runGit(["add", "-A"], input.repoRoot);
+    if (!stagedChangesExist(input.repoRoot)) {
+        throw new WorkspaceOpsError("validation_failed", input.emptyMessage);
+    }
+    runGit([
+        "commit",
+        "-m",
+        input.summary.trim().length === 0 ? "Complete Tutti task" : input.summary.trim(),
+        "-m",
+        input.metadata,
+    ], input.repoRoot);
+    return {
+        commit_oid: runGitText(["rev-parse", "--verify", "HEAD"], input.repoRoot),
+    };
+}
+export function createResultCommit(handle, summary) {
+    return createCandidateCommit({
+        repoRoot: handle.repo_root,
+        summary,
+        emptyMessage: "Run result has no candidate changes",
+        metadata: `Task: ${handle.task_id}\nActivity: ${handle.activity_ref}\nBase: ${handle.base_ref}`,
+    });
+}
+export function prepareMergeWorkspace(options) {
+    requireMainlineWriteReady(options.workspaceRoot);
+    const baseRef = runGitText(["rev-parse", "--verify", "HEAD"], options.workspaceRoot);
+    const tempBranch = mergeWorkspaceTempBranch(options.taskId, options.activityRef);
+    const mergeWorkspaceRoot = join(options.mergeWorkspaceRoot, options.activityRef);
+    const repoRoot = join(mergeWorkspaceRoot, "repo");
+    if (existsSync(mergeWorkspaceRoot)) {
+        throw new WorkspaceOpsError("conflict", "Merge workspace already exists");
+    }
+    mkdirSync(options.mergeWorkspaceRoot, { recursive: true });
+    runGit(["worktree", "add", "-b", tempBranch, repoRoot, baseRef], options.workspaceRoot);
+    return {
+        activity_ref: options.activityRef,
+        task_id: options.taskId,
+        workspace_root: options.workspaceRoot,
+        merge_workspace_root: mergeWorkspaceRoot,
+        repo_root: repoRoot,
+        base_ref: baseRef,
+        source_base_ref: options.sourceBaseRef,
+        source_result_commit_oid: options.sourceCommit.commit_oid,
+        temp_branch: tempBranch,
+    };
+}
+export function applyRunResultToMergeWorkspace(handle) {
+    const result = runGitRaw(["cherry-pick", "--no-commit", handle.source_result_commit_oid], handle.repo_root);
+    if (result.status === 0) {
+        return;
+    }
+    runGitRaw(["cherry-pick", "--abort"], handle.repo_root);
+    throw new WorkspaceOpsError("conflict", "Promotion reconcile could not apply the Run result to latest mainline", { reason_code: "promotion_reconcile_apply_failed" });
+}
+export function collectMergeDiff(handle) {
+    return collectWorkspaceDiff(handle.repo_root);
+}
+export function createMergeCandidateCommit(handle, summary) {
+    return createCandidateCommit({
+        repoRoot: handle.repo_root,
+        summary,
+        emptyMessage: "Promotion reconcile has no candidate changes",
+        metadata: [
+            `Task: ${handle.task_id}`,
+            `Activity: ${handle.activity_ref}`,
+            `Source-Base: ${handle.source_base_ref}`,
+            `Source-Commit: ${handle.source_result_commit_oid}`,
+            `Merge-Base: ${handle.base_ref}`,
+        ].join("\n"),
+    });
+}
+export function promoteRunResult(handle, commit) {
+    requireMainlineWriteReady(handle.workspace_root);
+    const currentHead = runGitText(["rev-parse", "--verify", "HEAD"], handle.workspace_root);
+    if (currentHead !== handle.base_ref) {
+        throw new WorkspaceOpsError("conflict", "Mainline HEAD is no longer at the Run base ref", {
+            reason_code: "mainline_not_at_base",
+        });
+    }
+    runGit(["merge", "--ff-only", commit.commit_oid], handle.workspace_root);
+    return {
+        promoted_commit_oid: runGitText(["rev-parse", "--verify", "HEAD"], handle.workspace_root),
+    };
+}
+export function promoteMergeCandidate(handle, commit) {
+    requireMainlineWriteReady(handle.workspace_root);
+    const currentHead = runGitText(["rev-parse", "--verify", "HEAD"], handle.workspace_root);
+    if (currentHead !== handle.base_ref) {
+        throw new WorkspaceOpsError("conflict", "Mainline HEAD changed while promotion reconcile was preparing a candidate", { reason_code: "promotion_reconcile_mainline_moved" });
+    }
+    runGit(["merge", "--ff-only", commit.commit_oid], handle.workspace_root);
+    return {
+        promoted_commit_oid: runGitText(["rev-parse", "--verify", "HEAD"], handle.workspace_root),
+    };
+}
+function cleanupWorktree(input) {
+    const warnings = [];
+    if (existsSync(input.repoRoot)) {
+        let remove = runGitRaw(["worktree", "remove", "--force", input.repoRoot], input.workspaceRoot);
+        if (remove.status !== 0) {
+            remove = runGitRaw(["worktree", "remove", "--force", "--force", input.repoRoot], input.workspaceRoot);
+        }
+        if (remove.status !== 0) {
+            warnings.push(summarizeGitFailure(["worktree", "remove"], remove));
+            rmSync(input.workspaceDir, { recursive: true, force: true });
+            runGitRaw(["worktree", "prune"], input.workspaceRoot);
+        }
+        else {
+            rmSync(input.workspaceDir, { recursive: true, force: true });
+        }
+    }
+    else {
+        rmSync(input.workspaceDir, { recursive: true, force: true });
+    }
+    const deleteBranch = runGitRaw(["branch", "-D", input.tempBranch], input.workspaceRoot);
+    if (deleteBranch.status !== 0) {
+        warnings.push(summarizeGitFailure(["branch", "-D", input.tempBranch], deleteBranch));
+    }
+    return { warnings };
+}
+export function cleanupRunWorkspace(handle) {
+    return cleanupWorktree({
+        workspaceRoot: handle.workspace_root,
+        repoRoot: handle.repo_root,
+        workspaceDir: handle.run_workspace_root,
+        tempBranch: handle.temp_branch,
+    });
+}
+export function cleanupMergeWorkspace(handle) {
+    return cleanupWorktree({
+        workspaceRoot: handle.workspace_root,
+        repoRoot: handle.repo_root,
+        workspaceDir: handle.merge_workspace_root,
+        tempBranch: handle.temp_branch,
+    });
+}
+export function cleanupStaleRunWorkspaces(options) {
+    const warnings = [];
+    let removedRunWorkspaceCount = 0;
+    for (const workspaceRoot of [options.runWorkspaceRoot, options.mergeWorkspaceRoot]) {
+        if (workspaceRoot === undefined || !existsSync(workspaceRoot)) {
+            continue;
+        }
+        try {
+            for (const entry of readdirSync(workspaceRoot, { withFileTypes: true })) {
+                rmSync(join(workspaceRoot, entry.name), { recursive: true, force: true });
+                removedRunWorkspaceCount += 1;
+            }
+        }
+        catch {
+            warnings.push("Failed to remove one or more stale run workspaces.");
+        }
+    }
+    const prune = runGitRaw(["worktree", "prune"], options.workspaceRoot);
+    if (prune.status !== 0) {
+        warnings.push("Failed to prune stale Git worktree metadata.");
+    }
+    let removedTempBranchCount = 0;
+    const branchPatterns = options.mergeWorkspaceRoot === undefined ? ["tutti/run/*"] : ["tutti/run/*", "tutti/merge/*"];
+    for (const pattern of branchPatterns) {
+        const branches = runGitRaw(["branch", "--list", pattern, "--format=%(refname:short)"], options.workspaceRoot);
+        if (branches.status !== 0) {
+            warnings.push(`Failed to list stale ${pattern} branches.`);
+            continue;
+        }
+        const branchNames = branches.stdout
+            .toString("utf8")
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        for (const branchName of branchNames) {
+            const deleted = runGitRaw(["branch", "-D", branchName], options.workspaceRoot);
+            if (deleted.status === 0) {
+                removedTempBranchCount += 1;
+            }
+            else {
+                warnings.push(`Failed to delete stale run branch ${branchName}.`);
+            }
+        }
+    }
+    return {
+        removed_run_workspace_count: removedRunWorkspaceCount,
+        removed_temp_branch_count: removedTempBranchCount,
+        warnings,
+    };
+}
+//# sourceMappingURL=run-workspaces.js.map

package/dist/workspace-ops/types.d.ts

@@ -0,0 +1,219 @@
+import type { ActivityRef, IdempotencyKey, TaskId } from "@tutti/shared/ids";
+import type { REFERENCE_INDEX_PATH, WORKSPACE_OPS_MAINLINE_BRANCH } from "./constants.js";
+export type ViewerRepoSnapshot = {
+    source: "mainline";
+    branch: typeof WORKSPACE_OPS_MAINLINE_BRANCH;
+    head: {
+        oid: string;
+        short_oid: string;
+    };
+    mainline_clean: boolean;
+    generated_at: string;
+};
+export type ViewerEntryKind = "directory" | "file" | "symlink" | "submodule";
+export type ViewerTreeEntry = {
+    path: string;
+    name: string;
+    kind: ViewerEntryKind;
+    depth: number;
+    parent_path?: string;
+    size_bytes?: number;
+    blob_oid?: string;
+    mode?: string;
+    extension?: string;
+    language_hint?: string;
+    has_children?: boolean;
+};
+export type ViewerTreeResult = {
+    snapshot: ViewerRepoSnapshot;
+    root: ViewerTreeEntry;
+    items: ViewerTreeEntry[];
+};
+export type ViewerFileContent = {
+    kind: "text";
+    encoding: "utf-8";
+    text: string;
+    truncated: boolean;
+    bytes_returned: number;
+    total_bytes: number;
+    line_count?: number;
+} | {
+    kind: "omitted";
+    reason: "binary" | "unsupported_encoding" | "too_large";
+    total_bytes: number;
+};
+export type ViewerFileResult = {
+    snapshot: ViewerRepoSnapshot;
+    file: ViewerTreeEntry & {
+        kind: "file";
+        size_bytes: number;
+        blob_oid: string;
+    };
+    content: ViewerFileContent;
+};
+export type ReferenceFileCategory = "file" | "image";
+export type ViewerAssetVariant = "thumbnail" | "preview" | "original";
+export type ReferenceSummaryStatus = "available" | "unavailable";
+export type ReferenceSummaryRecord = {
+    path: string;
+    status: ReferenceSummaryStatus;
+    generated_at: string;
+    source_blob_oid?: string;
+    summary?: string;
+    unavailable_reason?: string;
+    read_paths?: string[];
+};
+export type ReferenceSummaryProjection = {
+    status: "available" | "missing" | "stale" | "unavailable";
+    text?: string;
+    generated_at?: string;
+    source_blob_oid?: string;
+    unavailable_reason?: string;
+    read_paths?: string[];
+};
+export type ReferenceSummaryTarget = {
+    path: string;
+    name: string;
+    category: ReferenceFileCategory;
+    size_bytes: number;
+    blob_oid: string;
+    media_type?: string;
+    summary: ReferenceSummaryProjection;
+};
+export type ViewerAssetResult = {
+    snapshot: ViewerRepoSnapshot;
+    file: ViewerTreeEntry & {
+        kind: "file";
+        size_bytes: number;
+        blob_oid: string;
+    };
+    variant: ViewerAssetVariant;
+    cache_version?: string;
+    media_type: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+    content: Buffer;
+};
+export type WorkspaceViewerOptions = {
+    workspaceRoot: string;
+    now?: () => Date;
+};
+export type ReadViewerTreeOptions = WorkspaceViewerOptions & {
+    path?: string;
+    depth?: number;
+};
+export type ReadViewerFileOptions = WorkspaceViewerOptions & {
+    path: string;
+    maxBytes?: number;
+};
+export type ReadViewerAssetOptions = WorkspaceViewerOptions & {
+    path: string;
+    variant: ViewerAssetVariant;
+    version: string;
+    assetCacheRoot: string;
+};
+export type UploadReferenceFileOptions = WorkspaceViewerOptions & {
+    commandId: IdempotencyKey;
+    fileName: string;
+    content: Buffer;
+    mediaType?: string;
+    note?: string;
+};
+export type UploadReferenceFileResult = {
+    file: ViewerFileResult["file"];
+    category: ReferenceFileCategory;
+    index_path: typeof REFERENCE_INDEX_PATH;
+    commit_oid?: string;
+};
+export type UpdateReferenceSummariesOptions = WorkspaceViewerOptions & {
+    summaries: ReferenceSummaryRecord[];
+};
+export type UpdateReferenceSummariesResult = {
+    updated_paths: string[];
+    commit_oid?: string;
+};
+export type InitializeProjectDocsOptions = WorkspaceViewerOptions & {
+    projectName: string;
+    context?: ProjectDocsInitializationContext;
+    documents?: ProjectDocsInitializationDocument[];
+};
+export type InitializeProjectDocsResult = {
+    created_paths: string[];
+    commit_oid?: string;
+};
+export type ProjectDocsInitializationDocument = {
+    path: string;
+    content: string;
+};
+export type ProjectDocsInitializationContext = {
+    source: "scratchpad_submit" | "manual_command";
+    scratchpad?: {
+        topic: string;
+        background_summary: string;
+        current_consensus: string[];
+        open_questions: string[];
+        task_changes: string[];
+    };
+};
+export type ProjectDocsInitializationStatus = {
+    ready: boolean;
+    missing_paths: string[];
+    existing_paths: string[];
+};
+export type SyncProjectDocsUpdate = {
+    path: string;
+    content: string;
+};
+export type SyncProjectDocsResult = {
+    updated_paths: string[];
+    commit_oid?: string;
+};
+export type RunWorkspaceHandle = {
+    activity_ref: ActivityRef;
+    task_id: TaskId;
+    workspace_root: string;
+    run_workspace_root: string;
+    repo_root: string;
+    base_ref: string;
+    temp_branch: string;
+};
+export type MergeWorkspaceHandle = {
+    activity_ref: ActivityRef;
+    task_id: TaskId;
+    workspace_root: string;
+    merge_workspace_root: string;
+    repo_root: string;
+    base_ref: string;
+    source_base_ref: string;
+    source_result_commit_oid: string;
+    temp_branch: string;
+};
+export type PrepareRunWorkspaceOptions = WorkspaceViewerOptions & {
+    runWorkspaceRoot: string;
+    taskId: TaskId;
+    activityRef: ActivityRef;
+};
+export type PrepareMergeWorkspaceOptions = WorkspaceViewerOptions & {
+    mergeWorkspaceRoot: string;
+    taskId: TaskId;
+    activityRef: ActivityRef;
+    sourceBaseRef: string;
+    sourceCommit: ResultCommit;
+};
+export type RunDiffSummary = {
+    changed_paths: string[];
+    summary: string;
+};
+export type ResultCommit = {
+    commit_oid: string;
+};
+export type PromotionResult = {
+    promoted_commit_oid: string;
+};
+export type CleanupRunWorkspaceResult = {
+    warnings: string[];
+};
+export type CleanupStaleRunWorkspacesResult = {
+    removed_run_workspace_count: number;
+    removed_temp_branch_count: number;
+    warnings: string[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/workspace-ops/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/workspace-ops/viewer-file.d.ts

@@ -0,0 +1,4 @@
+import type { ReadViewerAssetOptions, ReadViewerFileOptions, ViewerAssetResult, ViewerFileResult } from "./types.js";
+export declare function readViewerFile(options: ReadViewerFileOptions): ViewerFileResult;
+export declare function readViewerAsset(options: ReadViewerAssetOptions): Promise<ViewerAssetResult>;
+//# sourceMappingURL=viewer-file.d.ts.map