project-tiny-context-harness 0.2.39

package/dist/lib/sync-engine.js

@@ -0,0 +1,350 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+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_START, MAKEFILE_BLOCK_END, MAKEFILE_BLOCK_MARKERS, MAKEFILE_BLOCK_START, MANAGED_BLOCK_END, MANAGED_BLOCK_START } from "./managed-file.js";
+import { packageAssetPath } from "./paths.js";
+import { assertSupportedSchema } from "./schema-guard.js";
+export function emptySyncReport() {
+    return {
+        changed: [],
+        skipped: [],
+        blocked: []
+    };
+}
+export async function runSync(projectRoot) {
+    await assertSupportedSchema(projectRoot, "sync");
+    const root = await harnessRoot(projectRoot);
+    const config = await readConfig(projectRoot);
+    const report = emptySyncReport();
+    await blockDeprecatedSkillOverrides(projectRoot, root, report);
+    if (report.blocked.length > 0) {
+        return report;
+    }
+    for (const managedFile of config.managed_files) {
+        await syncManagedFile(projectRoot, root, managedFile, report);
+    }
+    return report;
+}
+async function syncManagedFile(projectRoot, root, managedFile, report) {
+    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);
+        return;
+    }
+    const managedPath = normalizeManagedPath(managedFile.path);
+    if (managedPath === harnessPath(root, "pjsdlc_managed", "templates")) {
+        await syncTree(packageAssetPath("templates"), destination, report);
+        return;
+    }
+    if (managedPath === harnessPath(root, "pjsdlc_managed", "context_templates")) {
+        await syncTree(packageAssetPath("context_templates"), destination, report, { prune: true });
+        return;
+    }
+    if (managedPath === harnessPath(root, "pjsdlc_managed", "policies")) {
+        await syncTree(packageAssetPath("policies"), destination, report);
+        return;
+    }
+    if (managedPath === harnessPath(root, "pjsdlc_managed", "make", "sdlc-harness.mk")) {
+        await syncFile(packageAssetPath("make", "sdlc-harness.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) : "";
+    const next = mergeManagedBlock({
+        existing,
+        block,
+        markers: AGENTS_BLOCK_MARKERS,
+        pathLabel: "AGENTS.md",
+        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, "/")}/pjsdlc_managed/make/sdlc-harness.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());
+}
+function mergeManagedBlock(options) {
+    const { existing, block, markers, pathLabel, insert, report } = options;
+    const found = findManagedBlock(existing, markers);
+    if (found.status === "invalid") {
+        report.blocked.push(`${pathLabel}: ${found.reason}`);
+        return undefined;
+    }
+    if (found.status === "found") {
+        const before = existing.slice(0, found.startIndex);
+        const after = existing.slice(found.endIndex + found.markers.end.length);
+        return `${before}${block}${after}`;
+    }
+    if (!existing.trim()) {
+        return `${block}\n`;
+    }
+    if (insert === "prepend") {
+        return `${block}\n\n${existing}`;
+    }
+    return `${existing.trimEnd()}\n\n${block}\n`;
+}
+function findManagedBlock(existing, markersList) {
+    const matches = [];
+    for (const markers of markersList) {
+        const startIndex = existing.indexOf(markers.start);
+        const endIndex = existing.indexOf(markers.end);
+        const hasStart = startIndex >= 0;
+        const hasEnd = endIndex >= 0;
+        if (!hasStart && !hasEnd) {
+            continue;
+        }
+        if (hasStart !== hasEnd || endIndex < startIndex) {
+            return { status: "invalid", reason: "incomplete managed block markers" };
+        }
+        if (existing.indexOf(markers.start, startIndex + markers.start.length) >= 0 ||
+            existing.indexOf(markers.end, endIndex + markers.end.length) >= 0) {
+            return { status: "invalid", reason: "duplicate managed block markers" };
+        }
+        matches.push({ markers, startIndex, endIndex });
+    }
+    if (matches.length > 1) {
+        return { status: "invalid", reason: "conflicting managed block marker namespaces" };
+    }
+    return matches[0] ? { 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) {
+    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;
+    }
+    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);
+        }
+    }
+}
+async function blockDeprecatedSkillOverrides(projectRoot, root, report) {
+    const overrideRoot = skillOverrideRoot(projectRoot, root);
+    if (!(await pathExists(overrideRoot))) {
+        return;
+    }
+    const deprecatedFiles = (await listFiles(overrideRoot))
+        .filter((file) => path.basename(file) !== ".gitkeep")
+        .map((file) => path.relative(overrideRoot, file).split(path.sep).join("/"))
+        .sort();
+    if (deprecatedFiles.length === 0) {
+        return;
+    }
+    const relativeRoot = path.join(root, "pjsdlc_managed", "override_skills").split(path.sep).join("/");
+    report.blocked.push(`${relativeRoot}: Skill overrides are no longer supported. 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 skillOverrideRoot(projectRoot, root) {
+    return path.join(projectRoot, root, "pjsdlc_managed", "override_skills");
+}
+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 startIndex = content.indexOf(GITHUB_WORKFLOW_BLOCK_START);
+    const endIndex = content.indexOf(GITHUB_WORKFLOW_BLOCK_END);
+    const hasStart = startIndex >= 0;
+    const hasEnd = endIndex >= 0;
+    if (!hasStart && !hasEnd) {
+        return "missing";
+    }
+    if (hasStart !== hasEnd || endIndex < startIndex) {
+        return "invalid";
+    }
+    if (content.indexOf(GITHUB_WORKFLOW_BLOCK_START, startIndex + GITHUB_WORKFLOW_BLOCK_START.length) >= 0 ||
+        content.indexOf(GITHUB_WORKFLOW_BLOCK_END, endIndex + GITHUB_WORKFLOW_BLOCK_END.length) >= 0) {
+        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

@@ -0,0 +1,21 @@
+export interface HarnessConfig {
+    core: {
+        package: string;
+        schema_version: string;
+    };
+    managed_files: ManagedFile[];
+    never_overwrite: string[];
+}
+export interface ManagedFile {
+    path: string;
+    strategy: "merge-block" | "generated" | "generated-compat" | "managed" | "merge-with-local" | "create-if-missing";
+}
+export interface SourceMapping {
+    source: string;
+    target: string;
+    exclude?: string[];
+    mode: "extract-managed-block" | "copy-tree" | "copy-file" | "extract-harness-targets";
+}
+export interface SourceMappingsFile {
+    source_mappings: SourceMapping[];
+}

package/dist/lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/upgrade.d.ts

@@ -0,0 +1 @@
+export declare function runUpgrade(projectRoot: string): Promise<string[]>;

package/dist/lib/upgrade.js

@@ -0,0 +1,21 @@
+import { runDoctor } from "./doctor.js";
+import { runMigrations } from "./migrations.js";
+import { assertSupportedSchema } from "./schema-guard.js";
+import { runSync } from "./sync-engine.js";
+export async function runUpgrade(projectRoot) {
+    const lines = [];
+    await assertSupportedSchema(projectRoot, "upgrade");
+    const migrationReport = await runMigrations(projectRoot);
+    lines.push(`migrations changed=${migrationReport.changed.length} skipped=${migrationReport.skipped.length}`);
+    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}`);
+    }
+    const doctor = await runDoctor(projectRoot);
+    lines.push(`doctor warnings=${doctor.warnings.length} errors=${doctor.errors.length}`);
+    if (syncReport.blocked.length > 0 || doctor.errors.length > 0) {
+        throw new Error("upgrade completed with blockers");
+    }
+    return lines;
+}

package/dist/lib/validators.d.ts

@@ -0,0 +1,5 @@
+export interface ValidatorReport {
+    info: string[];
+    errors: string[];
+}
+export declare function runValidator(projectRoot: string, gate: string): Promise<ValidatorReport>;