@deksden-com/dd-flow-cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "./cli/run-cli.js";
+const exitCode = await runCli(process.argv.slice(2));
+process.exitCode = exitCode;

package/dist/domain/contracts.js

@@ -0,0 +1,57 @@
+import { canTransition as canFlowTransition, defaultFlowContract, isAllowedStage as isContractStage } from "./flow-contract.js";
+export const schemaVersion = "0.1.0";
+export const allowedPlanKinds = [
+    "analysis",
+    "decision",
+    "implementation",
+    "documentation",
+    "check",
+    "verification",
+    "review",
+    "scenario",
+    "evidence",
+    "operations"
+];
+export const allowedPlanStatuses = ["pending", "in_progress", "done", "blocked", "skipped"];
+export const allowedStages = [
+    "registered",
+    "prime",
+    "plan",
+    "implementation",
+    "readiness",
+    "ready_for_merge",
+    "queued_for_merge",
+    "integration",
+    "cancelled",
+    "closed",
+    "blocked",
+    "waiting_for_user"
+];
+export const mergeQueueStatuses = ["ready", "claimed", "merged", "failed", "requeued", "cancelled"];
+export const mergeSessionStatuses = ["active", "stopping", "stopped", "expired"];
+export const bootstrapStatuses = ["not_required", "pending", "running", "succeeded", "failed", "skipped"];
+export const flowKinds = ["planning", "implementation", "merge_worker", "merge_job", "memory_flow", "research_no_protocol"];
+export const flowSessionStatuses = ["pending", "active", "waiting_user", "blocked", "stopping", "stopped", "closed"];
+export const continuationPolicies = ["none", "go_router", "implementation_plan", "merge_queue", "merge_job", "memory_flow"];
+export const cmuxModes = ["off", "auto", "required"];
+export function isActiveProtocolStatus(status) {
+    return !["closed", "closed_local", "cancelled"].includes(status);
+}
+export function isActiveQueueStatus(status) {
+    return ["ready", "claimed", "requeued"].includes(status);
+}
+export function isQueueHistoryStatus(status) {
+    return !isActiveQueueStatus(status);
+}
+export function isAllowedStage(value, contract = defaultFlowContract) {
+    return isContractStage(value, contract);
+}
+/**
+ * Mechanical v1 transition graph for protocol stages.
+ *
+ * @docs .memory-bank/spec/system/v1-observable-state.md
+ * @scenario .memory-bank/scenarios/SCN-002-transition-audit.md
+ */
+export function canTransition(from, to, contract = defaultFlowContract) {
+    return canFlowTransition(from, to, contract);
+}

package/dist/domain/entity-ids.js

@@ -0,0 +1,47 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+const fullIdPattern = /^([A-Z]{2,4})-(\d{3})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+const shortIdPattern = /^([A-Z]{2,4})-\d{3}$/;
+export function parseFullEntityId(id) {
+    const match = fullIdPattern.exec(id);
+    if (!match?.[1] || !match[2] || !match[3]) {
+        throw new AppError("validation", `Invalid typed entity id: ${id}`, 2, {
+            expected: "TYPE-NNN-slug"
+        });
+    }
+    return {
+        type: match[1],
+        shortId: `${match[1]}-${match[2]}`,
+        slug: match[3],
+        fullId: id
+    };
+}
+export function isFullEntityId(id) {
+    return fullIdPattern.test(id);
+}
+export function isShortEntityId(id) {
+    return shortIdPattern.test(id);
+}
+export function slugFromRoot(root) {
+    const basename = path.basename(root);
+    const slug = basename
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+    return slug || "project";
+}
+export function formatFullId(type, sequence, slug) {
+    if (!/^[A-Z]{2,4}$/.test(type)) {
+        throw new AppError("validation", `Invalid entity type: ${type}`, 2);
+    }
+    if (sequence < 1 || sequence > 999) {
+        throw new AppError("validation", `Entity sequence is out of range: ${sequence}`, 2);
+    }
+    return `${type}-${String(sequence).padStart(3, "0")}-${slug}`;
+}
+export function shortIdForFullId(id) {
+    return parseFullEntityId(id).shortId;
+}

