@xfey/tutti 0.1.0

package/dist/workspace-ops/errors.js

@@ -0,0 +1,33 @@
+export class WorkspaceOpsError extends Error {
+    code;
+    statusCode;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "WorkspaceOpsError";
+        this.code = code;
+        this.statusCode = workspaceOpsStatusCode(code);
+        if (details !== undefined) {
+            this.details = details;
+        }
+    }
+}
+function workspaceOpsStatusCode(code) {
+    switch (code) {
+        case "bad_request":
+            return 400;
+        case "forbidden":
+            return 403;
+        case "not_found":
+            return 404;
+        case "conflict":
+            return 409;
+        case "validation_failed":
+            return 422;
+        case "repo_snapshot_unavailable":
+            return 409;
+        case "git_failed":
+            return 500;
+    }
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1,13 @@
+export type GitCommandResult = {
+    status: number | null;
+    stdout: Buffer;
+    stderr: string;
+    error?: Error;
+};
+export declare function runGitRaw(args: readonly string[], workspaceRoot: string, maxBuffer?: number): GitCommandResult;
+export declare function summarizeGitFailure(args: readonly string[], result: GitCommandResult): string;
+export declare function runGitText(args: readonly string[], workspaceRoot: string): string;
+export declare function runGit(args: readonly string[], workspaceRoot: string): void;
+export declare function tryGitText(args: readonly string[], workspaceRoot: string): string | null;
+export declare function stagedChangesExist(workspaceRoot: string): boolean;
+//# sourceMappingURL=git.d.ts.map

package/dist/workspace-ops/git.js

@@ -0,0 +1,53 @@
+import { spawnSync } from "node:child_process";
+import { WorkspaceOpsError } from "./errors.js";
+export function runGitRaw(args, workspaceRoot, maxBuffer = 10 * 1024 * 1024) {
+    const result = spawnSync("git", [...args], {
+        cwd: workspaceRoot,
+        encoding: "buffer",
+        maxBuffer,
+        shell: false,
+    });
+    return {
+        status: result.status,
+        stdout: Buffer.isBuffer(result.stdout) ? result.stdout : Buffer.from(result.stdout ?? ""),
+        stderr: Buffer.isBuffer(result.stderr)
+            ? result.stderr.toString("utf8")
+            : String(result.stderr ?? ""),
+        ...(result.error === undefined ? {} : { error: result.error }),
+    };
+}
+export function summarizeGitFailure(args, result) {
+    const stderr = result.stderr.trim();
+    if (stderr.length > 0) {
+        return stderr;
+    }
+    if (result.error !== undefined) {
+        return result.error.message;
+    }
+    return `git ${args.join(" ")} failed`;
+}
+export function runGitText(args, workspaceRoot) {
+    const result = runGitRaw(args, workspaceRoot);
+    if (result.status !== 0) {
+        throw new WorkspaceOpsError("git_failed", summarizeGitFailure(args, result));
+    }
+    return result.stdout.toString("utf8").trim();
+}
+export function runGit(args, workspaceRoot) {
+    const result = runGitRaw(args, workspaceRoot);
+    if (result.status !== 0) {
+        throw new WorkspaceOpsError("git_failed", summarizeGitFailure(args, result));
+    }
+}
+export function tryGitText(args, workspaceRoot) {
+    const result = runGitRaw(args, workspaceRoot);
+    if (result.status !== 0) {
+        return null;
+    }
+    return result.stdout.toString("utf8").trim();
+}
+export function stagedChangesExist(workspaceRoot) {
+    const result = runGitRaw(["diff", "--cached", "--quiet"], workspaceRoot);
+    return result.status !== 0;
+}
+//# sourceMappingURL=git.js.map

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

@@ -0,0 +1,11 @@
+export { DEFAULT_VIEWER_MAX_BYTES, MAX_REFERENCE_UPLOAD_BYTES, MAX_VIEWER_MAX_BYTES, PROJECT_DOC_PATHS, REFERENCE_IMAGE_ASSET_CACHE_VERSION, REFERENCE_IMAGE_PREVIEW_MAX_EDGE_PX, REFERENCE_IMAGE_THUMBNAIL_MAX_EDGE_PX, REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, VIEWER_ASSET_READ_LIMIT_BYTES, VIEWER_HARD_READ_LIMIT_BYTES, WORKSPACE_OPS_MAINLINE_BRANCH, } from "./constants.js";
+export { WorkspaceOpsError } from "./errors.js";
+export { initializeProjectDocs, readProjectDocsInitializationStatus, syncProjectDocs, } from "./project-docs.js";
+export { uploadReferenceFile } from "./reference-files.js";
+export { referenceFileCategoryForPath, referenceMediaTypeForPath } from "./reference-metadata.js";
+export { readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";
+export { applyRunResultToMergeWorkspace, cleanupMergeWorkspace, cleanupRunWorkspace, cleanupStaleRunWorkspaces, collectMergeDiff, collectRunDiff, createMergeCandidateCommit, createResultCommit, prepareMergeWorkspace, prepareRunWorkspace, promoteMergeCandidate, promoteRunResult, } from "./run-workspaces.js";
+export { readViewerAsset, readViewerFile, readViewerSnapshot, readViewerTree } from "./viewer.js";
+export type { WorkspaceOpsErrorCode } from "./errors.js";
+export type { CleanupRunWorkspaceResult, CleanupStaleRunWorkspacesResult, InitializeProjectDocsOptions, InitializeProjectDocsResult, MergeWorkspaceHandle, PrepareMergeWorkspaceOptions, PrepareRunWorkspaceOptions, ProjectDocsInitializationContext, ProjectDocsInitializationDocument, ProjectDocsInitializationStatus, PromotionResult, ReadViewerAssetOptions, ReadViewerFileOptions, ReadViewerTreeOptions, ReferenceFileCategory, ReferenceSummaryProjection, ReferenceSummaryRecord, ReferenceSummaryStatus, ReferenceSummaryTarget, ResultCommit, RunDiffSummary, RunWorkspaceHandle, SyncProjectDocsResult, SyncProjectDocsUpdate, UpdateReferenceSummariesOptions, UpdateReferenceSummariesResult, UploadReferenceFileOptions, UploadReferenceFileResult, ViewerAssetResult, ViewerAssetVariant, ViewerEntryKind, ViewerFileContent, ViewerFileResult, ViewerRepoSnapshot, ViewerTreeEntry, ViewerTreeResult, WorkspaceViewerOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/workspace-ops/index.js

@@ -0,0 +1,9 @@
+export { DEFAULT_VIEWER_MAX_BYTES, MAX_REFERENCE_UPLOAD_BYTES, MAX_VIEWER_MAX_BYTES, PROJECT_DOC_PATHS, REFERENCE_IMAGE_ASSET_CACHE_VERSION, REFERENCE_IMAGE_PREVIEW_MAX_EDGE_PX, REFERENCE_IMAGE_THUMBNAIL_MAX_EDGE_PX, REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, VIEWER_ASSET_READ_LIMIT_BYTES, VIEWER_HARD_READ_LIMIT_BYTES, WORKSPACE_OPS_MAINLINE_BRANCH, } from "./constants.js";
+export { WorkspaceOpsError } from "./errors.js";
+export { initializeProjectDocs, readProjectDocsInitializationStatus, syncProjectDocs, } from "./project-docs.js";
+export { uploadReferenceFile } from "./reference-files.js";
+export { referenceFileCategoryForPath, referenceMediaTypeForPath } from "./reference-metadata.js";
+export { readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";
+export { applyRunResultToMergeWorkspace, cleanupMergeWorkspace, cleanupRunWorkspace, cleanupStaleRunWorkspaces, collectMergeDiff, collectRunDiff, createMergeCandidateCommit, createResultCommit, prepareMergeWorkspace, prepareRunWorkspace, promoteMergeCandidate, promoteRunResult, } from "./run-workspaces.js";
+export { readViewerAsset, readViewerFile, readViewerSnapshot, readViewerTree } from "./viewer.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,2 @@
+export declare function requireMainlineWriteReady(workspaceRoot: string): void;
+//# sourceMappingURL=mainline.d.ts.map

package/dist/workspace-ops/mainline.js

@@ -0,0 +1,16 @@
+import { WORKSPACE_OPS_MAINLINE_BRANCH } from "./constants.js";
+import { WorkspaceOpsError } from "./errors.js";
+import { tryGitText } from "./git.js";
+import { readViewerSnapshot } from "./viewer.js";
+export function requireMainlineWriteReady(workspaceRoot) {
+    readViewerSnapshot({ workspaceRoot });
+    const currentBranch = tryGitText(["branch", "--show-current"], workspaceRoot);
+    if (currentBranch !== WORKSPACE_OPS_MAINLINE_BRANCH) {
+        throw new WorkspaceOpsError("conflict", "Mainline write requires the mainline branch to be checked out");
+    }
+    const status = tryGitText(["status", "--porcelain"], workspaceRoot);
+    if (status !== "") {
+        throw new WorkspaceOpsError("conflict", "Mainline write requires a clean mainline working tree");
+    }
+}
+//# sourceMappingURL=mainline.js.map

package/dist/workspace-ops/project-doc-templates.d.ts

@@ -0,0 +1,12 @@
+import type { PROJECT_DOC_PATHS } from "./constants.js";
+import type { ProjectDocsInitializationContext } from "./types.js";
+export type ProjectDocRepoFactHints = {
+    directories: string[];
+    root_files: string[];
+    package_managers: string[];
+    frameworks: string[];
+    entrypoints: string[];
+};
+export declare function repoFactHints(workspaceRoot: string): ProjectDocRepoFactHints;
+export declare function projectDocTemplate(path: (typeof PROJECT_DOC_PATHS)[number], projectName: string, context: ProjectDocsInitializationContext | undefined, repoHints: ProjectDocRepoFactHints): string;
+//# sourceMappingURL=project-doc-templates.d.ts.map

package/dist/workspace-ops/project-doc-templates.js

@@ -0,0 +1,180 @@
+import { readViewerTree } from "./viewer.js";
+function asBulletList(items, fallback) {
+    const normalized = items?.map((item) => item.trim()).filter((item) => item.length > 0) ?? [];
+    if (normalized.length === 0) {
+        return `- ${fallback}`;
+    }
+    return normalized.map((item) => `- ${item}`).join("\n");
+}
+function asParagraph(value, fallback) {
+    const normalized = value?.trim();
+    return normalized === undefined || normalized.length === 0 ? fallback : normalized;
+}
+export function repoFactHints(workspaceRoot) {
+    const tree = readViewerTree({ workspaceRoot, depth: 2 });
+    const paths = tree.items.map((entry) => entry.path);
+    const rootEntries = tree.items.filter((entry) => entry.depth === 1);
+    const rootFiles = rootEntries
+        .filter((entry) => entry.kind === "file")
+        .map((entry) => entry.path)
+        .slice(0, 12);
+    const directories = rootEntries
+        .filter((entry) => entry.kind === "directory")
+        .map((entry) => entry.path)
+        .slice(0, 12);
+    const pathSet = new Set(paths);
+    const packageManagers = [];
+    const frameworks = [];
+    const entrypoints = [];
+    if (pathSet.has("package.json")) {
+        packageManagers.push("npm-compatible JavaScript package metadata");
+    }
+    if (pathSet.has("package-lock.json")) {
+        packageManagers.push("npm lockfile");
+    }
+    if (pathSet.has("pnpm-lock.yaml")) {
+        packageManagers.push("pnpm lockfile");
+    }
+    if (pathSet.has("yarn.lock")) {
+        packageManagers.push("Yarn lockfile");
+    }
+    if (pathSet.has("pyproject.toml")) {
+        packageManagers.push("Python pyproject");
+    }
+    if (pathSet.has("requirements.txt")) {
+        packageManagers.push("Python requirements file");
+    }
+    if (pathSet.has("Dockerfile")) {
+        frameworks.push("Docker");
+    }
+    if (pathSet.has("docker-compose.yml") || pathSet.has("docker-compose.yaml")) {
+        frameworks.push("Docker Compose");
+    }
+    for (const candidate of [
+        "src/main.ts",
+        "src/main.tsx",
+        "src/index.ts",
+        "src/index.tsx",
+        "src/App.tsx",
+        "index.html",
+        "server.js",
+        "app.py",
+        "main.py",
+    ]) {
+        if (pathSet.has(candidate)) {
+            entrypoints.push(candidate);
+        }
+    }
+    return {
+        directories,
+        root_files: rootFiles,
+        package_managers: packageManagers,
+        frameworks,
+        entrypoints,
+    };
+}
+export function projectDocTemplate(path, projectName, context, repoHints) {
+    const scratchpad = context?.scratchpad;
+    switch (path) {
+        case "product.md":
+            return `# Product
+
+## Purpose
+
+${projectName} is a Tutti-managed project.
+
+Current startup topic: ${asParagraph(scratchpad?.topic, "To be confirmed.")}
+
+Background: ${asParagraph(scratchpad?.background_summary, "To be confirmed.")}
+
+## Target Users
+
+- To be confirmed.
+
+## Key Features
+
+${asBulletList([...(scratchpad?.current_consensus ?? []), ...(scratchpad?.task_changes ?? [])], "To be confirmed.")}
+
+## Business Objectives
+
+- Establish the initial project context baseline.
+- Convert confirmed discussion into an executable Worklist.
+`;
+        case "tech.md":
+            return `# Tech
+
+## Frameworks
+
+${asBulletList(repoHints.frameworks, "To be confirmed from the repository.")}
+
+## Libraries
+
+- To be confirmed from the repository.
+
+## Development Tools
+
+${asBulletList(repoHints.package_managers, "To be confirmed from the repository.")}
+
+## Technical Constraints
+
+- Keep this document synchronized when stable technical facts change.
+- Do not infer unconfirmed technology choices from discussion alone.
+`;
+        case "structure.md":
+            return `# Structure
+
+## File Organization
+
+${asBulletList([
+                ...repoHints.directories.map((directory) => `Top-level directory: \`${directory}/\``),
+                ...repoHints.root_files.map((file) => `Root file: \`${file}\``),
+            ], "Repository structure is pending context sync.")}
+- Human-uploaded reference materials, when present, live under \`docs/reference/\`.
+
+## Naming Conventions
+
+- To be confirmed.
+
+## Import Patterns
+
+- To be confirmed.
+
+## Architectural Decisions
+
+${asBulletList(scratchpad?.current_consensus, "To be confirmed.")}
+`;
+        case "architecture-principles.md":
+            return `# Architecture Principles
+
+## Scope
+
+These principles apply to implementation work in this project.
+
+## Core Principles
+
+- Current context before change.
+- Atomic task delivery.
+- Stable increments over large rewrites.
+- Clear responsibility boundaries.
+- Documentation stays in sync.
+
+## Boundary Rules
+
+- Prefer extending existing structure before adding new top-level structure.
+- Escalate when key architecture facts are missing.
+
+## Quality Gates
+
+- Run relevant validation before marking implementation complete.
+
+## Human Escalation
+
+- Ask for confirmation when requirements, safety, or architecture boundaries are unclear.
+
+## Documentation Duties
+
+- Update project documents and directory README files when stable facts change.
+`;
+    }
+}
+//# sourceMappingURL=project-doc-templates.js.map

