agent-project-sdlc 0.1.0

package/dist/lib/harness-root.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+import { DEFAULT_HARNESS_ROOT, HARNESS_JSON_CONFIG_PATH } from "./paths.js";
+import { pathExists, readText } from "./fs.js";
+export async function readHarnessRootConfig(projectRoot) {
+    const explicitConfig = await readJsonConfig(path.join(projectRoot, HARNESS_JSON_CONFIG_PATH));
+    const explicitValue = folderNameFromObject(explicitConfig);
+    if (explicitValue) {
+        return { harnessFolderName: normalizeHarnessFolderName(explicitValue), source: HARNESS_JSON_CONFIG_PATH };
+    }
+    const packageJson = await readJsonConfig(path.join(projectRoot, "package.json"));
+    const packageConfig = packageJson && typeof packageJson === "object" ? packageJson.sdlcHarness : undefined;
+    const packageValue = folderNameFromObject(packageConfig);
+    if (packageValue) {
+        return { harnessFolderName: normalizeHarnessFolderName(packageValue), source: "package.json#sdlcHarness" };
+    }
+    return { harnessFolderName: DEFAULT_HARNESS_ROOT, source: "default" };
+}
+export async function harnessRoot(projectRoot) {
+    return (await readHarnessRootConfig(projectRoot)).harnessFolderName;
+}
+export async function harnessConfigPath(projectRoot) {
+    return path.join(await harnessRoot(projectRoot), "config.yaml");
+}
+export function harnessPath(root, ...segments) {
+    return path.join(root, ...segments);
+}
+function folderNameFromObject(value) {
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    const record = value;
+    const folderName = record.harnessFolderName ?? record.harnessFloderName;
+    return typeof folderName === "string" && folderName.trim() ? folderName : undefined;
+}
+async function readJsonConfig(filePath) {
+    if (!(await pathExists(filePath))) {
+        return undefined;
+    }
+    return JSON.parse(await readText(filePath));
+}
+export function normalizeHarnessFolderName(value) {
+    const normalized = value.trim().replace(/\\/g, "/").replace(/\/+$/, "");
+    if (!normalized || normalized === "." || normalized === "..") {
+        throw new Error("harnessFolderName must be a non-empty relative directory");
+    }
+    if (path.isAbsolute(normalized) || normalized.includes("..")) {
+        throw new Error("harnessFolderName must not be absolute or contain '..'");
+    }
+    return normalized;
+}

package/dist/lib/init.d.ts

@@ -0,0 +1,5 @@
+export interface InitOptions {
+    adopt: boolean;
+    force: boolean;
+}
+export declare function runInit(projectRoot: string, options: InitOptions): Promise<string[]>;