package/dist/domain/flow-contract.js

@@ -0,0 +1,233 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { AppError } from "../shared/errors.js";
+import { parseJsonObject } from "../shared/json.js";
+export const defaultFlowContract = {
+    id: "dd-flow-canonical-2026-05",
+    version: 1,
+    stages: {
+        registered: { terminal: false },
+        prime: { terminal: false },
+        plan: { terminal: false },
+        implementation: { terminal: false },
+        readiness: { terminal: false },
+        ready_for_merge: { terminal: false },
+        queued_for_merge: { terminal: false },
+        integration: { terminal: false },
+        cancelled: { terminal: true },
+        closed: { terminal: true },
+        blocked: { terminal: false },
+        waiting_for_user: { terminal: false }
+    },
+    transitions: {
+        registered: ["prime", "blocked", "waiting_for_user"],
+        prime: ["plan", "blocked", "waiting_for_user"],
+        plan: ["implementation", "blocked", "waiting_for_user"],
+        implementation: ["readiness", "blocked", "waiting_for_user"],
+        readiness: ["ready_for_merge", "blocked", "waiting_for_user"],
+        ready_for_merge: ["queued_for_merge", "blocked", "waiting_for_user"],
+        queued_for_merge: ["integration", "blocked", "waiting_for_user"],
+        integration: ["closed", "blocked", "waiting_for_user"],
+        cancelled: [],
+        closed: [],
+        blocked: ["prime", "plan", "implementation", "readiness", "ready_for_merge", "closed"],
+        waiting_for_user: ["prime", "plan", "implementation", "readiness", "blocked", "closed"]
+    },
+    readiness: {
+        command: "ready-for-merge",
+        allowed_from: ["readiness", "ready_for_merge"],
+        target_stage: "ready_for_merge"
+    },
+    merge_queue: {
+        complete: {
+            target_stage: "closed",
+            next_action: "none"
+        }
+    },
+    defaults: {
+        registered_next_action: "run_prime_or_feature_plan"
+    },
+    legacy_aliases: {
+        g0: "prime",
+        m1: "readiness",
+        m2: "integration"
+    }
+};
+export function loadProjectFlowContract(projectRoot) {
+    const contractPath = findProjectFlowContractPath(projectRoot);
+    if (!contractPath) {
+        return defaultFlowContract;
+    }
+    return normalizeFlowContract(readFlowContractObject(contractPath), contractPath);
+}
+export function flowContractForState(state) {
+    if (!state.flow_contract) {
+        return defaultFlowContract;
+    }
+    if (typeof state.flow_contract !== "object" || Array.isArray(state.flow_contract)) {
+        return defaultFlowContract;
+    }
+    return normalizeFlowContract(state.flow_contract, "state.flow_contract");
+}
+export function normalizeStage(value, contract) {
+    return contract.legacy_aliases[value] ?? value;
+}
+export function isAllowedStage(value, contract = defaultFlowContract) {
+    return Object.prototype.hasOwnProperty.call(contract.stages, normalizeStage(value, contract));
+}
+export function requireContractStage(value, contract = defaultFlowContract) {
+    const stage = normalizeStage(value, contract);
+    if (!Object.prototype.hasOwnProperty.call(contract.stages, stage)) {
+        throw new AppError("validation", `Unknown protocol stage: ${value}`, 2, {
+            stage: value,
+            flow_contract_id: contract.id,
+            allowed: Object.keys(contract.stages)
+        });
+    }
+    return stage;
+}
+export function canTransition(from, to, contract = defaultFlowContract) {
+    const normalizedFrom = requireContractStage(from, contract);
+    const normalizedTo = requireContractStage(to, contract);
+    if (normalizedTo === "cancelled") {
+        return !contract.stages[normalizedFrom]?.terminal;
+    }
+    return contract.transitions[normalizedFrom]?.includes(normalizedTo) ?? false;
+}
+function normalizeFlowContract(value, label) {
+    const id = requireString(value.id, `${label}.id`);
+    const version = requireNumber(value.version, `${label}.version`);
+    const stages = normalizeStages(value.stages, `${label}.stages`);
+    const legacyAliases = normalizeStringMap(value.legacy_aliases ?? {}, `${label}.legacy_aliases`);
+    const transitions = normalizeTransitions(value.transitions, `${label}.transitions`, stages, legacyAliases);
+    const readiness = normalizeReadiness(value.readiness, `${label}.readiness`, stages, legacyAliases);
+    const mergeQueue = normalizeMergeQueue(value.merge_queue, `${label}.merge_queue`, stages, legacyAliases);
+    const defaults = normalizeDefaults(value.defaults, `${label}.defaults`);
+    return { id, version, stages, transitions, readiness, merge_queue: mergeQueue, defaults, legacy_aliases: legacyAliases };
+}
+function findProjectFlowContractPath(projectRoot) {
+    const basePath = path.join(projectRoot, ".memory-bank", "dd-flow", "flow-contract");
+    for (const extension of [".json", ".yaml", ".yml"]) {
+        const candidate = `${basePath}${extension}`;
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function readFlowContractObject(file) {
+    const raw = fs.readFileSync(file, "utf8");
+    if (file.endsWith(".json")) {
+        return parseJsonObject(raw, file);
+    }
+    const value = parseYaml(raw);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AppError("validation", `${file} must contain an object`, 2);
+    }
+    return value;
+}
+function normalizeStages(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AppError("validation", `${label} must be an object`, 2);
+    }
+    const stages = {};
+    for (const [stage, config] of Object.entries(value)) {
+        if (!config || typeof config !== "object" || Array.isArray(config)) {
+            throw new AppError("validation", `${label}.${stage} must be an object`, 2);
+        }
+        const terminal = config.terminal;
+        stages[stage] = { terminal: typeof terminal === "boolean" ? terminal : false };
+    }
+    if (!stages.registered || !stages.closed || !stages.cancelled) {
+        throw new AppError("validation", `${label} must include registered, closed, and cancelled stages`, 2);
+    }
+    return stages;
+}
+function normalizeTransitions(value, label, stages, aliases) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AppError("validation", `${label} must be an object`, 2);
+    }
+    const transitions = {};
+    for (const [from, tos] of Object.entries(value)) {
+        const normalizedFrom = aliases[from] ?? from;
+        requireKnownStage(normalizedFrom, stages, `${label}.${from}`);
+        if (!Array.isArray(tos) || tos.some((to) => typeof to !== "string")) {
+            throw new AppError("validation", `${label}.${from} must be a string array`, 2);
+        }
+        transitions[normalizedFrom] = tos.map((to) => {
+            const normalizedTo = aliases[to] ?? to;
+            requireKnownStage(normalizedTo, stages, `${label}.${from}`);
+            return normalizedTo;
+        });
+    }
+    return transitions;
+}
+function normalizeReadiness(value, label, stages, aliases) {
+    const object = requireObject(value, label);
+    const command = requireString(object.command, `${label}.command`);
+    if (command !== "ready-for-merge") {
+        throw new AppError("validation", `${label}.command must be ready-for-merge`, 2);
+    }
+    if (!Array.isArray(object.allowed_from) || object.allowed_from.some((stage) => typeof stage !== "string")) {
+        throw new AppError("validation", `${label}.allowed_from must be a string array`, 2);
+    }
+    const allowedFrom = object.allowed_from.map((stage) => normalizeKnownStage(stage, stages, aliases, `${label}.allowed_from`));
+    const targetStage = normalizeKnownStage(requireString(object.target_stage, `${label}.target_stage`), stages, aliases, label);
+    return { command, allowed_from: allowedFrom, target_stage: targetStage };
+}
+function normalizeMergeQueue(value, label, stages, aliases) {
+    const object = requireObject(value, label);
+    const complete = requireObject(object.complete, `${label}.complete`);
+    return {
+        complete: {
+            target_stage: normalizeKnownStage(requireString(complete.target_stage, `${label}.complete.target_stage`), stages, aliases, label),
+            next_action: requireString(complete.next_action, `${label}.complete.next_action`)
+        }
+    };
+}
+function normalizeDefaults(value, label) {
+    const object = requireObject(value, label);
+    return { registered_next_action: requireString(object.registered_next_action, `${label}.registered_next_action`) };
+}
+function normalizeStringMap(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AppError("validation", `${label} must be an object`, 2);
+    }
+    const output = {};
+    for (const [key, mapValue] of Object.entries(value)) {
+        if (typeof mapValue !== "string" || mapValue.length === 0) {
+            throw new AppError("validation", `${label}.${key} must be a non-empty string`, 2);
+        }
+        output[key] = mapValue;
+    }
+    return output;
+}
+function requireObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AppError("validation", `${label} must be an object`, 2);
+    }
+    return value;
+}
+function requireString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new AppError("validation", `${label} must be a non-empty string`, 2);
+    }
+    return value;
+}
+function requireNumber(value, label) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new AppError("validation", `${label} must be a positive integer`, 2);
+    }
+    return value;
+}
+function normalizeKnownStage(value, stages, aliases, label) {
+    const normalized = aliases[value] ?? value;
+    requireKnownStage(normalized, stages, label);
+    return normalized;
+}
+function requireKnownStage(value, stages, label) {
+    if (!Object.prototype.hasOwnProperty.call(stages, value)) {
+        throw new AppError("validation", `${label} references unknown stage: ${value}`, 2);
+    }
+}

