project-tiny-context-harness 0.11.0 → 0.12.0

package/dist/lib/sync-engine.js

@@ -1,107 +1,53 @@
-import path from "node:path";
-import { promises as fs } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { readConfig } from "./config.js";
-import { harnessPath, harnessRoot } from "./harness-root.js";
-import { copyTree, listFiles, pathExists, readText, writeTextIfChanged, } from "./fs.js";
-import { AGENTS_BLOCK_MARKERS, GITHUB_WORKFLOW_BLOCK_END, GITHUB_WORKFLOW_BLOCK_MARKERS, GITHUB_WORKFLOW_BLOCK_START, MAKEFILE_BLOCK_END, MAKEFILE_BLOCK_MARKERS, MAKEFILE_BLOCK_START, MANAGED_BLOCK_END, MANAGED_BLOCK_START, } from "./managed-file.js";
+import { AGENTS_BLOCK_MARKERS, MANAGED_BLOCK_START, MANAGED_BLOCK_END, } from "./managed-file.js";
 import { packageAssetPath } from "./paths.js";
 import { assertSupportedSchema } from "./schema-guard.js";
-import { installLongTaskHooks, uninstallLongTaskHooks, } from "./long-task-hook-install.js";
-import { syncLongTaskCodexAgentProfile } from "./long-task-codex-agent-profile.js";
-import { enabledManagedSkillNames, isProfileEnabled } from "./profiles.js";
+import { captureMutationFileState } from "./context-mutation/mutation-file-state.js";
+import { assertNoUnfinishedContextMutation } from "./context-mutation/mutation-command-support.js";
+import { withMaintenanceLock } from "./maintenance-lock.js";
+import { writeMaintenanceText } from "./maintenance-write.js";
 export function emptySyncReport() {
-    return {
-        changed: [],
-        skipped: [],
-        blocked: [],
-    };
+    return { changed: [], skipped: [], blocked: [] };
 }