package/dist/workspace-ops/project-docs.d.ts

@@ -0,0 +1,7 @@
+import type { InitializeProjectDocsOptions, InitializeProjectDocsResult, ProjectDocsInitializationStatus, SyncProjectDocsResult, SyncProjectDocsUpdate, WorkspaceViewerOptions } from "./types.js";
+export declare function readProjectDocsInitializationStatus(options: WorkspaceViewerOptions): ProjectDocsInitializationStatus;
+export declare function initializeProjectDocs(options: InitializeProjectDocsOptions): InitializeProjectDocsResult;
+export declare function syncProjectDocs(options: WorkspaceViewerOptions & {
+    updates: SyncProjectDocsUpdate[];
+}): SyncProjectDocsResult;
+//# sourceMappingURL=project-docs.d.ts.map

package/dist/workspace-ops/project-docs.js

@@ -0,0 +1,156 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { extname, join, posix } from "node:path";
+import { PROJECT_DOC_PATHS } from "./constants.js";
+import { WorkspaceOpsError } from "./errors.js";
+import { runGit, runGitText, stagedChangesExist } from "./git.js";
+import { requireMainlineWriteReady } from "./mainline.js";
+import { projectDocTemplate, repoFactHints } from "./project-doc-templates.js";
+import { entryKind, lsPath, readViewerSnapshot, requireNormalizedViewerPath, } from "./viewer.js";
+const MAX_PROJECT_DOC_SYNC_BYTES = 512 * 1024;
+function projectDocExists(workspaceRoot, path) {
+    return lsPath(workspaceRoot, path) !== null;
+}
+function requireProjectDocsSyncPath(options) {
+    const path = requireNormalizedViewerPath(options.path);
+    if (path === "") {
+        throw new WorkspaceOpsError("validation_failed", "Project docs sync path is required");
+    }
+    if (PROJECT_DOC_PATHS.includes(path)) {
+        if (!projectDocExists(options.workspaceRoot, path)) {
+            throw new WorkspaceOpsError("validation_failed", "Context sync must not create missing baseline context files");
+        }
+        return path;
+    }
+    const parentPath = posix.dirname(path);
+    const isReadmePath = path === "README.md" || path.endsWith("/README.md");
+    if (isReadmePath) {
+        if (parentPath !== ".") {
+            const parent = lsPath(options.workspaceRoot, parentPath);
+            if (parent === null || entryKind(parent) !== "directory") {
+                throw new WorkspaceOpsError("validation_failed", "Context sync README parent directory does not exist");
+            }
+        }
+        return path;
+    }
+    const isMarkdownPath = extname(path).toLowerCase() === ".md";
+    if (isMarkdownPath) {
+        const existing = lsPath(options.workspaceRoot, path);
+        if (existing === null || entryKind(existing) !== "file") {
+            throw new WorkspaceOpsError("validation_failed", "Context sync can only update existing Markdown documentation files");
+        }
+        return path;
+    }
+    throw new WorkspaceOpsError("forbidden", "Context sync may only update project docs, README.md files, or existing Markdown documentation files");
+}
+export function readProjectDocsInitializationStatus(options) {
+    readViewerSnapshot(options);
+    const existingPaths = [];
+    const missingPaths = [];
+    for (const path of PROJECT_DOC_PATHS) {
+        if (projectDocExists(options.workspaceRoot, path)) {
+            existingPaths.push(path);
+        }
+        else {
+            missingPaths.push(path);
+        }
+    }
+    return {
+        ready: missingPaths.length === 0,
+        missing_paths: missingPaths,
+        existing_paths: existingPaths,
+    };
+}
+export function initializeProjectDocs(options) {
+    requireMainlineWriteReady(options.workspaceRoot);
+    const createdPaths = [];
+    const repoHints = repoFactHints(options.workspaceRoot);
+    const providedDocuments = new Map();
+    for (const document of options.documents ?? []) {
+        let path;
+        try {
+            path = requireNormalizedViewerPath(document.path);
+        }
+        catch (error) {
+            if (error instanceof WorkspaceOpsError) {
+                continue;
+            }
+            throw error;
+        }
+        if (PROJECT_DOC_PATHS.includes(path) &&
+            document.content.trim().length > 0) {
+            providedDocuments.set(path, document.content);
+        }
+    }
+    for (const path of PROJECT_DOC_PATHS) {
+        if (projectDocExists(options.workspaceRoot, path)) {
+            continue;
+        }
+        const content = providedDocuments.get(path) ?? projectDocTemplate(path, options.projectName, options.context, repoHints);
+        writeFileSync(join(options.workspaceRoot, path), `${content.trimEnd()}\n`, "utf8");
+        createdPaths.push(path);
+    }
+    if (createdPaths.length === 0) {
+        return { created_paths: [] };
+    }
+    runGit(["add", "--", ...createdPaths], options.workspaceRoot);
+    if (stagedChangesExist(options.workspaceRoot)) {
+        runGit(["commit", "-m", "Initialize project docs"], options.workspaceRoot);
+    }
+    return {
+        created_paths: createdPaths,
+        commit_oid: runGitText(["rev-parse", "--verify", "HEAD"], options.workspaceRoot),
+    };
+}
+export function syncProjectDocs(options) {
+    requireMainlineWriteReady(options.workspaceRoot);
+    const normalizedUpdates = options.updates.map((update) => {
+        const normalizedPath = requireProjectDocsSyncPath({
+            workspaceRoot: options.workspaceRoot,
+            path: update.path,
+        });
+        const content = update.content.trimEnd();
+        if (content.length === 0) {
+            throw new WorkspaceOpsError("validation_failed", "Project docs sync content cannot be empty");
+        }
+        if (Buffer.byteLength(content, "utf8") > MAX_PROJECT_DOC_SYNC_BYTES) {
+            throw new WorkspaceOpsError("validation_failed", `Project docs sync content cannot exceed ${MAX_PROJECT_DOC_SYNC_BYTES} bytes`);
+        }
+        return {
+            path: normalizedPath,
+            content: `${content}\n`,
+        };
+    });
+    const seenPaths = new Set();
+    for (const update of normalizedUpdates) {
+        if (seenPaths.has(update.path)) {
+            throw new WorkspaceOpsError("validation_failed", "Context sync cannot update the same path more than once");
+        }
+        seenPaths.add(update.path);
+    }
+    const updatedPaths = [];
+    for (const update of normalizedUpdates) {
+        const filesystemPath = join(options.workspaceRoot, ...update.path.split("/"));
+        const existing = existsSync(filesystemPath) ? readFileSync(filesystemPath, "utf8") : "";
+        if (existing === update.content) {
+            continue;
+        }
+        const directory = posix.dirname(update.path);
+        if (directory !== ".") {
+            mkdirSync(join(options.workspaceRoot, ...directory.split("/")), { recursive: true });
+        }
+        writeFileSync(filesystemPath, update.content, "utf8");
+        updatedPaths.push(update.path);
+    }
+    if (updatedPaths.length === 0) {
+        return { updated_paths: [] };
+    }
+    runGit(["add", "--", ...updatedPaths], options.workspaceRoot);
+    if (stagedChangesExist(options.workspaceRoot)) {
+        runGit(["commit", "-m", "Sync project docs"], options.workspaceRoot);
+    }
+    return {
+        updated_paths: updatedPaths,
+        commit_oid: runGitText(["rev-parse", "--verify", "HEAD"], options.workspaceRoot),
+    };
+}
+//# sourceMappingURL=project-docs.js.map

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

