@deksden-com/dd-flow-cli 0.1.0 → 0.3.0

package/dist/schemas/status-report.schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/status-report@1",
+  "title": "dd-flow status report",
+  "description": "Read-only status contract for CLI/canon/project Memory Bank version visibility and drift diagnostics.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["ok", "schema_id", "dd_flow_home", "cwd", "cli", "project", "canon"],
+  "properties": {
+    "ok": { "type": "boolean" },
+    "schema_id": { "const": "dd-flow/status-report@1" },
+    "dd_flow_home": { "type": "string", "minLength": 1 },
+    "cwd": { "type": "string", "minLength": 1 },
+    "cli": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["version", "package_name", "build"],
+      "properties": {
+        "version": { "type": "string", "minLength": 1 },
+        "package_name": { "type": "string", "minLength": 1 },
+        "compatibility": { "$ref": "#/definitions/cliCompatibility" },
+        "registry": { "$ref": "#/definitions/registryStatus" },
+        "build": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["status", "built_with_canon"],
+          "properties": {
+            "status": { "type": "string", "enum": ["present", "degraded"] },
+            "built_at": { "type": ["string", "null"] },
+            "commit": { "type": ["string", "null"] },
+            "reason": { "type": "string" },
+            "built_with_canon": {
+              "type": "object",
+              "additionalProperties": true,
+              "required": ["version", "commit", "flow_contract", "status"],
+              "properties": {
+                "version": { "type": ["string", "null"] },
+                "commit": { "type": ["string", "null"] },
+                "flow_contract": { "type": ["string", "null"] },
+                "status": { "type": "string", "enum": ["present", "unknown", "degraded"] },
+                "reason": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "project": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["requested_root", "root", "root_source", "registered", "memory_bank", "flow_pack", "drift"],
+      "properties": {
+        "requested_root": { "type": "string", "minLength": 1 },
+        "root": { "type": ["string", "null"] },
+        "root_source": { "type": "string", "enum": ["explicit", "git", "cwd"] },
+        "registered": { "type": "boolean" },
+        "id": { "type": ["string", "null"] },
+        "status": { "type": ["string", "null"] },
+        "memory_bank": { "$ref": "#/definitions/memoryBank" },
+        "flow_pack": { "$ref": "#/definitions/flowPack" },
+        "drift": { "$ref": "#/definitions/drift" }
+      }
+    },
+    "canon": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["ok", "resolved", "compatibility"],
+      "properties": {
+        "ok": { "type": "boolean" },
+        "resolved": {
+          "type": ["object", "null"],
+          "additionalProperties": true
+        },
+        "compatibility": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["cli_built_with_resolved_canon", "reason"],
+          "properties": {
+            "cli_built_with_resolved_canon": {
+              "type": "string",
+              "enum": ["same", "behind", "ahead", "unknown"]
+            },
+            "reason": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "cliCompatibility": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["verdict", "reason", "package_name", "installed_version"],
+      "properties": {
+        "verdict": { "type": "string", "enum": ["ok", "outdated", "incompatible", "missing", "unknown"] },
+        "reason": { "type": "string", "minLength": 1 },
+        "package_name": { "type": "string", "minLength": 1 },
+        "expected_package_name": { "type": "string" },
+        "installed_version": { "type": "string", "minLength": 1 },
+        "memory_bank_version": { "type": ["string", "null"] },
+        "min_version": { "type": ["string", "null"] },
+        "recommended_version": { "type": ["string", "null"] },
+        "status_contract": { "type": ["string", "null"] },
+        "version_contract": { "type": ["string", "null"] },
+        "flow_contract": { "type": ["string", "null"] },
+        "update_command": { "type": ["string", "null"] }
+      }
+    },
+    "registryStatus": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["package_name", "latest", "checked_at", "source", "status"],
+      "properties": {
+        "package_name": { "type": "string", "minLength": 1 },
+        "latest": { "type": ["string", "null"] },
+        "checked_at": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "enum": ["npm", "npm_cache"] },
+        "status": { "type": "string", "enum": ["ok", "degraded"] },
+        "reason": { "type": "string" }
+      }
+    },
+    "memoryBank": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "required": ["root", "folder_name", "version", "source", "status"],
+      "properties": {
+        "root": { "type": ["string", "null"] },
+        "folder_name": { "type": ["string", "null"], "enum": [".memory-bank", "memory-bank", null] },
+        "version": { "type": ["string", "null"] },
+        "source": { "type": ["string", "null"] },
+        "status": { "type": "string", "enum": ["present", "missing", "invalid", "unknown"] },
+        "reason": { "type": "string" }
+      }
+    },
+    "flowPack": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "required": ["manifest_path", "schema_id", "pack_version", "source_commit", "canon_version_at_source_commit", "status", "canonical_only_files"],
+      "properties": {
+        "manifest_path": { "type": ["string", "null"] },
+        "schema_id": { "type": ["string", "null"] },
+        "pack_version": { "type": ["string", "null"] },
+        "source_commit": { "type": ["string", "null"] },
+        "canon_version_at_source_commit": { "type": ["string", "null"] },
+        "status": { "type": "string", "enum": ["present", "missing", "invalid", "degraded"] },
+        "reason": { "type": "string" },
+        "canonical_only_files": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "drift": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "required": ["memory_bank_version", "flow_pack_commit", "overall", "next_action"],
+      "properties": {
+        "memory_bank_version": { "$ref": "#/definitions/comparison" },
+        "flow_pack_commit": { "$ref": "#/definitions/comparison" },
+        "overall": {
+          "type": "string",
+          "enum": ["same", "behind", "ahead", "diverged", "missing", "invalid", "unknown", "not_applicable"]
+        },
+        "next_action": { "type": "string", "minLength": 1 }
+      }
+    },
+    "comparison": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["status", "confidence", "reason"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["same", "behind", "ahead", "diverged", "missing", "invalid", "unknown", "not_applicable"]
+        },
+        "confidence": {
+          "type": "string",
+          "enum": ["exact", "semver", "git_ancestry", "declared", "none"]
+        },
+        "reason": { "type": "string", "minLength": 1 },
+        "current": { "type": ["string", "null"] },
+        "target": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/dist/schemas/version-report.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/version-report@1",
+  "title": "dd-flow version report",
+  "description": "Small read-only JSON contract for dd-flow version --json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "schema_id", "cli"],
+  "properties": {
+    "ok": { "const": true },
+    "schema_id": { "const": "dd-flow/version-report@1" },
+    "cli": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package_name", "version"],
+      "properties": {
+        "package_name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/dist/services/build-info.js

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export function getCliBuildInfo() {
+    const packageRoot = findPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
+    const packageJson = readPackageJson(packageRoot);
+    const version = stringOr(packageJson.version, "0.0.0");
+    const packageName = stringOr(packageJson.name, "dd-flow-cli");
+    const buildInfoPath = packageRoot ? path.join(packageRoot, "dist", "build-info.json") : null;
+    const buildInfo = buildInfoPath && fs.existsSync(buildInfoPath) ? readBuildInfo(buildInfoPath) : null;
+    if (!buildInfo) {
+        return {
+            version,
+            package_name: packageName,
+            build: {
+                status: "degraded",
+                built_at: null,
+                commit: null,
+                reason: "build_info_missing",
+                built_with_canon: {
+                    version: null,
+                    commit: null,
+                    flow_contract: null,
+                    repo_root: null,
+                    memorybank_root: null,
+                    flow_root: null,
+                    layout: null,
+                    status: "unknown",
+                    reason: "build_info_missing"
+                }
+            }
+        };
+    }
+    const builtWithCanon = asRecord(buildInfo.built_with_canon);
+    const canonVersion = stringOrNull(builtWithCanon?.version);
+    const canonCommit = stringOrNull(builtWithCanon?.commit);
+    const flowContract = stringOrNull(builtWithCanon?.flow_contract);
+    const repoRoot = stringOrNull(builtWithCanon?.repo_root);
+    const memorybankRoot = stringOrNull(builtWithCanon?.memorybank_root);
+    const flowRoot = stringOrNull(builtWithCanon?.flow_root);
+    const layout = stringOrNull(builtWithCanon?.layout);
+    const canonStatus = canonVersion && canonCommit && flowContract ? "present" : "degraded";
+    return {
+        version,
+        package_name: packageName,
+        build: {
+            status: "present",
+            built_at: stringOrNull(buildInfo.built_at),
+            commit: stringOrNull(buildInfo.cli_commit),
+            built_with_canon: {
+                version: canonVersion,
+                commit: canonCommit,
+                flow_contract: flowContract,
+                repo_root: repoRoot,
+                memorybank_root: memorybankRoot,
+                flow_root: flowRoot,
+                layout,
+                status: canonStatus,
+                ...(canonStatus === "degraded" ? { reason: "build_canon_metadata_incomplete" } : {})
+            }
+        }
+    };
+}
+export function getCliVersionReport() {
+    const cli = getCliBuildInfo();
+    return {
+        ok: true,
+        schema_id: "dd-flow/version-report@1",
+        cli: {
+            package_name: cli.package_name,
+            version: cli.version
+        }
+    };
+}
+function findPackageRoot(start) {
+    let current = path.resolve(start);
+    while (true) {
+        const candidate = path.join(current, "package.json");
+        if (fs.existsSync(candidate))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function readPackageJson(packageRoot) {
+    if (!packageRoot)
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function readBuildInfo(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return asRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringOr(value, fallback) {
+    return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+function stringOrNull(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

package/dist/services/canon.js

@@ -0,0 +1,298 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+const canonRootKey = "canon.root";
+export function registerCanonRoot(context, input) {
+    const resolution = resolveCanonRoot(context, { explicitRoot: input.root, allowRegistered: false });
+    if (!resolution.ok || !resolution.canon) {
+        return {
+            ...resolution,
+            action: "register",
+            exit_code: 1
+        };
+    }
+    const now = context.now();
+    context.db.run(`INSERT INTO runtime_config (key, value_json, created_at, updated_at)
+     VALUES (?, ?, ?, ?)
+     ON CONFLICT(key) DO UPDATE SET
+       value_json = excluded.value_json,
+       updated_at = excluded.updated_at`, [canonRootKey, JSON.stringify({ root: resolution.canon.root }), now, now]);
+    return {
+        ok: true,
+        action: "register",
+        canon: {
+            ...resolution.canon,
+            source: "registered"
+        },
+        db_path: context.db.path
+    };
+}
+export function getCanonStatus(context, input = {}) {
+    const resolution = resolveCanonRoot(context, { explicitRoot: input.root });
+    return {
+        ...resolution,
+        dd_flow_home: context.ddFlowHome,
+        registered: readRegisteredCanonRoot(context)
+    };
+}
+export function resolveCanonRoot(context, input = {}) {
+    const candidates = canonCandidates(context, input);
+    const validCandidates = candidates.filter((candidate) => candidate.valid && candidate.realpath);
+    const uniqueValid = uniqueBy(validCandidates, (candidate) => candidate.realpath ?? candidate.root);
+    const blockers = candidates.flatMap((candidate) => candidate.blockers);
+    if (uniqueValid.length === 1) {
+        const candidate = uniqueValid[0];
+        if (!candidate) {
+            throw new Error("Expected one canonical candidate.");
+        }
+        const root = candidate.realpath ?? candidate.root;
+        const flowRoot = candidate.flow_root ?? path.join(root, "dd-flow");
+        const memorybankRoot = candidate.memorybank_root ?? root;
+        const mbbRoot = candidate.mbb_root ?? path.join(memorybankRoot, "mbb");
+        const layout = candidate.layout ?? "legacy_root";
+        const metadata = readCanonMetadata(root, flowRoot);
+        return {
+            ok: true,
+            canon: {
+                root,
+                repo_root: root,
+                source: candidate.source,
+                layout,
+                flow_root: flowRoot,
+                mbb_root: mbbRoot,
+                memorybank_root: memorybankRoot,
+                version: metadata.version,
+                commit: metadata.commit,
+                flow_contract: metadata.flow_contract,
+                metadata
+            },
+            candidates,
+            blockers: [],
+            bootstrap: []
+        };
+    }
+    if (uniqueValid.length > 1) {
+        return {
+            ok: false,
+            exit_code: 1,
+            candidates,
+            blockers: [
+                "Multiple different canonical Memory Bank roots are configured. Pass --root explicitly or make DD_MEMORYBANK and the registered root point to the same checkout."
+            ],
+            bootstrap: [
+                "dd-flow canon register --root \"$DD_MEMORYBANK\" --json",
+                "dd-flow canon resolve --root /absolute/path/to/dd-memorybank --json"
+            ]
+        };
+    }
+    return {
+        ok: false,
+        exit_code: 1,
+        candidates,
+        blockers: blockers.length > 0 ? blockers : ["Canonical Memory Bank root is not configured."],
+        bootstrap: [
+            "Clone the canonical dd-memorybank repository locally.",
+            "export DD_MEMORYBANK=/absolute/path/to/dd-memorybank",
+            "dd-flow canon register --root \"$DD_MEMORYBANK\" --json"
+        ]
+    };
+}
+function canonCandidates(context, input) {
+    const candidates = [];
+    if (input.explicitRoot) {
+        candidates.push(validateCanonCandidate("explicit", input.explicitRoot));
+        return candidates;
+    }
+    if (context.env.DD_MEMORYBANK) {
+        candidates.push(validateCanonCandidate("env", context.env.DD_MEMORYBANK));
+    }
+    if (input.allowRegistered !== false) {
+        const registered = readRegisteredCanonRoot(context);
+        if (registered?.root) {
+            candidates.push(validateCanonCandidate("registered", registered.root));
+        }
+    }
+    for (const known of knownCanonRoots()) {
+        candidates.push(validateCanonCandidate("known", known));
+    }
+    return uniqueBy(candidates, (candidate) => `${candidate.source}:${candidate.root}`);
+}
+function validateCanonCandidate(source, root) {
+    const absolute = path.resolve(root);
+    const blockers = [];
+    let realpath = null;
+    if (!fs.existsSync(absolute)) {
+        return { source, root: absolute, realpath, valid: false, blockers: [`${source} canonical root does not exist: ${absolute}`] };
+    }
+    realpath = fs.realpathSync(absolute);
+    if (!fs.statSync(realpath).isDirectory()) {
+        blockers.push(`${source} canonical root is not a directory: ${realpath}`);
+    }
+    if (path.basename(realpath) === ".memory-bank" && fs.existsSync(path.join(path.dirname(realpath), "VERSION"))) {
+        blockers.push(`${source} canonical root points to .memory-bank; use the dd-memorybank repository root instead: ${path.dirname(realpath)}`);
+    }
+    const layout = assessCanonLayout(realpath);
+    blockers.push(...layout.blockers.map((blocker) => `${source} ${blocker}`));
+    return {
+        source,
+        root: absolute,
+        realpath,
+        valid: blockers.length === 0 && layout.valid,
+        blockers,
+        ...(layout.valid
+            ? {
+                layout: layout.layout,
+                memorybank_root: layout.memorybankRoot,
+                flow_root: layout.flowRoot,
+                mbb_root: layout.mbbRoot
+            }
+            : {})
+    };
+}
+export function readCanonMetadata(root, flowRoot = path.join(root, "dd-flow")) {
+    const diagnostics = [];
+    const version = readTrimmed(path.join(root, "VERSION"));
+    if (!version)
+        diagnostics.push("canon_version_missing");
+    const commit = gitCommit(root);
+    if (!commit)
+        diagnostics.push("canon_commit_unknown");
+    const flowContract = readFlowContractId(flowRoot);
+    if (!flowContract)
+        diagnostics.push("flow_contract_unknown");
+    return {
+        version,
+        commit,
+        flow_contract: flowContract,
+        status: version && commit && flowContract ? "present" : diagnostics.length > 0 ? "degraded" : "unknown",
+        diagnostics
+    };
+}
+function readTrimmed(file) {
+    try {
+        const value = fs.readFileSync(file, "utf8").trim();
+        return value.length > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveCanonLayout(root) {
+    return assessCanonLayout(path.resolve(root));
+}
+function assessCanonLayout(root) {
+    const legacy = assessLayout(root, "legacy_root", root);
+    const dot = assessLayout(root, "dot_memory_bank", path.join(root, ".memory-bank"));
+    if (dot.valid && !legacy.valid)
+        return dot;
+    if (legacy.valid && !dot.valid)
+        return legacy;
+    if (dot.valid && legacy.valid) {
+        if (dot.flowContract && legacy.flowContract && dot.flowContract !== legacy.flowContract) {
+            return {
+                ...dot,
+                valid: false,
+                blockers: [
+                    `canonical root has conflicting legacy_root and dot_memory_bank flow contracts: ${legacy.flowContract} vs ${dot.flowContract}`
+                ]
+            };
+        }
+        return dot;
+    }
+    return {
+        ...dot,
+        valid: false,
+        blockers: [
+            "canonical root does not match legacy_root or dot_memory_bank layout",
+            ...legacy.blockers.map((blocker) => `legacy_root: ${blocker}`),
+            ...dot.blockers.map((blocker) => `dot_memory_bank: ${blocker}`)
+        ]
+    };
+}
+function assessLayout(root, layout, memorybankRoot) {
+    const blockers = [];
+    const requiredFiles = [
+        "dd-flow/README.md",
+        "mbb/index.md",
+        "protocol/index.md",
+        "dd-flow/mb-init.md",
+        "dd-flow/mb-upgrade.md",
+        "dd-flow/mb-upgrade-review.md",
+        "dd-flow/mb-distill.md"
+    ];
+    for (const relativePath of requiredFiles) {
+        const file = path.join(memorybankRoot, relativePath);
+        if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+            blockers.push(`canonical root is missing ${layout} ${relativePath}: ${root}`);
+        }
+    }
+    const flowRoot = path.join(memorybankRoot, "dd-flow");
+    return {
+        layout,
+        memorybankRoot,
+        flowRoot,
+        mbbRoot: path.join(memorybankRoot, "mbb"),
+        valid: blockers.length === 0,
+        blockers,
+        flowContract: readFlowContractId(flowRoot)
+    };
+}
+function readFlowContractId(flowRoot) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(flowRoot, "flow-contract.json"), "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const id = parsed.id;
+            return typeof id === "string" && id.length > 0 ? id : null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function gitCommit(root) {
+    const result = spawnSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" });
+    return result.status === 0 ? result.stdout.trim() || null : null;
+}
+function readRegisteredCanonRoot(context) {
+    const row = context.db.get("SELECT key, value_json, updated_at FROM runtime_config WHERE key = ?", [canonRootKey]);
+    if (!row)
+        return null;
+    const value = JSON.parse(row.value_json);
+    return typeof value.root === "string" ? { root: value.root, updated_at: row.updated_at } : null;
+}
+function knownCanonRoots() {
+    const cwd = process.cwd();
+    const candidates = [];
+    for (const dir of ancestorDirs(cwd)) {
+        if (path.basename(dir) === "dd-memorybank") {
+            candidates.push(dir);
+        }
+        candidates.push(path.join(dir, "dd-memorybank"));
+    }
+    return uniqueBy(candidates.filter((candidate) => fs.existsSync(candidate)), (candidate) => fs.realpathSync(candidate));
+}
+function ancestorDirs(start) {
+    const dirs = [];
+    let current = path.resolve(start);
+    while (true) {
+        dirs.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return dirs;
+}
+function uniqueBy(items, keyFor) {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const key = keyFor(item);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(item);
+        }
+    }
+    return result;
+}

package/dist/services/cleanup.js

@@ -7,7 +7,7 @@ import { ensureReadableFile } from "../storage/database.js";
 import { projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
-import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+import { protocolRunDiagnostics, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 const actionKinds = new Set([
     "repair_protocol_state",
     "cancel_queue_job",
@@ -39,6 +39,19 @@ export function cleanupScan(context, input) {
                 });
             }
         }
+        const fullProtocol = requireProtocol(context, protocol.id);
+        const state = readProtocolRuntimeState(context, fullProtocol).state;
+        const diagnostics = protocolRunDiagnostics(context, fullProtocol, state).diagnostics;
+        for (const diagnostic of diagnostics.filter((entry) => entry.code === "protocol_run_stage_mismatch")) {
+            findings.push({
+                code: "protocol_run_stage_mismatch",
+                severity: diagnostic.severity === "error" ? "warning" : "info",
+                protocol_id: protocol.id,
+                protocol_stage: state.stage,
+                latest_run: diagnostic.latest_run,
+                recommended_commands: diagnostic.recommended_commands
+            });
+        }
     }
     const orphanQueueJobs = context.db.all(`SELECT mq.protocol_id, mq.status FROM merge_queue mq
      LEFT JOIN protocols p ON p.id = mq.protocol_id