@xfey/tutti 0.1.0

package/dist/workspace-ops/reference-metadata.js

@@ -0,0 +1,86 @@
+import { extname, posix } from "node:path";
+import { REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, } from "./constants.js";
+const REFERENCE_IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif"]);
+const REFERENCE_IMAGE_MEDIA_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
+function normalizeMediaType(mediaType) {
+    const normalized = mediaType?.split(";")[0]?.trim().toLowerCase();
+    return normalized === undefined || normalized === "" ? undefined : normalized;
+}
+export function detectReferenceImageMediaType(content) {
+    if (content.byteLength >= 8 &&
+        content[0] === 0x89 &&
+        content[1] === 0x50 &&
+        content[2] === 0x4e &&
+        content[3] === 0x47 &&
+        content[4] === 0x0d &&
+        content[5] === 0x0a &&
+        content[6] === 0x1a &&
+        content[7] === 0x0a) {
+        return "image/png";
+    }
+    if (content.byteLength >= 3 &&
+        content[0] === 0xff &&
+        content[1] === 0xd8 &&
+        content[2] === 0xff) {
+        return "image/jpeg";
+    }
+    if (content.byteLength >= 6 &&
+        (content.subarray(0, 6).toString("ascii") === "GIF87a" ||
+            content.subarray(0, 6).toString("ascii") === "GIF89a")) {
+        return "image/gif";
+    }
+    if (content.byteLength >= 12 &&
+        content.subarray(0, 4).toString("ascii") === "RIFF" &&
+        content.subarray(8, 12).toString("ascii") === "WEBP") {
+        return "image/webp";
+    }
+    return undefined;
+}
+export function classifyReferenceUpload(options) {
+    const detectedImage = detectReferenceImageMediaType(options.content);
+    if (detectedImage === undefined) {
+        return { category: "file", directoryPath: REFERENCE_FILES_DIRECTORY_PATH };
+    }
+    const extension = extname(options.fileName).toLowerCase();
+    const mediaType = normalizeMediaType(options.mediaType);
+    if (REFERENCE_IMAGE_EXTENSIONS.has(extension) ||
+        mediaType === undefined ||
+        REFERENCE_IMAGE_MEDIA_TYPES.has(mediaType)) {
+        return { category: "image", directoryPath: REFERENCE_IMAGES_DIRECTORY_PATH };
+    }
+    return { category: "file", directoryPath: REFERENCE_FILES_DIRECTORY_PATH };
+}
+export function referenceFileCategoryForPath(path) {
+    if (path.startsWith(`${REFERENCE_IMAGES_DIRECTORY_PATH}/`)) {
+        return "image";
+    }
+    if (path.startsWith(`${REFERENCE_FILES_DIRECTORY_PATH}/`)) {
+        return "file";
+    }
+    if (posix.dirname(path) === REFERENCE_DIRECTORY_PATH && path !== REFERENCE_INDEX_PATH) {
+        return "file";
+    }
+    return undefined;
+}
+export function referenceMediaTypeForPath(path) {
+    const extension = extname(path).toLowerCase();
+    switch (extension) {
+        case ".png":
+            return "image/png";
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".webp":
+            return "image/webp";
+        case ".gif":
+            return "image/gif";
+        case ".md":
+        case ".markdown":
+            return "text/markdown";
+        case ".txt":
+            return "text/plain";
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=reference-metadata.js.map

package/dist/workspace-ops/reference-summaries.d.ts

@@ -0,0 +1,17 @@
+import type { ReferenceSummaryProjection, ReferenceSummaryRecord, ReferenceSummaryTarget, UpdateReferenceSummariesOptions, UpdateReferenceSummariesResult, ViewerTreeEntry } from "./types.js";
+type ReferenceSummaryIndex = Map<string, ReferenceSummaryRecord>;
+export declare function readReferenceSummaryIndex(options: {
+    workspaceRoot: string;
+}): ReferenceSummaryIndex;
+export declare function referenceSummaryProjectionForEntry(options: {
+    entry: ViewerTreeEntry;
+    summaries: ReferenceSummaryIndex;
+}): ReferenceSummaryProjection;
+export declare function readReferenceSummaryTargets(options: {
+    workspaceRoot: string;
+    paths?: string[];
+    now?: () => Date;
+}): ReferenceSummaryTarget[];
+export declare function updateReferenceSummaries(options: UpdateReferenceSummariesOptions): UpdateReferenceSummariesResult;
+export {};
+//# sourceMappingURL=reference-summaries.d.ts.map

package/dist/workspace-ops/reference-summaries.js

@@ -0,0 +1,298 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { redactText } from "@tutti/shared/utils";
+import { REFERENCE_DIRECTORY_PATH, REFERENCE_INDEX_PATH, } from "./constants.js";
+import { runGit, runGitText, stagedChangesExist } from "./git.js";
+import { requireMainlineWriteReady } from "./mainline.js";
+import { referenceFileCategoryForPath, referenceMediaTypeForPath } from "./reference-metadata.js";
+import { readViewerTree } from "./viewer.js";
+const SUMMARY_SECTION_HEADING = "## Summaries";
+const SUMMARY_BLOCK_START = "<!-- tutti-reference-summaries:v1";
+const SUMMARY_BLOCK_END = "-->";
+const SUMMARY_MAX_CHARS = 700;
+const SUMMARY_READ_PATHS_MAX_ITEMS = 20;
+function replaceControlCharacters(value) {
+    let result = "";
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        result += codePoint !== undefined && (codePoint < 32 || codePoint === 127) ? " " : character;
+    }
+    return result;
+}
+function normalizeOneLine(value, maxChars = SUMMARY_MAX_CHARS) {
+    const normalized = replaceControlCharacters(redactText(value))
+        .replace(/<!--/gu, "<--")
+        .replace(/-->/gu, "->")
+        .replace(/\s+/gu, " ")
+        .trim();
+    if (normalized.length <= maxChars) {
+        return normalized;
+    }
+    return `${normalized.slice(0, maxChars - 3).trimEnd()}...`;
+}
+function sanitizeReadPaths(paths) {
+    const safePaths = paths
+        .map((path) => path.trim())
+        .filter((path) => path !== "")
+        .filter((path) => !path.startsWith("/") && !path.includes("\\"))
+        .filter((path) => !path.split("/").includes(".."))
+        .filter((path) => path.length <= 300);
+    return [...new Set(safePaths)].slice(0, SUMMARY_READ_PATHS_MAX_ITEMS);
+}
+function summaryRecordFromUnknown(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value;
+    if (typeof record.path !== "string" || record.path.trim() === "") {
+        return undefined;
+    }
+    if (record.status !== "available" && record.status !== "unavailable") {
+        return undefined;
+    }
+    if (typeof record.generated_at !== "string" || Number.isNaN(Date.parse(record.generated_at))) {
+        return undefined;
+    }
+    const summary = {
+        path: record.path,
+        status: record.status,
+        generated_at: record.generated_at,
+    };
+    if (typeof record.source_blob_oid === "string" && record.source_blob_oid.trim() !== "") {
+        summary.source_blob_oid = record.source_blob_oid;
+    }
+    if (typeof record.summary === "string" && record.summary.trim() !== "") {
+        summary.summary = normalizeOneLine(record.summary);
+    }
+    if (typeof record.unavailable_reason === "string" && record.unavailable_reason.trim() !== "") {
+        summary.unavailable_reason = normalizeOneLine(record.unavailable_reason, 240);
+    }
+    if (Array.isArray(record.read_paths)) {
+        const readPaths = sanitizeReadPaths(record.read_paths.filter((path) => typeof path === "string"));
+        if (readPaths.length !== 0) {
+            summary.read_paths = readPaths;
+        }
+    }
+    return summary;
+}
+function parseSummaryIndex(content) {
+    const index = new Map();
+    const start = content.indexOf(SUMMARY_BLOCK_START);
+    if (start === -1) {
+        return index;
+    }
+    const jsonStart = content.indexOf("\n", start);
+    if (jsonStart === -1) {
+        return index;
+    }
+    const end = content.indexOf(SUMMARY_BLOCK_END, jsonStart);
+    if (end === -1) {
+        return index;
+    }
+    try {
+        const parsed = JSON.parse(content.slice(jsonStart + 1, end).trim());
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return index;
+        }
+        const items = parsed.items;
+        if (!Array.isArray(items)) {
+            return index;
+        }
+        for (const item of items) {
+            const record = summaryRecordFromUnknown(item);
+            if (record !== undefined) {
+                index.set(record.path, record);
+            }
+        }
+    }
+    catch {
+        return index;
+    }
+    return index;
+}
+function readReferenceIndexContent(workspaceRoot) {
+    const indexPath = join(workspaceRoot, "docs", "reference", "README.md");
+    if (!existsSync(indexPath)) {
+        return [
+            "# Reference Files",
+            "",
+            "Human-uploaded project reference files.",
+            "",
+            "## Files",
+            "",
+            "## Images",
+            "",
+        ].join("\n");
+    }
+    return readFileSync(indexPath, "utf8");
+}
+export function readReferenceSummaryIndex(options) {
+    return parseSummaryIndex(readReferenceIndexContent(options.workspaceRoot));
+}
+export function referenceSummaryProjectionForEntry(options) {
+    const record = options.summaries.get(options.entry.path);
+    if (record === undefined) {
+        return { status: "missing" };
+    }
+    const base = {
+        ...(record.generated_at === undefined ? {} : { generated_at: record.generated_at }),
+        ...(record.source_blob_oid === undefined ? {} : { source_blob_oid: record.source_blob_oid }),
+        ...(record.read_paths === undefined ? {} : { read_paths: record.read_paths }),
+    };
+    if (record.source_blob_oid !== undefined &&
+        options.entry.blob_oid !== undefined &&
+        record.source_blob_oid !== options.entry.blob_oid) {
+        return {
+            status: "stale",
+            ...base,
+            ...(record.summary === undefined ? {} : { text: record.summary }),
+            ...(record.unavailable_reason === undefined
+                ? {}
+                : { unavailable_reason: record.unavailable_reason }),
+        };
+    }
+    if (record.status === "unavailable") {
+        return {
+            status: "unavailable",
+            ...base,
+            ...(record.summary === undefined ? {} : { text: record.summary }),
+            ...(record.unavailable_reason === undefined
+                ? {}
+                : { unavailable_reason: record.unavailable_reason }),
+        };
+    }
+    return {
+        status: "available",
+        ...base,
+        ...(record.summary === undefined ? {} : { text: record.summary }),
+    };
+}
+function readReferenceFileEntries(options) {
+    const tree = readViewerTree({
+        workspaceRoot: options.workspaceRoot,
+        path: REFERENCE_DIRECTORY_PATH,
+        depth: 2,
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    return tree.items
+        .filter((entry) => entry.kind === "file")
+        .filter((entry) => referenceFileCategoryForPath(entry.path) !== undefined)
+        .filter((entry) => entry.blob_oid !== undefined && entry.size_bytes !== undefined)
+        .sort((left, right) => left.path.localeCompare(right.path, "en", { sensitivity: "base" }));
+}
+export function readReferenceSummaryTargets(options) {
+    const summaries = readReferenceSummaryIndex({ workspaceRoot: options.workspaceRoot });
+    const requested = options.paths === undefined ? undefined : new Set(options.paths);
+    return readReferenceFileEntries(options)
+        .filter((entry) => requested === undefined || requested.has(entry.path))
+        .map((entry) => {
+        const category = referenceFileCategoryForPath(entry.path) ?? "file";
+        const summary = referenceSummaryProjectionForEntry({ entry, summaries });
+        return {
+            path: entry.path,
+            name: entry.name,
+            category,
+            size_bytes: entry.size_bytes ?? 0,
+            blob_oid: entry.blob_oid,
+            ...(referenceMediaTypeForPath(entry.path) === undefined
+                ? {}
+                : { media_type: referenceMediaTypeForPath(entry.path) }),
+            summary,
+        };
+    })
+        .filter((target) => target.summary.status !== "available");
+}
+function removeSummarySection(content) {
+    const headingPattern = /(^|\n)## Summaries\n/u;
+    const match = headingPattern.exec(content);
+    if (match === null || match.index === undefined) {
+        return content.trimEnd();
+    }
+    const sectionStart = match.index + (match[1] === "\n" ? 1 : 0);
+    const afterHeading = sectionStart + `${SUMMARY_SECTION_HEADING}\n`.length;
+    const nextSection = content.indexOf("\n## ", afterHeading);
+    if (nextSection === -1) {
+        return content.slice(0, sectionStart).trimEnd();
+    }
+    return `${content.slice(0, sectionStart).trimEnd()}\n${content
+        .slice(nextSection + 1)
+        .trimStart()}`.trimEnd();
+}
+function renderSummaryRecord(record) {
+    const rendered = {
+        path: record.path,
+        status: record.status,
+        generated_at: record.generated_at,
+    };
+    if (record.source_blob_oid !== undefined) {
+        rendered.source_blob_oid = record.source_blob_oid;
+    }
+    if (record.summary !== undefined && record.summary.trim() !== "") {
+        rendered.summary = normalizeOneLine(record.summary);
+    }
+    if (record.unavailable_reason !== undefined && record.unavailable_reason.trim() !== "") {
+        rendered.unavailable_reason = normalizeOneLine(record.unavailable_reason, 240);
+    }
+    if (record.read_paths !== undefined && record.read_paths.length !== 0) {
+        rendered.read_paths = sanitizeReadPaths(record.read_paths);
+    }
+    return rendered;
+}
+function renderSummariesSection(records) {
+    const items = records.map(renderSummaryRecord).sort((left, right) => left.path.localeCompare(right.path, "en", { sensitivity: "base" }));
+    const json = JSON.stringify({ items }, null, 2);
+    const lines = [
+        SUMMARY_SECTION_HEADING,
+        "",
+        `${SUMMARY_BLOCK_START}`,
+        json,
+        SUMMARY_BLOCK_END,
+        "",
+    ];
+    if (items.length === 0) {
+        lines.push("No reference summaries yet.");
+    }
+    else {
+        for (const item of items) {
+            const label = item.status === "available"
+                ? item.summary
+                : `Summary unavailable${item.unavailable_reason === undefined ? "" : `: ${item.unavailable_reason}`}`;
+            lines.push(`- \`${item.path}\`: ${label ?? "Summary unavailable"}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function updateReferenceSummaries(options) {
+    if (options.summaries.length === 0) {
+        return { updated_paths: [] };
+    }
+    requireMainlineWriteReady(options.workspaceRoot);
+    const existingContent = readReferenceIndexContent(options.workspaceRoot);
+    const existing = parseSummaryIndex(existingContent);
+    const changedPaths = [];
+    for (const summary of options.summaries) {
+        const rendered = renderSummaryRecord(summary);
+        if (JSON.stringify(existing.get(summary.path)) !== JSON.stringify(rendered)) {
+            changedPaths.push(summary.path);
+        }
+        existing.set(summary.path, rendered);
+    }
+    const currentPaths = new Set(readReferenceFileEntries({
+        workspaceRoot: options.workspaceRoot,
+        ...(options.now === undefined ? {} : { now: options.now }),
+    }).map((entry) => entry.path));
+    const records = [...existing.values()].filter((record) => currentPaths.has(record.path));
+    const nextContent = `${removeSummarySection(existingContent)}\n\n${renderSummariesSection(records)}\n`;
+    const indexPath = join(options.workspaceRoot, "docs", "reference", "README.md");
+    writeFileSync(indexPath, nextContent, "utf8");
+    runGit(["add", "--", REFERENCE_INDEX_PATH], options.workspaceRoot);
+    if (!stagedChangesExist(options.workspaceRoot)) {
+        return { updated_paths: [] };
+    }
+    runGit(["commit", "-m", "Update reference summaries"], options.workspaceRoot);
+    return {
+        updated_paths: changedPaths.length === 0 ? options.summaries.map((summary) => summary.path) : changedPaths,
+        commit_oid: runGitText(["rev-parse", "--verify", "HEAD"], options.workspaceRoot),
+    };
+}
+//# sourceMappingURL=reference-summaries.js.map

package/dist/workspace-ops/run-workspaces.d.ts

@@ -0,0 +1,18 @@
+import type { CleanupRunWorkspaceResult, CleanupStaleRunWorkspacesResult, MergeWorkspaceHandle, PrepareMergeWorkspaceOptions, PrepareRunWorkspaceOptions, PromotionResult, ResultCommit, RunDiffSummary, RunWorkspaceHandle } from "./types.js";
+export declare function prepareRunWorkspace(options: PrepareRunWorkspaceOptions): RunWorkspaceHandle;
+export declare function collectRunDiff(handle: RunWorkspaceHandle): RunDiffSummary;
+export declare function createResultCommit(handle: RunWorkspaceHandle, summary: string): ResultCommit;
+export declare function prepareMergeWorkspace(options: PrepareMergeWorkspaceOptions): MergeWorkspaceHandle;
+export declare function applyRunResultToMergeWorkspace(handle: MergeWorkspaceHandle): void;
+export declare function collectMergeDiff(handle: MergeWorkspaceHandle): RunDiffSummary;
+export declare function createMergeCandidateCommit(handle: MergeWorkspaceHandle, summary: string): ResultCommit;
+export declare function promoteRunResult(handle: RunWorkspaceHandle, commit: ResultCommit): PromotionResult;
+export declare function promoteMergeCandidate(handle: MergeWorkspaceHandle, commit: ResultCommit): PromotionResult;
+export declare function cleanupRunWorkspace(handle: RunWorkspaceHandle): CleanupRunWorkspaceResult;
+export declare function cleanupMergeWorkspace(handle: MergeWorkspaceHandle): CleanupRunWorkspaceResult;
+export declare function cleanupStaleRunWorkspaces(options: {
+    workspaceRoot: string;
+    runWorkspaceRoot: string;
+    mergeWorkspaceRoot?: string;
+}): CleanupStaleRunWorkspacesResult;
+//# sourceMappingURL=run-workspaces.d.ts.map