@@ -0,0 +1,3 @@
+import type { UploadReferenceFileOptions, UploadReferenceFileResult } from "./types.js";
+export declare function uploadReferenceFile(options: UploadReferenceFileOptions): UploadReferenceFileResult;
+//# sourceMappingURL=reference-files.d.ts.map

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

@@ -0,0 +1,137 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { extname, join, posix } from "node:path";
+import { classifyViewerPath } from "@tutti/shared/utils";
+import { MAX_REFERENCE_UPLOAD_BYTES, REFERENCE_DIRECTORY_PATH, REFERENCE_INDEX_PATH, } from "./constants.js";
+import { WorkspaceOpsError } from "./errors.js";
+import { runGit, runGitText, stagedChangesExist } from "./git.js";
+import { requireMainlineWriteReady } from "./mainline.js";
+import { classifyReferenceUpload } from "./reference-metadata.js";
+import { readViewerFile } from "./viewer.js";
+function commandSuffix(commandId) {
+    return commandId.slice(-8).toLowerCase();
+}
+function sanitizeReferenceFileName(fileName, commandId) {
+    const raw = fileName.trim();
+    if (raw.length === 0) {
+        throw new WorkspaceOpsError("validation_failed", "Reference file name cannot be empty");
+    }
+    if (raw.includes("/") || raw.includes("\\")) {
+        throw new WorkspaceOpsError("validation_failed", "Reference file name must not include directories");
+    }
+    const rawClassification = classifyViewerPath(raw);
+    if (rawClassification.kind === "rejected") {
+        throw new WorkspaceOpsError("validation_failed", `Reference file name is rejected: ${rawClassification.reason_code}`, { reason_code: rawClassification.reason_code });
+    }
+    const extension = extname(raw)
+        .toLowerCase()
+        .replace(/[^.a-z0-9]/gu, "");
+    const rawStem = extension.length > 0 ? raw.slice(0, -extension.length) : raw;
+    const stem = rawStem
+        .replace(/[^A-Za-z0-9._-]+/gu, "-")
+        .replace(/-{2,}/gu, "-")
+        .replace(/^[.-]+/u, "")
+        .replace(/[.-]+$/u, "");
+    if (stem.length === 0) {
+        throw new WorkspaceOpsError("validation_failed", "Reference file name cannot be normalized");
+    }
+    const safeName = `${stem}-${commandSuffix(commandId)}${extension}`;
+    const path = `${REFERENCE_DIRECTORY_PATH}/${safeName}`;
+    const classification = classifyViewerPath(path);
+    if (classification.kind === "rejected") {
+        throw new WorkspaceOpsError("validation_failed", `Reference file path is rejected: ${classification.reason_code}`, { reason_code: classification.reason_code });
+    }
+    return safeName;
+}
+function appendReferenceIndexEntry(options) {
+    const indexPath = join(options.workspaceRoot, "docs", "reference", "README.md");
+    const existing = existsSync(indexPath) ? readFileSync(indexPath, "utf8") : "";
+    let content = existing.trim().length === 0
+        ? [
+            "# Reference Files",
+            "",
+            "Human-uploaded project reference files.",
+            "",
+            "## Files",
+            "",
+            "## Images",
+            "",
+        ].join("\n")
+        : existing.replace(/\s*$/u, "\n");
+    if (!content.includes("\n## Files\n")) {
+        content = `${content.trimEnd()}\n\n## Files\n\n`;
+    }
+    if (!content.includes("\n## Images\n")) {
+        content = `${content.trimEnd()}\n\n## Images\n\n`;
+    }
+    const relativePath = posix.relative(REFERENCE_DIRECTORY_PATH, options.repoPath);
+    const link = `./${relativePath}`;
+    const note = options.note?.trim();
+    const description = note === undefined || note.length === 0 ? "" : ` - ${note}`;
+    const line = `- [${options.fileName}](${link})${description}\n`;
+    if (content.includes(`](${link})`)) {
+        writeFileSync(indexPath, content, "utf8");
+        return;
+    }
+    const section = options.category === "image" ? "Images" : "Files";
+    const sectionStart = content.indexOf(`\n## ${section}\n`);
+    if (sectionStart === -1) {
+        writeFileSync(indexPath, `${content.trimEnd()}\n\n## ${section}\n\n${line}`, "utf8");
+        return;
+    }
+    const insertAfter = sectionStart + `\n## ${section}\n`.length;
+    const nextSection = content.indexOf("\n## ", insertAfter);
+    const insertAt = nextSection === -1 ? content.length : nextSection;
+    const before = content.slice(0, insertAt).replace(/\s*$/u, "\n\n");
+    const after = content.slice(insertAt).replace(/^\n*/u, "");
+    const nextContent = after.length === 0 ? `${before}${line}` : `${before}${line}\n${after}`;
+    writeFileSync(indexPath, nextContent, "utf8");
+}
+export function uploadReferenceFile(options) {
+    if (options.content.byteLength > MAX_REFERENCE_UPLOAD_BYTES) {
+        throw new WorkspaceOpsError("validation_failed", `Reference file content cannot exceed ${MAX_REFERENCE_UPLOAD_BYTES} bytes`);
+    }
+    requireMainlineWriteReady(options.workspaceRoot);
+    const safeName = sanitizeReferenceFileName(options.fileName, options.commandId);
+    const classification = classifyReferenceUpload({
+        fileName: options.fileName,
+        content: options.content,
+        ...(options.mediaType === undefined ? {} : { mediaType: options.mediaType }),
+    });
+    const referenceDirectory = join(options.workspaceRoot, ...classification.directoryPath.split("/"));
+    const repoPath = `${classification.directoryPath}/${safeName}`;
+    const filesystemPath = join(referenceDirectory, safeName);
+    mkdirSync(referenceDirectory, { recursive: true });
+    if (existsSync(filesystemPath)) {
+        const existing = readFileSync(filesystemPath);
+        if (!existing.equals(options.content)) {
+            throw new WorkspaceOpsError("conflict", "Reference file path already exists with different content");
+        }
+    }
+    else {
+        writeFileSync(filesystemPath, options.content);
+    }
+    appendReferenceIndexEntry({
+        workspaceRoot: options.workspaceRoot,
+        fileName: safeName,
+        repoPath,
+        category: classification.category,
+        ...(options.note === undefined ? {} : { note: options.note }),
+    });
+    runGit(["add", "--", REFERENCE_INDEX_PATH, repoPath], options.workspaceRoot);
+    if (stagedChangesExist(options.workspaceRoot)) {
+        runGit(["commit", "-m", `Add reference file: ${safeName}`], options.workspaceRoot);
+    }
+    const commitOid = runGitText(["rev-parse", "--verify", "HEAD"], options.workspaceRoot);
+    const file = readViewerFile({
+        workspaceRoot: options.workspaceRoot,
+        path: repoPath,
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    return {
+        file: file.file,
+        category: classification.category,
+        index_path: REFERENCE_INDEX_PATH,
+        commit_oid: commitOid,
+    };
+}
+//# sourceMappingURL=reference-files.js.map

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

@@ -0,0 +1,13 @@
+import type { ReferenceFileCategory, ViewerAssetResult } from "./types.js";
+export declare function detectReferenceImageMediaType(content: Buffer): ViewerAssetResult["media_type"] | undefined;
+export declare function classifyReferenceUpload(options: {
+    fileName: string;
+    content: Buffer;
+    mediaType?: string;
+}): {
+    category: ReferenceFileCategory;
+    directoryPath: string;
+};
+export declare function referenceFileCategoryForPath(path: string): ReferenceFileCategory | undefined;
+export declare function referenceMediaTypeForPath(path: string): string | undefined;
+//# sourceMappingURL=reference-metadata.d.ts.map