reffy-cli 0.7.0 → 1.1.1

package/dist/diagram.js

@@ -1,7 +1,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { THEMES, renderMermaid, renderMermaidAscii } from "beautiful-mermaid";
-function isLikelyOpenSpecDocument(inputPath, content) {
+function isLikelySpecDocument(inputPath, content) {
     if (inputPath && path.basename(inputPath).toLowerCase() === "spec.md")
         return true;
     return /^### Requirement:\s+/m.test(content) && /^#### Scenario:\s+/m.test(content);
@@ -67,7 +67,7 @@ async function loadSource(request) {
     if (trimmed.length === 0) {
         throw new Error("Diagram input is empty.");
     }
-    if (isLikelyOpenSpecDocument(request.inputPath, raw)) {
+    if (isLikelySpecDocument(request.inputPath, raw)) {
         return { sourceText: convertSpecToMermaid(raw), sourceKind: "spec" };
     }
     return { sourceText: raw, sourceKind: "mermaid" };

package/dist/doctor.d.ts

@@ -14,8 +14,5 @@ export interface DoctorReport {
         optional_failed: number;
     };
 }
-export interface DoctorOptions {
-    checkOpenSpec?: () => boolean;
-}
-export declare function runDoctor(repoRoot: string, options?: DoctorOptions): Promise<DoctorReport>;
+export declare function runDoctor(repoRoot: string): Promise<DoctorReport>;
 export {};

package/dist/doctor.js

@@ -1,8 +1,7 @@
-import { spawnSync } from "node:child_process";
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { validateManifest } from "./manifest.js";
-import { resolveRefsDirName } from "./refs-paths.js";
+import { detectWorkspaceState, resolveRefsDirName } from "./refs-paths.js";
 async function pathExists(targetPath) {
     try {
         await fs.access(targetPath);
@@ -12,10 +11,6 @@ async function pathExists(targetPath) {
         return false;
     }
 }
-function defaultOpenSpecCheck() {
-    const result = spawnSync("openspec", ["--version"], { stdio: "ignore" });
-    return result.error === undefined;
-}
 function summarizeChecks(checks) {
     const required = checks.filter((check) => check.level === "required");
     const optional = checks.filter((check) => check.level === "optional");
@@ -26,8 +21,9 @@ function summarizeChecks(checks) {
         optional_failed: optional.filter((check) => !check.ok).length,
     };
 }
-export async function runDoctor(repoRoot, options) {
+export async function runDoctor(repoRoot) {
     const checks = [];
+    const workspace = detectWorkspaceState(repoRoot);
     const refsDirName = resolveRefsDirName(repoRoot);
     const refsDir = path.join(repoRoot, refsDirName);
     const artifactsDir = path.join(refsDir, "artifacts");
@@ -84,13 +80,13 @@ export async function runDoctor(repoRoot, options) {
                 : `manifest invalid: ${manifestResult.errors.join("; ")}`,
         });
     }
-    const checkOpenSpec = options?.checkOpenSpec ?? defaultOpenSpecCheck;
-    const hasOpenSpec = checkOpenSpec();
     checks.push({
-        id: "openspec_available",
+        id: "workspace_canonical",
         level: "optional",
-        ok: hasOpenSpec,
-        message: hasOpenSpec ? "openspec command is available" : "openspec command not found on PATH",
+        ok: workspace.mode !== "legacy",
+        message: workspace.mode === "legacy"
+            ? "legacy .references workspace detected; run `reffy migrate` to adopt .reffy/"
+            : ".reffy/ is the active workspace",
     });
     return { checks, summary: summarizeChecks(checks) };
 }

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { ReferencesStore } from "./storage.js";
 export { MANIFEST_VERSION, allowedKindExtensions, validateManifest } from "./manifest.js";
 export { runDoctor } from "./doctor.js";
+export { createPlanScaffold } from "./plan.js";
+export { listSpecs, showSpec } from "./spec-runtime.js";

package/dist/index.js

@@ -1,3 +1,5 @@
 export { ReferencesStore } from "./storage.js";
 export { MANIFEST_VERSION, allowedKindExtensions, validateManifest } from "./manifest.js";
 export { runDoctor } from "./doctor.js";
+export { createPlanScaffold } from "./plan.js";
+export { listSpecs, showSpec } from "./spec-runtime.js";

package/dist/manifest.js

@@ -73,6 +73,19 @@ function validateArtifactShape(value, index, errors) {
     if (!Array.isArray(value.tags) || value.tags.some((tag) => typeof tag !== "string")) {
         errors.push(`artifacts[${index}].tags must be an array of strings`);
     }
+    if (value.status !== undefined && typeof value.status !== "string") {
+        errors.push(`artifacts[${index}].status must be a string when provided`);
+    }
+    if (value.related_changes !== undefined) {
+        if (!Array.isArray(value.related_changes) || value.related_changes.some((entry) => typeof entry !== "string")) {
+            errors.push(`artifacts[${index}].related_changes must be an array of strings when provided`);
+        }
+    }
+    if (value.derived_outputs !== undefined) {
+        if (!Array.isArray(value.derived_outputs) || value.derived_outputs.some((entry) => typeof entry !== "string")) {
+            errors.push(`artifacts[${index}].derived_outputs must be an array of strings when provided`);
+        }
+    }
     if (!isIsoDate(value.created_at)) {
         errors.push(`artifacts[${index}].created_at must be an ISO timestamp`);
     }

package/dist/plan-archive.d.ts

@@ -0,0 +1,8 @@
+export interface PlanArchiveResult {
+    change_id: string;
+    archive_dir: string;
+    archived_files: string[];
+    updated_specs: string[];
+    linked_artifacts: number;
+}
+export declare function archivePlanningChange(repoRoot: string, changeId: string): Promise<PlanArchiveResult>;

package/dist/plan-archive.js

@@ -0,0 +1,169 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { DEFAULT_PLANNING_DIRNAME } from "./planning-paths.js";
+import { validatePlanningChange } from "./plan-runtime.js";
+import { ReferencesStore } from "./storage.js";
+const DELTA_SECTION_PATTERN = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/;
+const REQUIREMENT_PATTERN = /^###\s+Requirement:\s+(.+)$/;
+const REQUIREMENTS_HEADING = "## Requirements";
+function archiveDatePrefix() {
+    return new Date().toISOString().slice(0, 10);
+}
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function listFilesRecursive(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listFilesRecursive(fullPath)));
+            continue;
+        }
+        if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files.sort();
+}
+function parseAddedRequirements(content, relPath) {
+    const lines = content.split(/\r?\n/);
+    const sectionTypes = new Set();
+    const blocks = [];
+    let inAddedSection = false;
+    let currentTitle = null;
+    let currentLines = [];
+    const flush = () => {
+        if (!currentTitle)
+            return;
+        blocks.push({
+            title: currentTitle,
+            content: currentLines.join("\n").trimEnd(),
+        });
+        currentTitle = null;
+        currentLines = [];
+    };
+    for (const line of lines) {
+        const sectionMatch = line.match(DELTA_SECTION_PATTERN);
+        if (sectionMatch) {
+            flush();
+            const sectionType = sectionMatch[1] ?? "";
+            sectionTypes.add(sectionType);
+            inAddedSection = sectionType === "ADDED";
+            continue;
+        }
+        const requirementMatch = line.match(REQUIREMENT_PATTERN);
+        if (requirementMatch) {
+            flush();
+            currentTitle = requirementMatch[1]?.trim() ?? "unknown";
+            currentLines = [line];
+            continue;
+        }
+        if (currentTitle) {
+            currentLines.push(line);
+        }
+    }
+    flush();
+    const unsupported = Array.from(sectionTypes).filter((sectionType) => sectionType !== "ADDED");
+    if (unsupported.length > 0) {
+        throw new Error(`${relPath}: unsupported delta sections for archive: ${unsupported.join(", ")}`);
+    }
+    if (!inAddedSection && sectionTypes.size === 0) {
+        throw new Error(`${relPath}: no supported archiveable requirements found`);
+    }
+    if (blocks.length === 0) {
+        throw new Error(`${relPath}: no ADDED requirements found to archive`);
+    }
+    return blocks;
+}
+function buildNewCurrentSpec(capability, changeId, blocks) {
+    return [
+        `# ${capability} Specification`,
+        "",
+        "## Purpose",
+        `TBD - created by archiving change ${changeId}. Update Purpose after archive.`,
+        "",
+        REQUIREMENTS_HEADING,
+        ...blocks.map((block) => block.content),
+        "",
+    ].join("\n");
+}
+function appendRequirementsToCurrentSpec(existing, blocks, relPath) {
+    if (!existing.includes(REQUIREMENTS_HEADING)) {
+        throw new Error(`${relPath}: current spec is missing a "## Requirements" section`);
+    }
+    for (const block of blocks) {
+        const escaped = block.title.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const duplicatePattern = new RegExp(`^###\\s+Requirement:\\s+${escaped}\\s*$`, "m");
+        if (duplicatePattern.test(existing)) {
+            throw new Error(`${relPath}: current spec already contains requirement "${block.title}"`);
+        }
+    }
+    return `${existing.trimEnd()}\n\n${blocks.map((block) => block.content).join("\n\n")}\n`;
+}
+async function buildSpecUpdates(repoRoot, changeId, changeDir) {
+    const specsRoot = path.join(changeDir, "specs");
+    const entries = await fs.readdir(specsRoot, { withFileTypes: true }).catch(() => []);
+    const updates = new Map();
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const capability = entry.name;
+        const deltaPath = path.join(specsRoot, capability, "spec.md");
+        if (!(await pathExists(deltaPath)))
+            continue;
+        const deltaContent = await fs.readFile(deltaPath, "utf8");
+        const relDeltaPath = path.relative(repoRoot, deltaPath).split(path.sep).join("/");
+        const blocks = parseAddedRequirements(deltaContent, relDeltaPath);
+        const currentSpecPath = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "specs", capability, "spec.md");
+        const nextContent = (await pathExists(currentSpecPath))
+            ? appendRequirementsToCurrentSpec(await fs.readFile(currentSpecPath, "utf8"), blocks, path.relative(repoRoot, currentSpecPath).split(path.sep).join("/"))
+            : buildNewCurrentSpec(capability, changeId, blocks);
+        updates.set(currentSpecPath, nextContent);
+    }
+    return updates;
+}
+export async function archivePlanningChange(repoRoot, changeId) {
+    const validation = await validatePlanningChange(repoRoot, changeId);
+    if (!validation.ok) {
+        throw new Error(`cannot archive invalid change "${changeId}": ${validation.errors.join("; ")}`);
+    }
+    const changeDir = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "changes", changeId);
+    if (!(await pathExists(changeDir))) {
+        throw new Error(`change not found: ${changeId}`);
+    }
+    const archiveDir = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "changes", "archive", `${archiveDatePrefix()}-${changeId}`);
+    if (await pathExists(archiveDir)) {
+        throw new Error(`archive destination already exists: ${path.relative(repoRoot, archiveDir).split(path.sep).join("/")}`);
+    }
+    const specUpdates = await buildSpecUpdates(repoRoot, changeId, changeDir);
+    const activeFiles = await listFilesRecursive(changeDir);
+    const pathMap = Object.fromEntries(activeFiles.map((filePath) => {
+        const relCurrent = path.relative(repoRoot, filePath).split(path.sep).join("/");
+        const archivedPath = path.join(archiveDir, path.relative(changeDir, filePath));
+        const relArchived = path.relative(repoRoot, archivedPath).split(path.sep).join("/");
+        return [relCurrent, relArchived];
+    }));
+    for (const [specPath, content] of specUpdates) {
+        await fs.mkdir(path.dirname(specPath), { recursive: true });
+        await fs.writeFile(specPath, content, "utf8");
+    }
+    await fs.mkdir(path.dirname(archiveDir), { recursive: true });
+    await fs.rename(changeDir, archiveDir);
+    const store = new ReferencesStore(repoRoot);
+    const rewriteResult = await store.rewriteDerivedOutputPaths(pathMap);
+    return {
+        change_id: changeId,
+        archive_dir: archiveDir,
+        archived_files: Object.values(pathMap).sort(),
+        updated_specs: Array.from(specUpdates.keys()).sort(),
+        linked_artifacts: rewriteResult.updated,
+    };
+}