package/dist/domain/validation.js

@@ -0,0 +1,91 @@
+import { AppError } from "../shared/errors.js";
+import { allowedPlanKinds, allowedPlanStatuses, isAllowedStage } from "./contracts.js";
+import { normalizeStage } from "./flow-contract.js";
+export function requireStage(value, contract) {
+    if (!isAllowedStage(value, contract)) {
+        throw new AppError("validation", `Unknown protocol stage: ${value}`, 2);
+    }
+    return contract ? normalizeStage(value, contract) : value;
+}
+export function validatePlan(input, expectedProtocolId) {
+    const plan = input;
+    if (!plan || typeof plan !== "object" || Array.isArray(plan)) {
+        throw new AppError("validation", "Plan must be a JSON object", 2);
+    }
+    requireString(plan.schema_version, "schema_version");
+    requireString(plan.plan_id, "plan_id");
+    requireString(plan.protocol_id, "protocol_id");
+    requireString(plan.title, "title");
+    if (expectedProtocolId && plan.protocol_id !== expectedProtocolId) {
+        throw new AppError("validation", "Plan protocol_id does not match command protocol id", 2, {
+            expectedProtocolId,
+            actualProtocolId: plan.protocol_id
+        });
+    }
+    if (!Array.isArray(plan.items)) {
+        throw new AppError("validation", "Plan items must be an array", 2);
+    }
+    const ids = new Set();
+    const items = plan.items.map((item, index) => validatePlanItem(item, index));
+    for (const item of items) {
+        if (ids.has(item.id)) {
+            throw new AppError("validation", `Duplicate plan item id: ${item.id}`, 2);
+        }
+        ids.add(item.id);
+    }
+    for (const item of items) {
+        for (const dep of item.depends_on) {
+            if (!ids.has(dep)) {
+                throw new AppError("validation", `Plan item ${item.id} depends on missing item ${dep}`, 2);
+            }
+        }
+    }
+    return { ...plan, items };
+}
+function validatePlanItem(input, index) {
+    const item = input;
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+        throw new AppError("validation", `Plan item ${index} must be an object`, 2);
+    }
+    const id = requireString(item.id, `items[${index}].id`);
+    const kind = requireString(item.kind, `items[${index}].kind`);
+    if (!allowedPlanKinds.includes(kind)) {
+        throw new AppError("validation", `Invalid plan item kind for ${id}: ${kind}`, 2);
+    }
+    const status = requireString(item.status, `items[${index}].status`);
+    if (!allowedPlanStatuses.includes(status)) {
+        throw new AppError("validation", `Invalid plan item status for ${id}: ${status}`, 2);
+    }
+    if (!Array.isArray(item.depends_on) || item.depends_on.some((dep) => typeof dep !== "string")) {
+        throw new AppError("validation", `Plan item ${id} depends_on must be a string array`, 2);
+    }
+    if (!Array.isArray(item.evidence) || item.evidence.some((entry) => typeof entry !== "string")) {
+        throw new AppError("validation", `Plan item ${id} evidence must be a string array`, 2);
+    }
+    return {
+        id,
+        kind: kind,
+        title: requireString(item.title, `items[${index}].title`),
+        status: status,
+        depends_on: item.depends_on,
+        stage: requireString(item.stage, `items[${index}].stage`),
+        required: requireBoolean(item.required, `items[${index}].required`),
+        owner: requireString(item.owner, `items[${index}].owner`),
+        summary: typeof item.summary === "string" ? item.summary : "",
+        evidence: item.evidence,
+        ...(typeof item.block_reason === "string" ? { block_reason: item.block_reason } : {}),
+        ...(typeof item.user_required === "boolean" ? { user_required: item.user_required } : {})
+    };
+}
+function requireString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new AppError("validation", `${label} must be a non-empty string`, 2);
+    }
+    return value;
+}
+function requireBoolean(value, label) {
+    if (typeof value !== "boolean") {
+        throw new AppError("validation", `${label} must be a boolean`, 2);
+    }
+    return value;
+}