package/dist/lib/init.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { writeConfigIfMissing } from "./config.js";
+import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
+import { ensureDir, pathExists, writeTextIfChanged } from "./fs.js";
+import { runSync } from "./sync-engine.js";
+const DOC_DIRS = [
+    ".docs/00_raw",
+    ".docs/01_product",
+    ".docs/02_architecture",
+    ".docs/03_tech_plan",
+    ".docs/04_implementation",
+    ".docs/05_decisions",
+    ".docs/06_review",
+    ".docs/07_test",
+    ".docs/08_release",
+    ".docs/rfc"
+];
+export async function runInit(projectRoot, options) {
+    const report = [];
+    const existingEntries = await projectHasExistingFiles(projectRoot);
+    if (existingEntries && !options.adopt && !options.force) {
+        report.push("Project is not empty; continuing with non-destructive init. Use --adopt to mark this as an existing project adoption.");
+    }
+    const root = await harnessRoot(projectRoot);
+    const configPath = await harnessConfigPath(projectRoot);
+    if (await writeConfigIfMissing(projectRoot)) {
+        report.push(`created ${configPath}`);
+    }
+    else {
+        report.push(`kept existing ${configPath}`);
+    }
+    await createProjectState(projectRoot, root, report);
+    await createDocs(projectRoot, report);
+    const syncReport = await runSync(projectRoot);
+    report.push(`sync changed=${syncReport.changed.length} skipped=${syncReport.skipped.length} blocked=${syncReport.blocked.length}`);
+    report.push(options.adopt ? "adopt mode complete" : "init complete");
+    return report;
+}
+async function projectHasExistingFiles(projectRoot) {
+    const markers = ["README.md", "src", "pyproject.toml", "go.mod"];
+    for (const marker of markers) {
+        if (await pathExists(path.join(projectRoot, marker))) {
+            return true;
+        }
+    }
+    return false;
+}
+async function createProjectState(projectRoot, root, report) {
+    const stateRoot = path.join(projectRoot, root, "state");
+    await ensureDir(stateRoot);
+    const files = [
+        [
+            harnessPath(root, "state", "lifecycle.yaml"),
+            `project_name: "Project"\nversion: "v0.1"\ncurrent_phase: "REQUIREMENT_GATHERING"\nactive_role: "pm"\nactive_skill: "pm_prd"\ncurrent_milestone: "MVP"\nblocked_reason: ""\nsuspended_phase: ""\nallowed_next_phases:\n  - "ARCHITECTING"\nhistory: []\n`
+        ],
+        [harnessPath(root, "state", "plan.yaml"), `current_phase: "SPRINTING"\ncurrent_task_id: ""\ntasks: []\n`],
+        [harnessPath(root, "state", "plan.draft.yaml"), `current_phase: "SPRINTING"\ncurrent_task_id: ""\ntasks: []\n`],
+        [harnessPath(root, "state", "gate_results.log"), "# Gate results are appended by sdlc-harness.\n"],
+        [harnessPath(root, "state", "memory.md"), "# Project Memory\n\n短期执行计划写入 plan.yaml；长期稳定知识简短记录在这里，并链接到 `.docs/` 正式出处。\n"]
+    ];
+    for (const [relative, content] of files) {
+        if (await writeTextIfChanged(path.join(projectRoot, relative), content)) {
+            report.push(`created ${relative}`);
+        }
+    }
+}
+async function createDocs(projectRoot, report) {
+    for (const dir of DOC_DIRS) {
+        await ensureDir(path.join(projectRoot, dir));
+        await writeTextIfChanged(path.join(projectRoot, dir, ".gitkeep"), "");
+    }
+    const index = ".docs/INDEX.md";
+    if (await writeTextIfChanged(path.join(projectRoot, index), "# Documentation Index\n\n本文件是 AI SDLC Harness 的文档路由表。\n")) {
+        report.push(`created ${index}`);
+    }
+}

package/dist/lib/managed-file.d.ts

@@ -0,0 +1,6 @@
+export declare const MANAGED_BLOCK_START = "<!-- sdlc-harness:begin -->";
+export declare const MANAGED_BLOCK_END = "<!-- sdlc-harness:end -->";
+export declare const MAKEFILE_BLOCK_START = "# sdlc-harness:make:begin";
+export declare const MAKEFILE_BLOCK_END = "# sdlc-harness:make:end";
+export declare const MANAGED_METADATA_START = "<!-- sdlc-harness-managed";
+export declare const MANAGED_METADATA_END = "-->";

package/dist/lib/managed-file.js

@@ -0,0 +1,6 @@
+export const MANAGED_BLOCK_START = "<!-- sdlc-harness:begin -->";
+export const MANAGED_BLOCK_END = "<!-- sdlc-harness:end -->";
+export const MAKEFILE_BLOCK_START = "# sdlc-harness:make:begin";
+export const MAKEFILE_BLOCK_END = "# sdlc-harness:make:end";
+export const MANAGED_METADATA_START = "<!-- sdlc-harness-managed";
+export const MANAGED_METADATA_END = "-->";

package/dist/lib/migrations.d.ts

@@ -0,0 +1,12 @@
+export declare const CURRENT_SCHEMA_VERSION = "1";
+export interface Migration {
+    from: string;
+    to: string;
+    description: string;
+}
+export declare const migrations: Migration[];
+export interface MigrationReport {
+    changed: string[];
+    skipped: string[];
+}
+export declare function runMigrations(projectRoot: string): Promise<MigrationReport>;

package/dist/lib/migrations.js