package/dist/plan-runtime.d.ts

@@ -0,0 +1,35 @@
+export interface TaskStatus {
+    total: number;
+    completed: number;
+}
+export interface PlanChangeSummary {
+    id: string;
+    title: string;
+    change_dir: string;
+    proposal_path: string;
+    tasks_path: string;
+    design_path?: string;
+    delta_count: number;
+    task_status: TaskStatus;
+}
+export interface PlanShowResult extends PlanChangeSummary {
+    proposal: string;
+    tasks: string;
+    design?: string;
+    specs: Array<{
+        capability: string;
+        path: string;
+        content: string;
+    }>;
+}
+export interface PlanValidationResult {
+    ok: boolean;
+    change_id: string;
+    errors: string[];
+    warnings: string[];
+    delta_count: number;
+    task_status: TaskStatus;
+}
+export declare function listPlanningChanges(repoRoot: string): Promise<PlanChangeSummary[]>;
+export declare function showPlanningChange(repoRoot: string, changeId: string): Promise<PlanShowResult>;
+export declare function validatePlanningChange(repoRoot: string, changeId: string): Promise<PlanValidationResult>;

package/dist/plan-runtime.js

@@ -0,0 +1,218 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { DEFAULT_PLANNING_DIRNAME } from "./planning-paths.js";
+const CHANGE_HEADING_PREFIX = "# Change:";
+const REQUIREMENT_SECTION_PATTERN = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/;
+const REQUIREMENT_HEADING_PATTERN = /^###\s+Requirement:\s+(.+)$/;
+const SCENARIO_HEADING_PATTERN = /^####\s+Scenario:\s+(.+)$/;
+const BAD_SCENARIO_PATTERNS = [/^###\s+Scenario:/, /^- \*\*Scenario:/, /^\*\*Scenario\*\*:/];
+async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function listDirectories(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+}
+function getChangePaths(repoRoot, changeId) {
+    const changeDir = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "changes", changeId);
+    return {
+        id: changeId,
+        changeDir,
+        proposalPath: path.join(changeDir, "proposal.md"),
+        tasksPath: path.join(changeDir, "tasks.md"),
+        designPath: path.join(changeDir, "design.md"),
+        specsDir: path.join(changeDir, "specs"),
+    };
+}
+async function listSpecFiles(specsDir) {
+    const capabilities = await listDirectories(specsDir);
+    const files = [];
+    for (const capability of capabilities) {
+        const capabilityDir = path.join(specsDir, capability);
+        const entries = await fs.readdir(capabilityDir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith(".md"))
+                continue;
+            files.push(path.join(capabilityDir, entry.name));
+        }
+    }
+    return files.sort();
+}
+function countTasks(content) {
+    const matches = content.matchAll(/^- \[( |x)\] /gm);
+    let total = 0;
+    let completed = 0;
+    for (const match of matches) {
+        total += 1;
+        if (match[1] === "x")
+            completed += 1;
+    }
+    return { total, completed };
+}
+function extractTitle(content, fallback) {
+    for (const line of content.split(/\r?\n/)) {
+        if (line.startsWith(CHANGE_HEADING_PREFIX)) {
+            return line.slice(CHANGE_HEADING_PREFIX.length).trim() || fallback;
+        }
+        if (line.startsWith("# ")) {
+            return line.slice(2).trim() || fallback;
+        }
+    }
+    return fallback;
+}
+function validateSpecContent(content, relPath, errors) {
+    const lines = content.split(/\r?\n/);
+    let sectionCount = 0;
+    let requirementCount = 0;
+    let scenarioCount = 0;
+    let currentRequirement = null;
+    let currentRequirementScenarios = 0;
+    const finalizeRequirement = () => {
+        if (currentRequirement !== null && currentRequirementScenarios === 0) {
+            errors.push(`${relPath}: requirement "${currentRequirement}" must include at least one scenario`);
+        }
+    };
+    for (const line of lines) {
+        if (REQUIREMENT_SECTION_PATTERN.test(line)) {
+            sectionCount += 1;
+            continue;
+        }
+        const requirementMatch = line.match(REQUIREMENT_HEADING_PATTERN);
+        if (requirementMatch) {
+            finalizeRequirement();
+            requirementCount += 1;
+            currentRequirement = requirementMatch[1]?.trim() ?? "unknown";
+            currentRequirementScenarios = 0;
+            continue;
+        }
+        const scenarioMatch = line.match(SCENARIO_HEADING_PATTERN);
+        if (scenarioMatch) {
+            scenarioCount += 1;
+            currentRequirementScenarios += 1;
+            continue;
+        }
+        if (BAD_SCENARIO_PATTERNS.some((pattern) => pattern.test(line))) {
+            errors.push(`${relPath}: scenarios must use "#### Scenario:" headings`);
+        }
+    }
+    finalizeRequirement();
+    if (sectionCount === 0) {
+        errors.push(`${relPath}: must include at least one "## ADDED|MODIFIED|REMOVED|RENAMED Requirements" section`);
+    }
+    if (requirementCount === 0) {
+        errors.push(`${relPath}: must include at least one "### Requirement:" heading`);
+    }
+    if (scenarioCount === 0) {
+        errors.push(`${relPath}: must include at least one "#### Scenario:" heading`);
+    }
+}
+async function buildChangeSummary(repoRoot, changeId) {
+    const paths = getChangePaths(repoRoot, changeId);
+    const proposal = await fs.readFile(paths.proposalPath, "utf8");
+    const tasks = await fs.readFile(paths.tasksPath, "utf8").catch(() => "");
+    const designExists = await pathExists(paths.designPath);
+    const specFiles = await listSpecFiles(paths.specsDir);
+    return {
+        id: changeId,
+        title: extractTitle(proposal, changeId),
+        change_dir: paths.changeDir,
+        proposal_path: paths.proposalPath,
+        tasks_path: paths.tasksPath,
+        design_path: designExists ? paths.designPath : undefined,
+        delta_count: specFiles.length,
+        task_status: countTasks(tasks),
+    };
+}
+export async function listPlanningChanges(repoRoot) {
+    const changesRoot = path.join(repoRoot, DEFAULT_PLANNING_DIRNAME, "changes");
+    const changeIds = (await listDirectories(changesRoot)).filter((id) => id !== "archive");
+    const summaries = [];
+    for (const changeId of changeIds) {
+        const proposalPath = path.join(changesRoot, changeId, "proposal.md");
+        if (!(await pathExists(proposalPath)))
+            continue;
+        summaries.push(await buildChangeSummary(repoRoot, changeId));
+    }
+    return summaries.sort((a, b) => a.id.localeCompare(b.id));
+}
+export async function showPlanningChange(repoRoot, changeId) {
+    const summary = await buildChangeSummary(repoRoot, changeId);
+    const paths = getChangePaths(repoRoot, changeId);
+    const proposal = await fs.readFile(paths.proposalPath, "utf8");
+    const tasks = await fs.readFile(paths.tasksPath, "utf8");
+    const design = await fs.readFile(paths.designPath, "utf8").catch(() => undefined);
+    const specFiles = await listSpecFiles(paths.specsDir);
+    const specs = await Promise.all(specFiles.map(async (filePath) => ({
+        capability: path.basename(path.dirname(filePath)),
+        path: filePath,
+        content: await fs.readFile(filePath, "utf8"),
+    })));
+    return {
+        ...summary,
+        proposal,
+        tasks,
+        design,
+        specs,
+    };
+}
+export async function validatePlanningChange(repoRoot, changeId) {
+    const paths = getChangePaths(repoRoot, changeId);
+    const errors = [];
+    const warnings = [];
+    if (!(await pathExists(paths.changeDir))) {
+        return {
+            ok: false,
+            change_id: changeId,
+            errors: [`change not found: ${changeId}`],
+            warnings,
+            delta_count: 0,
+            task_status: { total: 0, completed: 0 },
+        };
+    }
+    if (!(await pathExists(paths.proposalPath))) {
+        errors.push("missing required file: proposal.md");
+    }
+    if (!(await pathExists(paths.tasksPath))) {
+        errors.push("missing required file: tasks.md");
+    }
+    if (!(await pathExists(paths.specsDir))) {
+        errors.push("missing required directory: specs/");
+    }
+    const proposal = await fs.readFile(paths.proposalPath, "utf8").catch(() => "");
+    if (proposal.length > 0) {
+        if (!proposal.includes("## Why"))
+            errors.push("proposal.md must include a '## Why' section");
+        if (!proposal.includes("## What Changes"))
+            errors.push("proposal.md must include a '## What Changes' section");
+        if (!proposal.includes("## Impact"))
+            errors.push("proposal.md must include a '## Impact' section");
+    }
+    const tasks = await fs.readFile(paths.tasksPath, "utf8").catch(() => "");
+    const taskStatus = countTasks(tasks);
+    if (tasks.length > 0 && taskStatus.total === 0) {
+        warnings.push("tasks.md does not contain any checkbox tasks");
+    }
+    const specFiles = await listSpecFiles(paths.specsDir).catch(() => []);
+    if (specFiles.length === 0) {
+        errors.push("specs/ must contain at least one delta spec file");
+    }
+    for (const filePath of specFiles) {
+        const relPath = path.relative(paths.changeDir, filePath).split(path.sep).join("/");
+        const content = await fs.readFile(filePath, "utf8").catch(() => "");
+        validateSpecContent(content, relPath, errors);
+    }
+    return {
+        ok: errors.length === 0,
+        change_id: changeId,
+        errors,
+        warnings,
+        delta_count: specFiles.length,
+        task_status: taskStatus,
+    };
+}

package/dist/plan.d.ts

@@ -0,0 +1,25 @@
+import type { Artifact } from "./types.js";
+interface StoreLike {
+    repoRoot: string;
+    listArtifacts(): Promise<Artifact[]>;
+    getArtifactPath(artifact: Artifact): string;
+    linkPlanningOutputs(artifactFilenames: string[], outputPaths: string[], changeId: string): Promise<{
+        linked: number;
+    }>;
+}
+export interface CreatePlanInput {
+    changeId: string;
+    title?: string;
+    artifactFilters?: string[];
+    includeAllArtifacts?: boolean;
+    overwrite?: boolean;
+}
+export interface CreatePlanResult {
+    change_id: string;
+    change_dir: string;
+    selected_artifacts: string[];
+    written_files: string[];
+    linked_artifacts: number;
+}
+export declare function createPlanScaffold(store: StoreLike, input: CreatePlanInput): Promise<CreatePlanResult>;
+export {};