project-tiny-context-harness 0.2.60 → 0.2.61

package/dist/lib/source-pack-classify.js

@@ -0,0 +1,142 @@
+import path from "node:path";
+import { SAFE_EXAMPLE_FILE_NAMES } from "./source-files.js";
+const OVERSIZED_LINES = 1000;
+const OVERSIZED_CHARACTERS = 50_000;
+export function classifyCodeFile(relative, content, areas) {
+    const language = languageFor(relative) || "text";
+    const routes = extractRouteSummary(content);
+    const tags = tagsFor(relative, content, language, routes);
+    return {
+        language,
+        summary: summarizeCodeFile(relative, content, language),
+        tags,
+        routes,
+        score: scoreFor(tags, relative),
+        bucket: routingBucket(relative, areas)
+    };
+}
+function tagsFor(relative, content, language, routes) {
+    const lower = relative.toLowerCase();
+    const tags = new Set();
+    const lines = content.length === 0 ? 0 : content.split(/\r\n|\r|\n/).length;
+    if (isLikelyEntrypoint(relative))
+        tags.add("entry");
+    if (routes.length > 0 || /route|controller|api/.test(lower))
+        tags.add("api");
+    if (/cli|commands|bin\//.test(lower))
+        tags.add("cli");
+    if (/worker|scheduler|queue|runtime|cron|job/.test(lower))
+        tags.add("worker");
+    if (/schema|contract|types?\.|\.d\.ts$/.test(lower) || /\b(interface|type|schema)\b/.test(content))
+        tags.add("contract");
+    if (/pages|views|screens|components|\.vue$|\.tsx$|\.jsx$/.test(lower))
+        tags.add("ui");
+    if (/test|spec|verification|makefile/.test(lower))
+        tags.add("test");
+    if (["json", "yaml", "toml", "make", "dockerfile"].includes(language))
+        tags.add("config");
+    if (lines > OVERSIZED_LINES || content.length > OVERSIZED_CHARACTERS)
+        tags.add("oversized");
+    return [...tags].sort();
+}
+function scoreFor(tags, relative) {
+    const weights = { entry: 50, api: 35, cli: 32, worker: 30, contract: 28, ui: 24, test: 18, config: 12, oversized: -15 };
+    return tags.reduce((sum, tag) => sum + (weights[tag] ?? 0), 0) + Math.max(0, 20 - relative.split("/").length);
+}
+function routingBucket(relative, areas) {
+    for (const area of areas) {
+        if (area.root === "." || relative === area.root || relative.startsWith(`${area.root}/`)) {
+            return `area:${area.id}`;
+        }
+    }
+    const parts = relative.split("/");
+    for (const prefix of ["domains", "apps", "services", "packages", "tools"]) {
+        if (parts[0] === prefix && parts[1]) {
+            return `${prefix}:${parts[1]}`;
+        }
+    }
+    return parts[0] || "misc";
+}
+function summarizeCodeFile(relative, content, language) {
+    const base = path.posix.basename(relative);
+    const symbols = extractSymbolSummary(content, language);
+    if (base === "package.json") {
+        const packageName = /"name"\s*:\s*"([^"]+)"/.exec(content)?.[1];
+        return packageName ? `Defines npm package ${packageName} metadata, scripts and dependencies.` : "Defines npm package metadata, scripts and dependencies.";
+    }
+    if (base.toLowerCase() === "makefile") {
+        const targets = [...content.matchAll(/^([A-Za-z0-9_.-]+):/gm)].map((match) => match[1]).slice(0, 6);
+        return targets.length > 0 ? `Defines Make targets ${targets.join(", ")}.` : "Defines Make targets for local automation.";
+    }
+    if (symbols.length > 0) {
+        return `${describeFilePurpose(relative, language)}; exposes ${symbols.slice(0, 6).join(", ")}.`;
+    }
+    return `${describeFilePurpose(relative, language)}.`;
+}
+function extractSymbolSummary(content, language) {
+    const patterns = language === "python"
+        ? [/^(?:async\s+)?def\s+([A-Za-z_][\w]*)/gm, /^class\s+([A-Za-z_][\w]*)/gm]
+        : language === "go"
+            ? [/^func\s+(?:\([^)]+\)\s*)?([A-Za-z_][\w]*)/gm, /^type\s+([A-Za-z_][\w]*)/gm]
+            : [
+                /(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g,
+                /(?:export\s+)?class\s+([A-Za-z_$][\w$]*)/g,
+                /(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/g,
+                /(?:export\s+)?type\s+([A-Za-z_$][\w$]*)/g,
+                /(?:export\s+)?const\s+([A-Za-z_$][\w$]*)/g
+            ];
+    const symbols = new Set();
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(content)) && symbols.size < 10)
+            symbols.add(match[1]);
+    }
+    for (const route of extractRouteSummary(content)) {
+        if (symbols.size < 10)
+            symbols.add(route);
+    }
+    return [...symbols];
+}
+function extractRouteSummary(content) {
+    const routes = new Set();
+    const patterns = [/\.(get|post|put|patch|delete|head|options)\s*\(\s*["'`]([^"'`]+)["'`]/gi, /\bHandle(?:Func)?\s*\(\s*["'`]([^"'`]+)["'`]/g];
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(content)) && routes.size < 8) {
+            routes.add(match.length === 3 ? `${match[1].toUpperCase()} ${match[2]}` : `route ${match[1]}`);
+        }
+    }
+    return [...routes].sort();
+}
+function describeFilePurpose(relative, language) {
+    const lower = relative.toLowerCase();
+    if (lower.includes("/test") || lower.includes(".test.") || lower.includes(".spec."))
+        return `Contains ${language} tests for ${path.posix.basename(relative)}`;
+    if (lower.includes("/commands/"))
+        return `Implements ${language} command handling for ${path.posix.basename(relative)}`;
+    if (lower.includes("/cli") || lower.endsWith("/cli.ts") || lower.endsWith("/cli.js"))
+        return `Implements ${language} CLI behavior for ${path.posix.basename(relative)}`;
+    if (lower.includes("/components/") || lower.includes("/pages/") || lower.includes("/views/"))
+        return `Implements ${language} UI behavior for ${path.posix.basename(relative)}`;
+    return `Contains ${language} implementation for ${path.posix.basename(relative)}`;
+}
+function isLikelyEntrypoint(relative) {
+    const lower = relative.toLowerCase();
+    const base = path.posix.basename(lower);
+    return ["package.json", "makefile", "dockerfile", "main.go", "app.py", "server.py", "index.ts", "index.js", "cli.ts", "cli.js"].includes(base) || /\/src\/(main|app|index)\.[tj]sx?$/.test(lower);
+}
+function languageFor(relative) {
+    const lower = relative.toLowerCase();
+    const base = path.posix.basename(lower);
+    if (base === "makefile")
+        return "make";
+    if (base === "dockerfile" || base.startsWith("dockerfile.") || lower.endsWith(".dockerfile"))
+        return "dockerfile";
+    if (SAFE_EXAMPLE_FILE_NAMES.has(base))
+        return "dotenv";
+    for (const [extension, language] of [[".tsx", "tsx"], [".ts", "typescript"], [".jsx", "jsx"], [".js", "javascript"], [".mjs", "javascript"], [".py", "python"], [".go", "go"], [".vue", "vue"], [".sql", "sql"], [".json", "json"], [".jsonc", "jsonc"], [".yaml", "yaml"], [".yml", "yaml"], [".toml", "toml"], [".sh", "bash"], [".ps1", "powershell"], [".cmd", "batch"], [".bat", "batch"], [".graphql", "graphql"], [".gql", "graphql"], [".proto", "protobuf"]]) {
+        if (lower.endsWith(extension))
+            return language;
+    }
+    return "";
+}

package/dist/lib/source-pack-config.d.ts

@@ -0,0 +1,7 @@
+import type { ContextAreaMapping, SourcePackProfile } from "./source-pack-types.js";
+export declare function readSourcePackProfile(projectRoot: string, profileId?: string): Promise<SourcePackProfile>;
+export declare function parseContextAreas(projectRoot: string): Promise<ContextAreaMapping[]>;
+export declare function mergePatterns(...groups: Array<string[] | undefined>): string[];
+export declare function validatePatternList(values: string[], label: string): string[];
+export declare function matchesAny(relative: string, patterns: string[]): boolean;
+export declare function normalizeRepoPath(value: string, label: string): string;

package/dist/lib/source-pack-config.js

@@ -0,0 +1,93 @@
+import path from "node:path";
+import { harnessConfigPath } from "./harness-root.js";
+import { pathExists, readText } from "./fs.js";
+import { parseYaml } from "./yaml.js";
+import { toPosix } from "./source-files.js";
+export async function readSourcePackProfile(projectRoot, profileId) {
+    if (!profileId) {
+        return { context: [], code: [], exclude: [], verification: [] };
+    }
+    const configPath = path.join(projectRoot, await harnessConfigPath(projectRoot));
+    if (!(await pathExists(configPath))) {
+        throw new Error(`source pack profile not found: ${profileId}`);
+    }
+    const parsed = parseYaml(await readText(configPath));
+    const sourcePacks = parsed && typeof parsed === "object" ? parsed.source_packs : undefined;
+    const profileValue = sourcePacks && typeof sourcePacks === "object" ? sourcePacks[profileId] : undefined;
+    if (!profileValue || typeof profileValue !== "object" || Array.isArray(profileValue)) {
+        throw new Error(`source pack profile not found: ${profileId}`);
+    }
+    const value = profileValue;
+    return {
+        context: readPatternList(value.context, `source_packs.${profileId}.context`, "context path"),
+        code: readPatternList(value.code, `source_packs.${profileId}.code`, "code path"),
+        exclude: readPatternList(value.exclude, `source_packs.${profileId}.exclude`, "exclude path"),
+        verification: readStringList(value.verification, `source_packs.${profileId}.verification`),
+        maxBundleCharacters: readPositiveInteger(value.max_bundle_characters, `source_packs.${profileId}.max_bundle_characters`)
+    };
+}
+export async function parseContextAreas(projectRoot) {
+    const manifestPath = path.join(projectRoot, "project_context", "context.toml");
+    if (!(await pathExists(manifestPath))) {
+        return [];
+    }
+    const content = await readText(manifestPath);
+    const areas = [];
+    for (const block of content.split(/\[\[areas\]\]/g).slice(1)) {
+        const id = /id\s*=\s*"([^"]+)"/.exec(block)?.[1];
+        const root = /root\s*=\s*"([^"]+)"/.exec(block)?.[1];
+        const context = /context\s*=\s*"([^"]+)"/.exec(block)?.[1];
+        if (id && root && context) {
+            areas.push({ id, root: normalizeRepoPath(root, "area root"), context: normalizeRepoPath(context, "area context") });
+        }
+    }
+    return areas.sort((left, right) => left.id.localeCompare(right.id));
+}
+export function mergePatterns(...groups) {
+    return [...new Set(groups.flatMap((group) => group ?? []).map((value) => normalizeRepoPath(value, "include path")))].sort();
+}
+export function validatePatternList(values, label) {
+    return values.map((value) => normalizeRepoPath(value, label));
+}
+export function matchesAny(relative, patterns) {
+    return patterns.some((pattern) => globToRegExp(pattern).test(relative));
+}
+export function normalizeRepoPath(value, label) {
+    const normalized = toPosix(value.trim()).replace(/^\.\//, "");
+    if (!isAllowedPatternPath(normalized)) {
+        throw new Error(`${label} must be repo-relative and stay inside the workspace: ${value}`);
+    }
+    return normalized;
+}
+function readPatternList(value, label, pathLabel) {
+    return readStringList(value, label).map((item) => normalizeRepoPath(item, pathLabel));
+}
+function readStringList(value, label) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim().length === 0)) {
+        throw new Error(`<harnessRoot>/config.yaml ${label} must be an array of non-empty strings`);
+    }
+    return value.map((item) => item.trim());
+}
+function readPositiveInteger(value, label) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Number.isInteger(value) || Number(value) <= 0) {
+        throw new Error(`<harnessRoot>/config.yaml ${label} must be a positive integer`);
+    }
+    return Number(value);
+}
+function isAllowedPatternPath(value) {
+    return value.length > 0 && !path.posix.isAbsolute(value) && !value.split("/").includes("..");
+}
+function globToRegExp(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "\0")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\0/g, ".*");
+    return new RegExp(`^${escaped}$`);
+}