-export async function runSync(projectRoot) {
-    await assertSupportedSchema(projectRoot, "sync");
-    const root = await harnessRoot(projectRoot);
-    const config = await readConfig(projectRoot);
+export async function runSync(repository) {
+    await assertSupportedSchema(repository, "sync");
+    return withMaintenanceLock(repository, "sync", () => syncStartupInstructions(repository));
+}
+// Upgrade calls this while holding the same maintenance lock, after its own publication checks.
+export async function syncStartupInstructions(repository) {
+    await assertSupportedSchema(repository, "sync");
+    await assertNoUnfinishedContextMutation(repository);
+    const config = await readConfig(repository);
     const report = emptySyncReport();
-    await blockDeprecatedSkillOverrides(projectRoot, root, report);
-    if (report.blocked.length > 0) {
+    const unsupported = config.managed_files.filter((file) => file.path !== "AGENTS.md" || file.strategy !== "merge-block");
+    if (unsupported.length) {
+        report.blocked.push("Unsupported managed entries require explicit upgrade/review: " +
+            unsupported.map((x) => x.path).join(", "));
         return report;
     }
-    for (const managedFile of config.managed_files) {
-        await syncManagedFile(projectRoot, root, managedFile, report, config);
-    }
-    const longTaskEnabled = isProfileEnabled(config, "long-task");
-    await syncLongTaskCodexAgentProfile(projectRoot, root, longTaskEnabled, report);
-    if (longTaskEnabled) {
-        await installLongTaskHooks(projectRoot, report);
+    if (!config.managed_files.some((x) => x.path === "AGENTS.md")) {
+        report.notices = [
+            "Startup instructions are not managed by this configuration.",
+        ];
+        return report;
     }
-    else {
-        await uninstallLongTaskHooks(projectRoot, report);
+    const { before, content: next, blocked, } = await prepareStartupInstructions(repository);
+    report.blocked.push(...blocked);
+    if (next !== undefined) {
+        const changed = await writeMaintenanceText(repository, "AGENTS.md", next, before);
+        (changed ? report.changed : report.skipped).push("AGENTS.md");
     }
     return report;
 }
-async function syncManagedFile(projectRoot, root, managedFile, report, config) {
-    const destination = path.join(projectRoot, managedFile.path);
-    if (managedFile.path === "AGENTS.md") {
-        await syncAgentsBlock(destination, root, report);
-        return;
-    }
-    if (managedFile.path === "Makefile") {
-        await syncMakefileInclude(destination, root, report);
-        return;
-    }
-    if (isSkillsManagedPath(managedFile.path, root)) {
-        await syncSkillsTree(packageAssetPath("skills"), path.join(projectRoot, root, "skills"), report, enabledManagedSkillNames(config));
-        return;
-    }
-    const managedPath = normalizeManagedPath(managedFile.path);
-    if (managedPath === harnessPath(root, "ty-context-managed", "templates")) {
-        await syncTree(packageAssetPath("templates"), destination, report);
-        return;
-    }
-    if (managedPath === harnessPath(root, "ty-context-managed", "context_templates")) {
-        await syncTree(packageAssetPath("context_templates"), destination, report, {
-            prune: true,
-        });
-        return;
-    }
-    if (managedPath === harnessPath(root, "ty-context-managed", "policies")) {
-        await syncTree(packageAssetPath("policies"), destination, report);
-        return;
-    }
-    if (managedPath ===
-        harnessPath(root, "ty-context-managed", "make", "ty-context.mk")) {
-        await syncFile(packageAssetPath("make", "ty-context.mk"), destination, report, "skip-if-missing");
-        return;
-    }
-    if (managedFile.path === "tools") {
-        await syncTree(packageAssetPath("tools"), destination, report);
-        return;
-    }
-    if (managedFile.path === ".github/workflows/harness.yml") {
-        await syncGithubWorkflow(packageAssetPath("github", "harness.yml"), destination, managedFile.path, report);
-        return;
-    }
-    report.skipped.push(managedFile.path);
-}
-function isSkillsManagedPath(managedPath, root) {
-    const normalized = normalizeManagedPath(managedPath);
-    return (normalized === harnessPath(root, "skills") ||
-        normalized === ".harness/agents/skills" ||
-        (normalized === ".agents/skills" && root !== ".agents"));
-}
-function normalizeManagedPath(managedPath) {
-    return managedPath.replace(/\\/g, "/");
-}
-async function syncAgentsBlock(destination, root, report) {
-    const corePath = packageAssetPath("agents", "AGENTS_CORE.md");
-    if (!(await pathExists(corePath))) {
-        report.skipped.push("AGENTS.md");
-        return;
-    }
-    const core = renderAgentsCore(await readText(corePath), root);
-    const block = `${MANAGED_BLOCK_START}\n${core.trim()}\n${MANAGED_BLOCK_END}`;
-    const existing = (await pathExists(destination))
-        ? await readText(destination)
+export async function prepareStartupInstructions(repository) {
+    const report = emptySyncReport();
+    const before = await captureMutationFileState(repository, "AGENTS.md");
+    const existing = before.bytes_base64
+        ? Buffer.from(before.bytes_base64, "base64").toString("utf8")
         : "";
+    const core = await readFile(packageAssetPath("agents", "AGENTS_CORE.md"), "utf8");
+    const block = MANAGED_BLOCK_START + "\n" + core.trim() + "\n" + MANAGED_BLOCK_END;
     const next = mergeManagedBlock({
         existing,
         block,
@@ -110,67 +56,7 @@ async function syncAgentsBlock(destination, root, report) {
         insert: "append",
         report,
     });
-    if (!next) {
-        return;
-    }
-    if (await writeTextIfChanged(destination, next)) {
-        report.changed.push("AGENTS.md");
-    }
-    else {
-        report.skipped.push("AGENTS.md");
-    }
-}
-function renderAgentsCore(content, root) {
-    return content.replaceAll(".agent", root).replaceAll(".codex", root);
-}
-async function syncMakefileInclude(destination, root, report) {
-    const existing = (await pathExists(destination))
-        ? await readText(destination)
-        : "";
-    const resetDefaultGoal = shouldResetMakeDefaultGoal(existing);
-    const includePath = `${root.replace(/\\/g, "/")}/ty-context-managed/make/ty-context.mk`;
-    const blockLines = [
-        MAKEFILE_BLOCK_START,
-        "# Included before project targets so project recipes win on name conflicts.",
-        `-include ${includePath}`,
-        MAKEFILE_BLOCK_END,
-    ];
-    if (resetDefaultGoal) {
-        blockLines.splice(3, 0, ".DEFAULT_GOAL :=");
-    }
-    const block = blockLines.join("\n");
-    const next = mergeManagedBlock({
-        existing,
-        block,
-        markers: MAKEFILE_BLOCK_MARKERS,
-        pathLabel: "Makefile",
-        insert: "prepend",
-        report,
-    });
-    if (!next) {
-        return;
-    }
-    if (await writeTextIfChanged(destination, next)) {
-        report.changed.push("Makefile");
-    }
-    else {
-        report.skipped.push("Makefile");
-    }
-}
-function shouldResetMakeDefaultGoal(existing) {
-    if (!existing.trim()) {
-        return false;
-    }
-    const block = findManagedBlock(existing, MAKEFILE_BLOCK_MARKERS);
-    if (block.status === "missing") {
-        return true;
-    }
-    if (block.status === "invalid") {
-        return false;
-    }
-    const before = existing.slice(0, block.startIndex);
-    const after = existing.slice(block.endIndex + block.markers.end.length);
-    return !before.trim() && Boolean(after.trim());
+    return { before, content: next, blocked: report.blocked };
 }
 function mergeManagedBlock(options) {
     const { existing, block, markers, pathLabel, insert, report } = options;
@@ -221,187 +107,3 @@ function findManagedBlock(existing, markersList) {
         ? { status: "found", ...matches[0] }
         : { status: "missing" };
 }
-async function syncTree(source, destination, report, options = {}) {
-    if (!(await pathExists(source))) {
-        report.skipped.push(path.basename(destination));
-        return;
-    }
-    const files = await listFiles(source);
-    const realFiles = files.filter((file) => !file.endsWith(".gitkeep"));
-    if (realFiles.length === 0) {
-        report.skipped.push(path.basename(destination));
-        return;
-    }
-    const changed = await copyTree(source, destination, { skipGitkeep: true });
-    if (options.prune) {
-        changed.push(...(await removeStaleManagedFiles(source, destination)));
-    }
-    report.changed.push(...changed);
-}
-async function removeStaleManagedFiles(source, destination) {
-    if (!(await pathExists(destination))) {
-        return [];
-    }
-    const sourceFiles = new Set((await listFiles(source))
-        .filter((file) => !file.endsWith(".gitkeep"))
-        .map((file) => path.relative(source, file).split(path.sep).join("/")));
-    const removed = [];
-    for (const destinationFile of await listFiles(destination)) {
-        const relative = path
-            .relative(destination, destinationFile)
-            .split(path.sep)
-            .join("/");
-        if (sourceFiles.has(relative)) {
-            continue;
-        }
-        await fs.rm(destinationFile, { force: true });
-        removed.push(destinationFile);
-    }
-    return removed;
-}
-async function syncSkillsTree(source, destination, report, enabledSkillNames) {
-    if (!(await pathExists(source))) {
-        report.skipped.push(path.basename(destination));
-        return;
-    }
-    const files = await listFiles(source);
-    const allManagedSkillNames = new Set(files
-        .map((file) => path.relative(source, file).split(path.sep)[0])
-        .filter(Boolean));
-    const realFiles = files
-        .filter((file) => !file.endsWith(".gitkeep"))
-        .filter((file) => enabledSkillNames.has(path.relative(source, file).split(path.sep)[0]));
-    if (realFiles.length === 0) {
-        report.skipped.push(path.basename(destination));
-        return;
-    }
-    for (const file of realFiles) {
-        const relative = path.relative(source, file);
-        const destinationFile = path.join(destination, relative);
-        if (await writeTextIfChanged(destinationFile, await readText(file))) {
-            report.changed.push(destinationFile);
-        }
-        else {
-            report.skipped.push(destinationFile);
-        }
-    }
-    const managedSkillNames = new Set(realFiles
-        .map((file) => path.relative(source, file).split(path.sep)[0])
-        .filter(Boolean));
-    for (const skillName of managedSkillNames) {
-        report.changed.push(...(await removeStaleManagedFiles(path.join(source, skillName), path.join(destination, skillName))));
-    }
-    for (const skillName of allManagedSkillNames) {
-        if (enabledSkillNames.has(skillName))
-            continue;
-        const disabled = path.join(destination, skillName);
-        if (!(await pathExists(disabled)))
-            continue;
-        await fs.rm(disabled, { recursive: true, force: true });
-        report.changed.push(disabled);
-    }
-}
-async function blockDeprecatedSkillOverrides(projectRoot, root, report) {
-    for (const overrideRoot of skillOverrideRoots(projectRoot, root)) {
-        if (!(await pathExists(overrideRoot.absolute))) {
-            continue;
-        }
-        const deprecatedFiles = (await listFiles(overrideRoot.absolute))
-            .filter((file) => path.basename(file) !== ".gitkeep")
-            .map((file) => path.relative(overrideRoot.absolute, file).split(path.sep).join("/"))
-            .sort();
-        if (deprecatedFiles.length === 0) {
-            continue;
-        }
-        report.blocked.push(`${overrideRoot.relative}: deprecated Skill overrides block sync because package-managed default Skills are overwritten during managed asset refresh. Move these rules into a separate project-local Skill such as ${root.replace(/\\/g, "/")}/skills/product_plan/SKILL.md, ${root.replace(/\\/g, "/")}/skills/uiux_design/SKILL.md or ${root.replace(/\\/g, "/")}/skills/development_engineer/SKILL.md. Deprecated files: ${deprecatedFiles.join(", ")}`);
-    }
-}
-function skillOverrideRoots(projectRoot, root) {
-    return [
-        {
-            absolute: path.join(projectRoot, root, "ty-context-managed", "override_skills"),
-            relative: path
-                .join(root, "ty-context-managed", "override_skills")
-                .split(path.sep)
-                .join("/"),
-        },
-        {
-            absolute: path.join(projectRoot, root, "pjsdlc_managed", "override_skills"),
-            relative: path
-                .join(root, "pjsdlc_managed", "override_skills")
-                .split(path.sep)
-                .join("/"),
-        },
-    ];
-}
-async function syncFile(source, destination, report, missingMode) {
-    if (!(await pathExists(source))) {
-        if (missingMode === "block-if-missing") {
-            report.blocked.push(source);
-        }
-        else {
-            report.skipped.push(destination);
-        }
-        return;
-    }
-    if (await writeTextIfChanged(destination, await readText(source))) {
-        report.changed.push(destination);
-    }
-    else {
-        report.skipped.push(destination);
-    }
-}
-async function syncGithubWorkflow(source, destination, relativePath, report) {
-    if (!(await pathExists(source))) {
-        report.skipped.push(relativePath);
-        return;
-    }
-    const sourceContent = await readText(source);
-    if (!(await pathExists(destination))) {
-        if (await writeTextIfChanged(destination, sourceContent)) {
-            report.changed.push(relativePath);
-        }
-        else {
-            report.skipped.push(relativePath);
-        }
-        return;
-    }
-    const existing = await readText(destination);
-    const markerState = workflowMarkerState(existing);
-    if (markerState === "invalid") {
-        report.blocked.push(`${relativePath}: incomplete managed workflow markers`);
-        return;
-    }
-    if (markerState === "managed" ||
-        normalizeWorkflow(existing) ===
-            normalizeWorkflow(stripWorkflowMarkers(sourceContent))) {
-        if (await writeTextIfChanged(destination, sourceContent)) {
-            report.changed.push(relativePath);
-        }
-        else {
-            report.skipped.push(relativePath);
-        }
-        return;
-    }
-    report.skipped.push(`${relativePath}: customized`);
-}
-function workflowMarkerState(content) {
-    const found = findManagedBlock(content, GITHUB_WORKFLOW_BLOCK_MARKERS);
-    if (found.status === "missing") {
-        return "missing";
-    }
-    if (found.status === "invalid") {
-        return "invalid";
-    }
-    return "managed";
-}
-function stripWorkflowMarkers(content) {
-    return content
-        .split(/\r?\n/)
-        .filter((line) => line.trim() !== GITHUB_WORKFLOW_BLOCK_START &&
-        line.trim() !== GITHUB_WORKFLOW_BLOCK_END)
-        .join("\n");
-}
-function normalizeWorkflow(content) {
-    return content.replace(/\r\n/g, "\n").trim();
-}

package/dist/lib/types.d.ts

@@ -3,28 +3,9 @@ export interface HarnessConfig {
         package: string;
         schema_version: string;
     };
-    profiles: {
-        enabled: HarnessProfile[];
-    };
-    modularity?: HarnessModularityConfig;
     managed_files: ManagedFile[];
     never_overwrite: string[];
 }
-export type HarnessProfile = "core-portable" | "workflow-default" | "long-task";
-export interface HarnessModularityConfig {
-    limit?: number;
-    policy?: "scoped_waivers" | "strict_except_generated";
-    waivers?: ModularityWaiverConfig[];
-}
-export interface ModularityWaiverConfig {
-    path?: string;
-    category?: string;
-    owner?: string;
-    introduced_at?: string;
-    reason?: string;
-    tracking_issue?: string;
-    expiry_condition?: string;
-}
 export interface ManagedFile {
     path: string;
     strategy: "merge-block" | "generated" | "generated-compat" | "managed" | "merge-with-local" | "create-if-missing";

package/dist/lib/upgrade.d.ts

@@ -1,3 +1,4 @@
+import { type RetirementRunOptions } from "./retirement-runner.js";
 export interface UpgradeRunReport {
     lines: string[];
     blocked: boolean;
@@ -6,5 +7,5 @@ export declare class UpgradeBlockedError extends Error {
     readonly lines: string[];
     constructor(lines: string[]);
 }
-export declare function runUpgrade(projectRoot: string): Promise<string[]>;
-export declare function runUpgradeReport(projectRoot: string): Promise<UpgradeRunReport>;
+export declare function runUpgrade(repository: string, options?: RetirementRunOptions): Promise<string[]>;
+export declare function runUpgradeReport(repository: string, options?: RetirementRunOptions): Promise<UpgradeRunReport>;

package/dist/lib/upgrade.js

@@ -1,53 +1,43 @@
-import { runDoctor } from "./doctor.js";
-import { createUpgradePlan, formatUpgradePlan, runMigrations, } from "./migrations.js";
-import { assertSupportedSchema } from "./schema-guard.js";
+import { assertSupportedSchema, rawSchemaVersion } from "./schema-guard.js";
+import { runSchema5Retirement, readRetirementJournal, } from "./retirement-runner.js";
 import { runSync } from "./sync-engine.js";
 export class UpgradeBlockedError extends Error {
     lines;
     constructor(lines) {
-        super("upgrade completed with blockers");
+        super("upgrade blocked; no success is claimed");
         this.lines = lines;
     }
 }
-export async function runUpgrade(projectRoot) {
-    const report = await runUpgradeReport(projectRoot);
-    if (report.blocked) {
+export async function runUpgrade(repository, options = {}) {
+    const report = await runUpgradeReport(repository, options);
+    if (report.blocked)
         throw new UpgradeBlockedError(report.lines);
-    }
     return report.lines;
 }
-export async function runUpgradeReport(projectRoot) {
-    const lines = [];
-    await assertSupportedSchema(projectRoot, "upgrade");
-    const plan = await createUpgradePlan(projectRoot);
-    if (plan.blocked.length > 0) {
-        lines.push(...formatUpgradePlan(plan));
-        lines.push("upgrade blocked: resolve blocked migration items before applying safe migrations or sync.");
-        const doctor = await runDoctor(projectRoot);
-        lines.push(`doctor warnings=${doctor.warnings.length} errors=${doctor.errors.length}`);
-        return { lines, blocked: true };
-    }
-    const migrationReport = await runMigrations(projectRoot, plan);
-    lines.push(`migrations changed=${migrationReport.changed.length} skipped=${migrationReport.skipped.length} manual_required=${migrationReport.manualRequired.length} blocked=${migrationReport.blocked.length}`);
-    if (migrationReport.manualRequired.length > 0 ||
-        migrationReport.blocked.length > 0) {
-        lines.push(...formatUpgradePlan({
-            safe_pending: [],
-            manual_required: migrationReport.manualRequired,
-            blocked: migrationReport.blocked,
-        }).slice(1));
+export async function runUpgradeReport(repository, options = {}) {
+    try {
+        await assertSupportedSchema(repository, "upgrade");
+        if ((await rawSchemaVersion(repository)) === "5" &&
+            !(await readRetirementJournal(repository))) {
+            const report = await runSync(repository);
+            return {
+                lines: [
+                    "Schema 5 already installed.",
+                    ...report.blocked,
+                    ...(report.notices ?? []),
+                ],
+                blocked: report.blocked.length > 0,
+            };
+        }
+        return await runSchema5Retirement(repository, options);
     }
-    const syncReport = await runSync(projectRoot);
-    lines.push(`sync changed=${syncReport.changed.length} skipped=${syncReport.skipped.length} blocked=${syncReport.blocked.length}`);
-    for (const skipped of syncReport.skipped.filter((line) => line.includes("customized"))) {
-        lines.push(`sync skipped: ${skipped}`);
+    catch (error) {
+        return {
+            lines: [
+                String(error),
+                "Upgrade stopped. Retained backups and pending migration state must be resolved before ordinary writes; sync was not continued.",
+            ],
+            blocked: true,
+        };
     }
-    lines.push(...(syncReport.notices ?? []));
-    const doctor = await runDoctor(projectRoot);
-    lines.push(`doctor warnings=${doctor.warnings.length} errors=${doctor.errors.length}`);
-    const blocked = migrationReport.manualRequired.length > 0 ||
-        migrationReport.blocked.length > 0 ||
-        syncReport.blocked.length > 0 ||
-        doctor.errors.length > 0;
-    return { lines, blocked };
 }

package/dist/lib/validators.d.ts

@@ -5,6 +5,6 @@ export interface ValidatorReport {
     hygiene?: string[];
     errors: string[];
 }
-export declare function runValidator(projectRoot: string, gate: string, args?: string[]): Promise<ValidatorReport>;
-export declare function validateContextContentForRole(projectRoot: string, file: string, content: string, role: ContextRole): string[];
-export declare function validateContextRegistrationContent(projectRoot: string, file: string, content: string, role: ContextRole, readPolicy: string): string[];
+export declare function runValidator(projectRoot: string, name: string, _args?: string[]): Promise<ValidatorReport>;
+export declare function validateContextContentForRole(_root: string, file: string, content: string, _role: ContextRole): string[];
+export declare function validateContextRegistrationContent(root: string, file: string, content: string, role: ContextRole, readPolicy?: string): string[];