@@ -0,0 +1,176 @@
+import path from "node:path";
+import { rm } from "node:fs/promises";
+import { readConfig } from "./config.js";
+import { pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { harnessConfigPath, harnessPath, harnessRoot } from "./harness-root.js";
+import { parseYaml, stringifyYaml } from "./yaml.js";
+export const CURRENT_SCHEMA_VERSION = "1";
+export const migrations = [];
+export async function runMigrations(projectRoot) {
+    const report = { changed: [], skipped: [] };
+    const root = await harnessRoot(projectRoot);
+    await migrateConfig(projectRoot, root, report);
+    await migratePlan(projectRoot, root, report, "plan.yaml", "tasks.yaml");
+    await migratePlan(projectRoot, root, report, "plan.draft.yaml", "tasks.draft.yaml");
+    await removeLegacyCheckpoints(projectRoot, root, report);
+    await ensureMemory(projectRoot, root, report);
+    return report;
+}
+async function migrateConfig(projectRoot, root, report) {
+    const relativeConfigPath = await harnessConfigPath(projectRoot);
+    const configPath = path.join(projectRoot, relativeConfigPath);
+    if (!(await pathExists(configPath))) {
+        report.skipped.push(relativeConfigPath);
+        return;
+    }
+    const config = await readConfig(projectRoot);
+    config.core.schema_version = CURRENT_SCHEMA_VERSION;
+    config.managed_files = migrateManagedFiles(config.managed_files, root);
+    config.local_overrides = config.local_overrides.map((item) => item === ".harness/policies/*.local.yaml" ? harnessPath(root, "managed", "policies", "*.local.yaml") : item);
+    if (await writeTextIfChanged(configPath, stringifyYaml(config))) {
+        report.changed.push(relativeConfigPath);
+    }
+    else {
+        report.skipped.push(relativeConfigPath);
+    }
+}
+function migrateManagedFiles(managedFiles, root) {
+    const migrated = [];
+    const seen = new Set();
+    const push = (item) => {
+        if (seen.has(item.path)) {
+            return;
+        }
+        seen.add(item.path);
+        migrated.push(item);
+    };
+    for (const item of managedFiles) {
+        if (item.path === ".agents/skills" || item.path === ".harness/agents/skills") {
+            push({ path: harnessPath(root, "skills"), strategy: "managed" });
+            continue;
+        }
+        if (item.path === ".harness/templates") {
+            push({ path: harnessPath(root, "managed", "templates"), strategy: "managed" });
+            continue;
+        }
+        if (item.path === ".harness/policies") {
+            push({ path: harnessPath(root, "managed", "policies"), strategy: "merge-with-local" });
+            continue;
+        }
+        if (item.path === ".harness/make/sdlc-harness.mk") {
+            push({ path: harnessPath(root, "managed", "make", "sdlc-harness.mk"), strategy: "managed" });
+            continue;
+        }
+        push(item);
+    }
+    if (!seen.has("Makefile")) {
+        const agentsIndex = migrated.findIndex((item) => item.path === "AGENTS.md");
+        const makefileEntry = { path: "Makefile", strategy: "merge-block" };
+        if (agentsIndex >= 0) {
+            migrated.splice(agentsIndex + 1, 0, makefileEntry);
+        }
+        else {
+            migrated.unshift(makefileEntry);
+        }
+    }
+    return migrated;
+}
+async function migratePlan(projectRoot, root, report, planFileName, legacyFileName) {
+    const relativePlanPath = harnessPath(root, "state", planFileName);
+    const planPath = path.join(projectRoot, relativePlanPath);
+    const legacyTasksPath = path.join(projectRoot, harnessPath(root, "state", legacyFileName));
+    const sourcePath = (await pathExists(planPath)) ? planPath : legacyTasksPath;
+    if (!(await pathExists(sourcePath))) {
+        report.skipped.push(relativePlanPath);
+        return;
+    }
+    const data = (parseYaml(await readText(sourcePath)) ?? {});
+    let changed = false;
+    if (!("current_phase" in data)) {
+        data.current_phase = "SPRINTING";
+        changed = true;
+    }
+    if (!("current_task_id" in data)) {
+        data.current_task_id = "";
+        changed = true;
+    }
+    if (!Array.isArray(data.tasks)) {
+        data.tasks = [];
+        changed = true;
+    }
+    if (Array.isArray(data.tasks)) {
+        for (const task of data.tasks) {
+            if (!isRecord(task))
+                continue;
+            if ("checkpoint" in task) {
+                const checkpoint = String(task.checkpoint ?? "");
+                if (isOpenTask(task) && checkpoint) {
+                    const contract = await readLegacyCheckpointContract(projectRoot, root, checkpoint);
+                    for (const field of ["allowed_paths", "required_gates", "acceptance_criteria"]) {
+                        if (!(field in task) && Array.isArray(contract[field])) {
+                            task[field] = contract[field];
+                        }
+                    }
+                }
+                delete task.checkpoint;
+                changed = true;
+            }
+        }
+    }
+    if (changed || sourcePath !== planPath) {
+        if (await writeTextIfChanged(planPath, stringifyYaml(data))) {
+            report.changed.push(relativePlanPath);
+        }
+        else {
+            report.skipped.push(relativePlanPath);
+        }
+        if (sourcePath !== planPath) {
+            await rm(sourcePath, { force: true });
+            report.changed.push(path.relative(projectRoot, sourcePath));
+        }
+    }
+    else {
+        report.skipped.push(relativePlanPath);
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isOpenTask(task) {
+    return ["pending", "in_progress", "blocked", "pending_revision"].includes(String(task.status));
+}
+async function readLegacyCheckpointContract(projectRoot, root, checkpoint) {
+    const relative = checkpoint.replace("<harnessRoot>", root);
+    const checkpointPath = path.join(projectRoot, relative);
+    if (!(await pathExists(checkpointPath))) {
+        return {};
+    }
+    const text = await readText(checkpointPath);
+    const match = text.match(/## Task Contract[\s\S]*?```ya?ml\s*([\s\S]*?)```/i);
+    if (!match) {
+        return {};
+    }
+    return (parseYaml(match[1]) ?? {});
+}
+async function removeLegacyCheckpoints(projectRoot, root, report) {
+    const relativeCheckpointPath = harnessPath(root, "state", "checkpoints");
+    const checkpointPath = path.join(projectRoot, relativeCheckpointPath);
+    if (!(await pathExists(checkpointPath))) {
+        report.skipped.push(relativeCheckpointPath);
+        return;
+    }
+    await rm(checkpointPath, { recursive: true, force: true });
+    report.changed.push(relativeCheckpointPath);
+}
+async function ensureMemory(projectRoot, root, report) {
+    const relativeMemoryPath = harnessPath(root, "state", "memory.md");
+    const memoryPath = path.join(projectRoot, relativeMemoryPath);
+    if (await pathExists(memoryPath)) {
+        report.skipped.push(relativeMemoryPath);
+        return;
+    }
+    const content = "# Project Memory\n\n记录跨阶段长期有效的稳定知识，并链接到 `.docs/` 正式出处。\n";
+    if (await writeTextIfChanged(memoryPath, content)) {
+        report.changed.push(relativeMemoryPath);
+    }
+}

package/dist/lib/package-json-config.d.ts

@@ -0,0 +1,2 @@
+export declare function packageHarnessRoot(projectRoot: string): Promise<string | undefined>;
+export declare function writePackageHarnessRoot(projectRoot: string, folderName: string): Promise<boolean>;

package/dist/lib/package-json-config.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { normalizeHarnessFolderName } from "./harness-root.js";
+export async function packageHarnessRoot(projectRoot) {
+    const packagePath = path.join(projectRoot, "package.json");
+    if (!(await pathExists(packagePath))) {
+        return undefined;
+    }
+    const packageJson = parsePackageJson(await readText(packagePath));
+    const config = packageJson.sdlcHarness;
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+        return undefined;
+    }
+    const value = config.harnessFolderName;
+    return typeof value === "string" && value.trim() ? normalizeHarnessFolderName(value) : undefined;
+}
+export async function writePackageHarnessRoot(projectRoot, folderName) {
+    const normalized = normalizeHarnessFolderName(folderName);
+    const packagePath = path.join(projectRoot, "package.json");
+    const packageJson = (await pathExists(packagePath)) ? parsePackageJson(await readText(packagePath)) : {};
+    const existingConfig = packageJson.sdlcHarness;
+    const nextConfig = existingConfig && typeof existingConfig === "object" && !Array.isArray(existingConfig)
+        ? { ...existingConfig, harnessFolderName: normalized }
+        : { harnessFolderName: normalized };
+    const next = {
+        ...packageJson,
+        sdlcHarness: nextConfig
+    };
+    return writeTextIfChanged(packagePath, `${JSON.stringify(next, null, 2)}\n`);
+}
+function parsePackageJson(content) {
+    const parsed = JSON.parse(content);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("package.json must contain a JSON object");
+    }
+    return parsed;
+}

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

@@ -0,0 +1,8 @@
+export interface PackageSourceSyncReport {
+    changed: string[];
+}
+export interface PackageSourceCheckReport {
+    drift: string[];
+}
+export declare function syncSource(projectRoot: string): Promise<PackageSourceSyncReport>;
+export declare function checkSource(projectRoot: string): Promise<PackageSourceCheckReport>;

package/dist/lib/package-source.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ensureDir, listFiles, pathExists, readText, writeTextIfChanged } from "./fs.js";
+import { MANAGED_BLOCK_END, MANAGED_BLOCK_START } from "./managed-file.js";
+import { SOURCE_MAPPINGS_PATH } from "./paths.js";
+import { parseYaml } from "./yaml.js";
+export async function syncSource(projectRoot) {
+    const report = { changed: [] };
+    for (const mapping of await readSourceMappings(projectRoot)) {
+        const changed = await applyMapping(projectRoot, mapping);
+        report.changed.push(...changed);
+    }
+    return report;
+}
+export async function checkSource(projectRoot) {
+    const drift = [];
+    for (const mapping of await readSourceMappings(projectRoot)) {
+        const expected = await renderMapping(projectRoot, mapping);
+        const target = path.join(projectRoot, mapping.target);
+        if (typeof expected === "string") {
+            const existing = (await pathExists(target)) ? await readText(target) : "";
+            if (normalize(existing) !== normalize(expected)) {
+                drift.push(mapping.target);
+            }
+            continue;
+        }
+        const sourceHashes = new Map();
+        for (const item of expected) {
+            sourceHashes.set(item.relative, hash(item.content));
+            const targetFile = path.join(target, item.relative);
+            const existing = (await pathExists(targetFile)) ? await readText(targetFile) : "";
+            if (hash(existing) !== hash(item.content)) {
+                drift.push(`${mapping.target}/${item.relative}`);
+            }
+        }
+        const targetFiles = await listFiles(target);
+        for (const targetFile of targetFiles) {
+            if (path.basename(targetFile) === ".gitkeep") {
+                continue;
+            }
+            const relative = path.relative(target, targetFile);
+            if (!sourceHashes.has(relative)) {
+                drift.push(`${mapping.target}/${relative}`);
+            }
+        }
+    }
+    return { drift };
+}
+async function readSourceMappings(projectRoot) {
+    const mappingPath = path.join(projectRoot, SOURCE_MAPPINGS_PATH);
+    const parsed = parseYaml(await readText(mappingPath));
+    return parsed.source_mappings ?? [];
+}
+async function applyMapping(projectRoot, mapping) {
+    const target = path.join(projectRoot, mapping.target);
+    const rendered = await renderMapping(projectRoot, mapping);
+    if (typeof rendered === "string") {
+        return (await writeTextIfChanged(target, rendered)) ? [mapping.target] : [];
+    }
+    await fs.rm(target, { recursive: true, force: true });
+    await ensureDir(target);
+    const changed = [];
+    for (const item of rendered) {
+        const targetFile = path.join(target, item.relative);
+        if (await writeTextIfChanged(targetFile, item.content)) {
+            changed.push(`${mapping.target}/${item.relative}`);
+        }
+    }
+    return changed;
+}
+async function renderMapping(projectRoot, mapping) {
+    const source = path.join(projectRoot, mapping.source);
+    if (mapping.mode === "copy-file") {
+        return readText(source);
+    }
+    if (mapping.mode === "copy-tree") {
+        const files = await listFiles(source);
+        const rendered = [];
+        for (const file of files) {
+            if (path.basename(file) === ".gitkeep") {
+                continue;
+            }
+            rendered.push({ relative: path.relative(source, file), content: await readText(file) });
+        }
+        return rendered;
+    }
+    if (mapping.mode === "extract-managed-block") {
+        const content = await readText(source);
+        const start = content.indexOf(MANAGED_BLOCK_START);
+        const end = content.indexOf(MANAGED_BLOCK_END);
+        if (start >= 0 && end > start) {
+            return `${content.slice(start + MANAGED_BLOCK_START.length, end).trim()}\n`;
+        }
+        return content;
+    }
+    if (mapping.mode === "extract-harness-targets") {
+        return readText(source);
+    }
+    throw new Error(`Unsupported source mapping mode: ${mapping.mode}`);
+}
+function normalize(content) {
+    return content.replace(/\r\n/g, "\n").trimEnd();
+}
+function hash(content) {
+    return createHash("sha256").update(normalize(content)).digest("hex");
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,5 @@
+export declare const SOURCE_MAPPINGS_PATH = "packages/sdlc-harness/source-mappings.yaml";
+export declare const DEFAULT_HARNESS_ROOT = ".agent";
+export declare const HARNESS_JSON_CONFIG_PATH = "sdlc-harness.config.json";
+export declare function packageRoot(): string;
+export declare function packageAssetPath(...segments: string[]): string;

package/dist/lib/paths.js

@@ -0,0 +1,11 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const SOURCE_MAPPINGS_PATH = "packages/sdlc-harness/source-mappings.yaml";
+export const DEFAULT_HARNESS_ROOT = ".agent";
+export const HARNESS_JSON_CONFIG_PATH = "sdlc-harness.config.json";
+export function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+}
+export function packageAssetPath(...segments) {
+    return path.join(packageRoot(), "assets", ...segments);
+}

package/dist/lib/sync-engine.d.ts

@@ -0,0 +1,7 @@
+export interface SyncReport {
+    changed: string[];
+    skipped: string[];
+    blocked: string[];
+}
+export declare function emptySyncReport(): SyncReport;
+export declare function runSync(projectRoot: string): Promise<SyncReport>;