package/dist/lib/source-pack-export.d.ts

@@ -0,0 +1,2 @@
+import type { SourcePackOptions, SourcePackReport } from "./source-pack-types.js";
+export declare function runSourcePackExport(projectRoot: string, options: SourcePackOptions): Promise<SourcePackReport>;

package/dist/lib/source-pack-export.js

@@ -0,0 +1,223 @@
+import path from "node:path";
+import { artifactReport, buildManifest, pruneTimestampedExports, readPackageVersion, timestampForFile, writeArtifactSet } from "./source-pack-manifest.js";
+import { mergePatterns, parseContextAreas, readSourcePackProfile, validatePatternList } from "./source-pack-config.js";
+import { collectCodeRecords, collectContextArtifacts, countRedactionWarnings, repoRelative } from "./source-pack-records.js";
+import { renderBundleArtifact, renderCodeIndexArtifact, renderFullProjectContextArtifact, renderTaskContextArtifact } from "./source-pack-render.js";
+const DEFAULT_EXPORT_DIR = "tmp/ty-context/context-exports";
+const DEFAULT_MAX_PACK_FILES = 5;
+const DEFAULT_MAX_BUNDLE_CHARACTERS = 800_000;
+export async function runSourcePackExport(projectRoot, options) {
+    const maxPackFiles = options.maxPackFiles ?? DEFAULT_MAX_PACK_FILES;
+    validateMaxPackFiles(options.mode, maxPackFiles);
+    const now = options.now ?? new Date();
+    const timestamp = timestampForFile(now);
+    const timestampDir = path.join(projectRoot, ...DEFAULT_EXPORT_DIR.split("/"), timestamp);
+    const generatedAt = now.toISOString();
+    const warnings = [];
+    const areas = await parseContextAreas(projectRoot);
+    const profile = await readSourcePackProfile(projectRoot, options.profile);
+    const includeCode = mergePatterns(profile.code, validatePatternList(options.includeCode ?? [], "include code path"));
+    const includeContext = mergePatterns(profile.context, validatePatternList(options.includeContext ?? [], "include context path"));
+    const exclude = mergePatterns(profile.exclude);
+    const maxBundleCharacters = options.maxBundleCharacters ?? profile.maxBundleCharacters ?? DEFAULT_MAX_BUNDLE_CHARACTERS;
+    const bundleStrategy = options.bundleStrategy ?? "auto";
+    const records = await collectCodeRecords(projectRoot, warnings, {
+        include: includeCode.length > 0 ? includeCode : undefined,
+        exclude,
+        areas
+    });
+    const contexts = await collectContextArtifacts(projectRoot, warnings, options.mode === "task-context" && includeContext.length > 0 ? includeContext : undefined);
+    const taskName = options.taskName ?? "";
+    const command = options.command ?? commandFor(options);
+    const toolVersion = await readPackageVersion();
+    const recommendedUploadSets = uploadSets(options.mode, timestamp, taskName);
+    const artifacts = [];
+    if (options.mode === "code-index" || options.mode === "source-pack" || options.mode === "code-bundles" || options.mode === "task-context") {
+        assignBundles(records, maxBundleCharacters, bundleStrategy);
+        artifacts.push(markdownArtifact("code-index", "code-index.md", renderCodeIndexArtifact(records, areas, warnings, meta(generatedAt, "code-index.md", command, toolVersion)), records.length, sumLines(records), warnings.length));
+    }
+    if (options.mode === "source-pack" || options.mode === "task-context") {
+        artifacts.splice(0, 0, markdownArtifact("full-project-context", "full-project-context.md", renderFullProjectContextArtifact(contexts, warnings, meta(generatedAt, "full-project-context.md", command, toolVersion)), contexts.length, sumContextLines(contexts), warnings.length));
+    }
+    if (options.mode === "source-pack" || options.mode === "code-bundles") {
+        addDefaultBundles(artifacts, records, contexts, maxPackFiles, warnings, generatedAt, command, toolVersion);
+    }
+    if (options.mode === "task-context") {
+        addTaskArtifacts(artifacts, records, contexts, profile.verification, maxPackFiles, warnings, generatedAt, command, toolVersion, taskName, maxBundleCharacters, bundleStrategy);
+    }
+    const omitted = omittedSummary(records);
+    const nonManifestArtifacts = artifacts.slice();
+    const manifestPath = `${DEFAULT_EXPORT_DIR}/${timestamp}/source-pack-manifest.json`;
+    const manifest = await buildManifest({
+        projectRoot,
+        generatedAt,
+        command,
+        maxPackFiles,
+        artifacts: nonManifestArtifacts.map((artifact) => ({ ...artifact, relativePath: `${DEFAULT_EXPORT_DIR}/${timestamp}/${artifact.name}` })),
+        warnings,
+        omitted,
+        recommendedUploadSets
+    });
+    artifacts.unshift({
+        kind: "manifest",
+        name: "source-pack-manifest.json",
+        relativePath: manifestPath,
+        content: manifest,
+        sourceCount: 0,
+        sourceLineCount: 0,
+        warningCount: warnings.length
+    });
+    for (const artifact of artifacts) {
+        if (!artifact.relativePath) {
+            artifact.relativePath = `${DEFAULT_EXPORT_DIR}/${timestamp}/${artifact.name}`;
+        }
+    }
+    if (artifacts.length > maxPackFiles) {
+        throw new Error(`Source Pack mode ${options.mode} planned ${artifacts.length} files; max is ${maxPackFiles}`);
+    }
+    const redactionCount = countRedactionWarnings(warnings);
+    if (options.redactionStrict && redactionCount > 0) {
+        throw new Error(`export-context --redaction-strict found ${redactionCount} redaction warning(s)`);
+    }
+    if (!options.check) {
+        await writeArtifactSet(projectRoot, timestampDir, artifacts);
+        if (options.prune !== undefined) {
+            await pruneTimestampedExports(projectRoot, options.prune);
+        }
+    }
+    return {
+        mode: options.mode,
+        outputDirectory: timestampDir,
+        outputRelativePath: repoRelative(projectRoot, timestampDir),
+        artifacts: artifacts.map(artifactReport),
+        sourceFiles: records.map((record) => record.relative),
+        sourceCodeCount: records.length,
+        totalLines: sumLines(records),
+        totalCharacters: records.reduce((sum, record) => sum + record.characters, 0),
+        redactionCount,
+        warnings,
+        omitted,
+        recommendedUploadSets,
+        wrote: !options.check
+    };
+}
+function addDefaultBundles(artifacts, records, contexts, maxPackFiles, warnings, generatedAt, command, toolVersion) {
+    const omitted = omittedSummary(records);
+    const slots = maxPackFiles - artifacts.length - 1;
+    const core = records.filter((record) => record.bundle === "core");
+    const extended = records.filter((record) => record.bundle === "extended");
+    if (slots >= 1 && core.length > 0) {
+        artifacts.push(markdownArtifact("code-bundle-core", "code-bundle-core.md", renderBundleArtifact("Code Bundle Core", core, contexts, omitted, warnings, meta(generatedAt, "code-bundle-core.md", command, toolVersion), "Deterministic score-first selection of entry/API/CLI/contract/UI/test files; routing buckets are export routing only."), core.length, sumLines(core), warnings.length));
+    }
+    if (slots >= 2 && extended.length > 0) {
+        artifacts.push(markdownArtifact("code-bundle-extended", "code-bundle-extended.md", renderBundleArtifact("Code Bundle Extended", extended, contexts, omitted, warnings, meta(generatedAt, "code-bundle-extended.md", command, toolVersion), "Next highest deterministic scores after core bundle until the bundle character budget is reached."), extended.length, sumLines(extended), warnings.length));
+    }
+}
+function addTaskArtifacts(artifacts, records, contexts, verification, maxPackFiles, warnings, generatedAt, command, toolVersion, taskName, maxBundleCharacters, bundleStrategy) {
+    const slug = taskSlug(taskName);
+    const sorted = sortedRecords(records, bundleStrategy);
+    assignTaskBundles(sorted, maxBundleCharacters);
+    const taskRecords = sorted.filter((record) => record.bundle === "task");
+    const supportRecords = sorted.filter((record) => record.bundle === "task-support");
+    const omitted = omittedSummary(sorted);
+    artifacts.push(markdownArtifact("task-context", `task-contexts/task-context-${slug}.md`, renderTaskContextArtifact(taskName, contexts, taskRecords, verification, omitted, warnings, meta(generatedAt, `task-contexts/task-context-${slug}.md`, command, toolVersion)), contexts.length + taskRecords.length, sumContextLines(contexts) + sumLines(taskRecords), warnings.length));
+    const slots = maxPackFiles - artifacts.length - 1;
+    if (slots >= 1 && supportRecords.length > 0) {
+        artifacts.push(markdownArtifact("code-bundle-task-support", "code-bundle-task-support.md", renderBundleArtifact("Code Bundle Task Support", supportRecords, contexts, omitted, warnings, meta(generatedAt, "code-bundle-task-support.md", command, toolVersion), "Deterministic support files selected after the main task-context body."), supportRecords.length, sumLines(supportRecords), warnings.length));
+    }
+}
+function assignBundles(records, maxCharacters, bundleStrategy) {
+    let coreCharacters = 0;
+    let extendedCharacters = 0;
+    for (const record of sortedRecords(records, bundleStrategy)) {
+        if (coreCharacters + record.characters <= maxCharacters) {
+            record.bundle = "core";
+            coreCharacters += record.characters;
+        }
+        else if (extendedCharacters + record.characters <= maxCharacters) {
+            record.bundle = "extended";
+            extendedCharacters += record.characters;
+        }
+        else {
+            record.bundle = "omitted";
+        }
+    }
+}
+function assignTaskBundles(records, maxCharacters) {
+    let taskCharacters = 0;
+    let supportCharacters = 0;
+    for (const record of records) {
+        if (taskCharacters + record.characters <= maxCharacters) {
+            record.bundle = "task";
+            taskCharacters += record.characters;
+        }
+        else if (supportCharacters + record.characters <= maxCharacters) {
+            record.bundle = "task-support";
+            supportCharacters += record.characters;
+        }
+        else {
+            record.bundle = "omitted";
+        }
+    }
+}
+function sortedRecords(records, bundleStrategy) {
+    return [...records].sort((left, right) => {
+        if (bundleStrategy === "area" || bundleStrategy === "config") {
+            return left.bucket.localeCompare(right.bucket) || right.score - left.score || left.relative.localeCompare(right.relative);
+        }
+        if (bundleStrategy === "topdir") {
+            return topDir(left).localeCompare(topDir(right)) || right.score - left.score || left.relative.localeCompare(right.relative);
+        }
+        return right.score - left.score || left.bucket.localeCompare(right.bucket) || left.relative.localeCompare(right.relative);
+    });
+}
+function topDir(record) {
+    return record.relative.split("/")[0] || ".";
+}
+function omittedSummary(records) {
+    const omitted = records.filter((record) => record.bundle === "omitted");
+    return { source_file_count: omitted.length, reason_counts: omitted.length > 0 ? { bundle_budget: omitted.length } : {} };
+}
+function markdownArtifact(kind, name, content, sourceCount, sourceLineCount, warningCount) {
+    return { kind, name, relativePath: "", content, sourceCount, sourceLineCount, warningCount };
+}
+function meta(generatedAt, artifactName, command, toolVersion) {
+    return { generatedAt, outputPath: `tmp/ty-context/context-exports/latest/${artifactName}`, command, toolVersion };
+}
+function uploadSets(mode, timestamp, taskName) {
+    const base = `${DEFAULT_EXPORT_DIR}/${timestamp}`;
+    const sets = {
+        daily_planning: [`${base}/full-project-context.md`, `${base}/code-index.md`],
+        cross_module_review: [`${base}/full-project-context.md`, `${base}/code-index.md`, `${base}/code-bundle-core.md`, `${base}/code-bundle-extended.md`],
+        full_fallback: [`${base}/full-project-context.md`, `${base}/code-index.md`, `${DEFAULT_EXPORT_DIR}/code-level-implementation-<timestamp>/code-level-implementation.md`]
+    };
+    if (mode === "task-context") {
+        sets.focused_task_handoff = [`${base}/full-project-context.md`, `${base}/code-index.md`, `${base}/task-contexts/task-context-${taskSlug(taskName)}.md`];
+    }
+    return sets;
+}
+function validateMaxPackFiles(mode, maxPackFiles) {
+    if (!Number.isInteger(maxPackFiles) || maxPackFiles <= 0) {
+        throw new Error("export-context --max-pack-files requires a positive integer");
+    }
+    if (maxPackFiles > DEFAULT_MAX_PACK_FILES) {
+        throw new Error("export-context --max-pack-files cannot exceed 5 for Source Pack modes");
+    }
+    const required = mode === "code-index" ? 2 : mode === "task-context" ? 4 : mode === "code-bundles" ? 3 : 3;
+    if (maxPackFiles < required) {
+        throw new Error(`export-context ${mode} requires --max-pack-files >= ${required}`);
+    }
+}
+function commandFor(options) {
+    const flag = options.mode === "task-context" ? `--task-context ${options.taskName ?? ""}` : `--${options.mode}`;
+    return `ty-context export-context ${flag}`;
+}
+function taskSlug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "task";
+}
+function sumLines(records) {
+    return records.reduce((sum, record) => sum + record.lines, 0);
+}
+function sumContextLines(contexts) {
+    return contexts.reduce((sum, context) => sum + context.lines, 0);
+}