package/dist/protocol/local-files.js

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import path from "node:path";
+import { schemaVersion } from "../domain/contracts.js";
+import { loadProjectFlowContract } from "../domain/flow-contract.js";
+import { ensureDir, planJsonPath, protocolDir, stateJsonPath } from "../storage/paths.js";
+export function ensureProtocolFiles(input) {
+    const storageRoot = input.storageRoot ?? input.projectRoot;
+    const dir = protocolDir(storageRoot, input.protocolId);
+    ensureDir(dir);
+    const summaryPath = path.join(dir, "summary.md");
+    if (!fs.existsSync(summaryPath)) {
+        fs.writeFileSync(summaryPath, [
+            "---",
+            `file: '.memory-bank/protocol/${input.protocolId}/summary.md'`,
+            `description: 'Protocol trace for ${input.protocolId}.'`,
+            `purpose: 'Read for the active dd-flow protocol trace, current stage, evidence, and closure state.'`,
+            "version: '0.1.0'",
+            `date: '${input.now.slice(0, 10)}'`,
+            "status: 'ACTIVE'",
+            "---",
+            "",
+            `# ${input.protocolId}`,
+            "",
+            `Registered by handshake id \`${input.handshakeId}\`.`,
+            ""
+        ].join("\n"));
+    }
+    const statePath = stateJsonPath(storageRoot, input.protocolId);
+    const existing = readStateIfExists(statePath);
+    const flowContract = existing?.flow_contract ?? loadProjectFlowContract(input.projectRoot);
+    const state = existing ??
+        {
+            schema_version: schemaVersion,
+            protocol_id: input.protocolId,
+            project_root: input.projectRoot,
+            status: "registered",
+            stage: "registered",
+            next_action: flowContract.defaults.registered_next_action,
+            route: {
+                planning: "feature_plan",
+                git: "feature_worktree",
+                delivery: "local",
+                ci: "none"
+            },
+            workspace: {
+                integration_branch: null,
+                feature_branch: null,
+                worktree_path: null
+            },
+            plan: {
+                plan_id: null,
+                total: 0,
+                done: 0,
+                blocked: 0
+            },
+            blockers: [],
+            active_def: [],
+            flow_contract: flowContract,
+            updated_at: input.now
+        };
+    writeState(statePath, { ...state, flow_contract: flowContract, updated_at: input.now });
+    return { ...state, flow_contract: flowContract, updated_at: input.now };
+}
+export function ensureRuntimeProtocolFiles(input) {
+    ensureDir(input.runtimeDir);
+    const metadataPath = path.join(input.runtimeDir, "metadata.json");
+    if (!fs.existsSync(metadataPath)) {
+        fs.writeFileSync(metadataPath, `${JSON.stringify({ protocol_id: input.protocolId, handshake_id: input.handshakeId, project_root: input.projectRoot }, null, 2)}\n`);
+    }
+    const statePath = path.join(input.runtimeDir, "state.json");
+    const existing = readStateIfExists(statePath);
+    const flowContract = existing?.flow_contract ?? loadProjectFlowContract(input.projectRoot);
+    const state = existing ??
+        {
+            schema_version: schemaVersion,
+            protocol_id: input.protocolId,
+            project_root: input.projectRoot,
+            status: "registered",
+            stage: "registered",
+            next_action: flowContract.defaults.registered_next_action,
+            route: {
+                planning: "feature_plan",
+                git: "feature_worktree",
+                delivery: "local",
+                ci: "none"
+            },
+            workspace: {
+                integration_branch: null,
+                feature_branch: null,
+                worktree_path: null
+            },
+            plan: {
+                plan_id: null,
+                total: 0,
+                done: 0,
+                blocked: 0
+            },
+            blockers: [],
+            active_def: [],
+            flow_contract: flowContract,
+            updated_at: input.now
+        };
+    const workspace = input.workspacePath ? { ...state.workspace, worktree_path: input.workspacePath } : state.workspace;
+    const nextState = { ...state, workspace, flow_contract: flowContract, updated_at: input.now };
+    writeState(statePath, nextState);
+    return nextState;
+}
+export function readState(projectRoot, protocolId) {
+    return readStateFile(stateJsonPath(projectRoot, protocolId), protocolId);
+}
+export function readStateFile(file, protocolId) {
+    const state = readStateIfExists(file);
+    if (!state) {
+        throw new Error(`Missing state.json for protocol ${protocolId}`);
+    }
+    return state;
+}
+export function writeState(file, state) {
+    fs.writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`);
+}
+export function readPlan(projectRoot, protocolId) {
+    return readPlanFile(planJsonPath(projectRoot, protocolId));
+}
+export function readPlanFile(file) {
+    if (!fs.existsSync(file)) {
+        return undefined;
+    }
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+export function writePlan(projectRoot, protocolId, plan) {
+    writePlanFile(planJsonPath(projectRoot, protocolId), plan);
+}
+export function writePlanFile(file, plan) {
+    fs.writeFileSync(file, `${JSON.stringify(plan, null, 2)}\n`);
+}
+function readStateIfExists(file) {
+    if (!fs.existsSync(file)) {
+        return undefined;
+    }
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+}

package/dist/runtime/context.js

@@ -0,0 +1,11 @@
+import { getDatabase } from "../storage/database.js";
+import { resolveDdFlowHome } from "../storage/paths.js";
+export function createContext(env) {
+    const ddFlowHome = resolveDdFlowHome(env);
+    return {
+        ddFlowHome,
+        db: getDatabase(ddFlowHome),
+        env,
+        now: () => new Date().toISOString()
+    };
+}