package/dist/lib/source-pack-manifest.d.ts

@@ -0,0 +1,25 @@
+import type { SourcePackArtifactReport, SourcePackOmitted } from "./source-pack-types.js";
+export interface PendingArtifact {
+    kind: string;
+    name: string;
+    relativePath: string;
+    content: string;
+    sourceCount: number;
+    sourceLineCount: number;
+    warningCount: number;
+}
+export declare function buildManifest(params: {
+    projectRoot: string;
+    generatedAt: string;
+    command: string;
+    maxPackFiles: number;
+    artifacts: PendingArtifact[];
+    warnings: string[];
+    omitted: SourcePackOmitted;
+    recommendedUploadSets: Record<string, string[]>;
+}): Promise<string>;
+export declare function artifactReport(artifact: PendingArtifact): SourcePackArtifactReport;
+export declare function writeArtifactSet(projectRoot: string, timestampDir: string, artifacts: PendingArtifact[]): Promise<void>;
+export declare function pruneTimestampedExports(projectRoot: string, keepCount: number): Promise<void>;
+export declare function timestampForFile(now: Date): string;
+export declare function readPackageVersion(): Promise<string>;

package/dist/lib/source-pack-manifest.js

@@ -0,0 +1,93 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { promises as fs } from "node:fs";
+import { ensureDir, writeTextIfChanged } from "./fs.js";
+import { repoRelative, sha256 } from "./source-pack-records.js";
+const execFileAsync = promisify(execFile);
+export async function buildManifest(params) {
+    const git = await gitInfo(params.projectRoot);
+    const manifest = {
+        schema_version: "source-pack-v1",
+        generated_at: params.generatedAt,
+        tool: "ty-context export-context",
+        tool_version: await readPackageVersion(),
+        git_sha: git.sha,
+        git_dirty: git.dirty,
+        command: params.command,
+        max_pack_files: params.maxPackFiles,
+        artifacts: params.artifacts.map((artifact) => artifactReport(artifact)),
+        warnings: params.warnings,
+        omitted: params.omitted,
+        recommended_upload_sets: params.recommendedUploadSets
+    };
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+export function artifactReport(artifact) {
+    return {
+        kind: artifact.kind,
+        name: artifact.name,
+        path: artifact.relativePath,
+        sha256: sha256(artifact.content),
+        characters: artifact.content.length,
+        source_count: artifact.sourceCount,
+        source_line_count: artifact.sourceLineCount,
+        warning_count: artifact.warningCount
+    };
+}
+export async function writeArtifactSet(projectRoot, timestampDir, artifacts) {
+    const latestDir = path.join(projectRoot, "tmp", "ty-context", "context-exports", "latest");
+    await writeArtifacts(projectRoot, timestampDir, artifacts);
+    await fs.rm(latestDir, { recursive: true, force: true });
+    await writeArtifacts(projectRoot, latestDir, artifacts);
+}
+export async function pruneTimestampedExports(projectRoot, keepCount) {
+    if (!Number.isInteger(keepCount) || keepCount < 0) {
+        throw new Error("export-context --prune requires a non-negative integer");
+    }
+    const exportsRoot = path.join(projectRoot, "tmp", "ty-context", "context-exports");
+    let entries;
+    try {
+        entries = await fs.readdir(exportsRoot);
+    }
+    catch {
+        return;
+    }
+    const timestampDirs = entries.filter((entry) => /^\d{8}T\d{6}Z$/.test(entry)).sort().reverse();
+    for (const entry of timestampDirs.slice(keepCount)) {
+        await fs.rm(path.join(exportsRoot, entry), { recursive: true, force: true });
+    }
+}
+export function timestampForFile(now) {
+    return now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+}
+async function writeArtifacts(projectRoot, outputDir, artifacts) {
+    for (const artifact of artifacts) {
+        const target = path.join(outputDir, ...artifact.name.split("/"));
+        const relative = repoRelative(projectRoot, target);
+        if (!relative.startsWith("tmp/ty-context/context-exports/")) {
+            throw new Error("Source Pack artifacts must stay under tmp/ty-context/context-exports/**");
+        }
+        await ensureDir(path.dirname(target));
+        await writeTextIfChanged(target, artifact.content);
+    }
+}
+async function gitInfo(projectRoot) {
+    try {
+        const shaResult = await execFileAsync("git", ["-C", projectRoot, "rev-parse", "HEAD"], { encoding: "utf8" });
+        const dirtyResult = await execFileAsync("git", ["-C", projectRoot, "status", "--porcelain"], { encoding: "utf8" });
+        return { sha: shaResult.stdout.trim() || null, dirty: dirtyResult.stdout.trim().length > 0 };
+    }
+    catch {
+        return { sha: null, dirty: false };
+    }
+}
+export async function readPackageVersion() {
+    try {
+        const packageJson = JSON.parse(await fs.readFile(new URL("../../package.json", import.meta.url), "utf8"));
+        return packageJson.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist/lib/source-pack-records.d.ts

@@ -0,0 +1,11 @@
+import type { ContextAreaMapping, ContextArtifact, SourcePackRecord } from "./source-pack-types.js";
+export declare function collectCodeRecords(projectRoot: string, warnings: string[], options?: {
+    include?: string[];
+    exclude?: string[];
+    areas?: ContextAreaMapping[];
+}): Promise<SourcePackRecord[]>;
+export declare function collectContextArtifacts(projectRoot: string, warnings: string[], includePatterns?: string[]): Promise<ContextArtifact[]>;
+export declare function countRedactionWarnings(warnings: string[]): number;
+export declare function countLines(content: string): number;
+export declare function sha256(content: string): string;
+export declare function repoRelative(root: string, file: string): string;