@deksden-com/dd-flow-cli 0.1.0

package/dist/services/runs.js

@@ -0,0 +1,359 @@
+import fs from "node:fs";
+import path from "node:path";
+import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
+import { AppError } from "../shared/errors.js";
+import { ensureDir, runtimeRunJsonPath, userFacingRunDir, userFacingRunIndexPath, resolveProjectRoot } from "../storage/paths.js";
+import { appendAudit } from "./audit.js";
+import { registerProject, requireProjectByRoot } from "./projects.js";
+const runSchemaId = "dd-flow/flow-run-index@1";
+const runIdType = "RUN";
+const allowedRunFlowKinds = [
+    "coding",
+    "experiment",
+    "mb-init",
+    "mb-upgrade",
+    "mb-audit",
+    "mb-distill",
+    "mb-upgrade-review",
+    "custom"
+];
+export function startFlowRun(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    registerProject(context, { root: projectRoot });
+    const project = requireProjectByRoot(context, projectRoot);
+    const workspaceRoot = resolveWorkspaceRoot(input.workspaceRoot ?? projectRoot);
+    const flowKind = parseRunFlowKind(input.flowKind);
+    const slug = normalizeSlug(input.slug);
+    const runId = nextRunId(context, slug);
+    const { shortId } = parseFullEntityId(runId);
+    const now = context.now();
+    const runDirAbsolute = userFacingRunDir(workspaceRoot, runId);
+    const runIndexAbsolute = userFacingRunIndexPath(workspaceRoot, runId);
+    const runDirRelative = path.relative(workspaceRoot, runDirAbsolute);
+    const runtimePath = runtimeRunJsonPath(context.ddFlowHome, project.id, runId);
+    const index = {
+        schema_id: runSchemaId,
+        run_id: runId,
+        short_id: shortId,
+        flow_kind: flowKind,
+        subject: {
+            type: requiredPlain(input.subjectType, "subject-type"),
+            id: requiredPlain(input.subjectId, "subject-id")
+        },
+        project: {
+            id: project.id,
+            root: project.root
+        },
+        workspace: {
+            root: workspaceRoot,
+            run_dir: runDirRelative
+        },
+        stage_runs: [],
+        sessions: [],
+        artifacts: [],
+        status: "running",
+        verdict: "pending",
+        next_action: input.nextAction ?? null,
+        created_at: now,
+        updated_at: now
+    };
+    ensureDir(path.dirname(runtimePath));
+    ensureDir(runDirAbsolute);
+    writeJsonFile(runtimePath, index);
+    writeJsonFile(runIndexAbsolute, index);
+    context.db.run(`INSERT INTO flow_runs
+      (id, short_id, slug, project_id, project_root, workspace_root, flow_kind, subject_type, subject_id,
+       status, verdict, next_action, runtime_path, run_dir, run_index_path, index_json, created_at, updated_at, completed_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)`, [
+        runId,
+        shortId,
+        slug,
+        project.id,
+        project.root,
+        workspaceRoot,
+        flowKind,
+        index.subject.type,
+        index.subject.id,
+        index.status,
+        index.verdict,
+        index.next_action,
+        runtimePath,
+        runDirRelative,
+        runIndexAbsolute,
+        JSON.stringify(index),
+        now,
+        now
+    ]);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "flow_run.started",
+        payload: { run_id: runId, flow_kind: flowKind, subject: index.subject, workspace_root: workspaceRoot }
+    });
+    return { ok: true, run: flowRunSummary(requireRunById(context, project.id, runId)), index };
+}
+export function getFlowRunStatus(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    return { ok: true, run: flowRunSummary(run), index: parseRunIndex(run.index_json) };
+}
+export function listFlowRuns(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const runs = context.db
+        .all(`SELECT * FROM flow_runs
+       WHERE project_id = ?
+       ORDER BY updated_at DESC, id DESC`, [project.id])
+        .map(flowRunSummary);
+    return { ok: true, project, runs };
+}
+export function attachFlowRunStage(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = parseRunIndex(run.index_json);
+    const now = context.now();
+    const stage = requiredPlain(input.stage, "stage");
+    const dir = requiredStageDir(input.dir);
+    const status = parseStageStatus(input.status);
+    const existing = index.stage_runs.find((item) => item.stage === stage);
+    const stageRun = {
+        ...(existing ?? { order: index.stage_runs.length + 1 }),
+        stage,
+        dir,
+        status,
+        ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : existing?.data_schema_id ? { data_schema_id: existing.data_schema_id } : {}),
+        updated_at: now
+    };
+    upsertStage(index, stageRun);
+    index.updated_at = now;
+    persistRunIndex(context, project, run, index);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "flow_run.stage_attached",
+        payload: { run_id: run.id, stage, dir, status }
+    });
+    return { ok: true, run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
+}
+export function completeFlowRunStage(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = parseRunIndex(run.index_json);
+    const now = context.now();
+    const stage = requiredPlain(input.stage, "stage");
+    const status = parseStageStatus(input.status);
+    const existing = index.stage_runs.find((item) => item.stage === stage);
+    if (!existing) {
+        throw new AppError("not_found", `Run stage is not attached: ${stage}`, 1, { run_id: run.id, stage });
+    }
+    const stageRun = {
+        ...existing,
+        status,
+        ...(input.stageReport ? { stage_report: input.stageReport } : {}),
+        ...(input.data ? { data: input.data } : {}),
+        ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : {}),
+        ...(input.report ? { report: input.report } : {}),
+        ...(input.aliases && input.aliases.length > 0 ? { artifact_aliases: input.aliases } : {}),
+        updated_at: now
+    };
+    upsertStage(index, stageRun);
+    index.updated_at = now;
+    persistRunIndex(context, project, run, index);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "flow_run.stage_completed",
+        payload: { run_id: run.id, stage, status, stage_report: input.stageReport ?? null, data: input.data ?? null }
+    });
+    return { ok: true, run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
+}
+export function completeFlowRun(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = parseRunIndex(run.index_json);
+    const now = context.now();
+    const status = parseRunStatus(input.status);
+    index.status = status;
+    index.verdict = input.verdict ?? (status === "done" ? "accepted" : status);
+    index.next_action = input.nextAction ?? null;
+    index.updated_at = now;
+    if (["done", "blocked", "cancelled", "failed"].includes(status)) {
+        index.completed_at = now;
+    }
+    persistRunIndex(context, project, run, index);
+    appendAudit(context, {
+        projectId: project.id,
+        eventType: "flow_run.completed",
+        payload: { run_id: run.id, status, verdict: index.verdict, next_action: index.next_action }
+    });
+    return { ok: true, run: flowRunSummary(requireRunById(context, project.id, run.id)), index };
+}
+function persistRunIndex(context, project, run, index) {
+    const runtimePath = runtimeRunJsonPath(context.ddFlowHome, project.id, run.id);
+    const runIndexPath = userFacingRunIndexPath(run.workspace_root, run.id);
+    ensureDir(path.dirname(runtimePath));
+    ensureDir(path.dirname(runIndexPath));
+    writeJsonFile(runtimePath, index);
+    writeJsonFile(runIndexPath, index);
+    context.db.run(`UPDATE flow_runs
+     SET status = ?, verdict = ?, next_action = ?, index_json = ?, runtime_path = ?, run_index_path = ?,
+       updated_at = ?, completed_at = ?
+     WHERE project_id = ? AND id = ?`, [
+        index.status,
+        index.verdict,
+        index.next_action,
+        JSON.stringify(index),
+        runtimePath,
+        runIndexPath,
+        index.updated_at,
+        index.completed_at ?? null,
+        project.id,
+        run.id
+    ]);
+}
+function upsertStage(index, stageRun) {
+    const position = index.stage_runs.findIndex((item) => item.stage === stageRun.stage);
+    if (position === -1) {
+        index.stage_runs.push(stageRun);
+    }
+    else {
+        index.stage_runs[position] = stageRun;
+    }
+    index.stage_runs.sort((a, b) => a.order - b.order);
+}
+function resolveRun(context, projectId, idOrAlias) {
+    if (isFullEntityId(idOrAlias)) {
+        return requireRunById(context, projectId, idOrAlias);
+    }
+    if (isShortEntityId(idOrAlias)) {
+        const matches = context.db.all("SELECT * FROM flow_runs WHERE project_id = ? AND short_id = ? ORDER BY updated_at DESC", [
+            projectId,
+            idOrAlias
+        ]);
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length > 1) {
+            throw new AppError("ambiguous_alias", `Run alias is ambiguous: ${idOrAlias}`, 1, {
+                candidates: matches.map(flowRunSummary)
+            });
+        }
+    }
+    throw new AppError("not_found", `Run is not registered: ${idOrAlias}`, 1, { run_id: idOrAlias });
+}
+function requireRunById(context, projectId, runId) {
+    const run = context.db.get("SELECT * FROM flow_runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!run) {
+        throw new AppError("not_found", `Run is not registered: ${runId}`, 1, { run_id: runId });
+    }
+    return run;
+}
+function nextRunId(context, slug) {
+    const rows = context.db.all("SELECT id FROM flow_runs WHERE id LIKE 'RUN-%'");
+    const max = rows.reduce((value, row) => {
+        try {
+            const parsed = parseFullEntityId(row.id);
+            return parsed.type === runIdType ? Math.max(value, Number(parsed.shortId.slice(4))) : value;
+        }
+        catch {
+            return value;
+        }
+    }, 0);
+    for (let sequence = max + 1; sequence <= 999; sequence += 1) {
+        const id = formatFullId(runIdType, sequence, slug);
+        if (!context.db.get("SELECT id FROM flow_runs WHERE id = ?", [id])) {
+            return id;
+        }
+    }
+    throw new AppError("validation", "RUN id sequence exhausted", 2);
+}
+function flowRunSummary(run) {
+    return {
+        id: run.id,
+        short_id: run.short_id,
+        slug: run.slug,
+        project_id: run.project_id,
+        project_root: run.project_root,
+        workspace_root: run.workspace_root,
+        flow_kind: run.flow_kind,
+        subject: {
+            type: run.subject_type,
+            id: run.subject_id
+        },
+        status: run.status,
+        verdict: run.verdict,
+        next_action: run.next_action,
+        runtime_path: run.runtime_path,
+        run_dir: run.run_dir,
+        run_index_path: run.run_index_path,
+        created_at: run.created_at,
+        updated_at: run.updated_at,
+        completed_at: run.completed_at
+    };
+}
+function parseRunIndex(text) {
+    const index = JSON.parse(text);
+    if (index.schema_id !== runSchemaId) {
+        throw new AppError("validation", `Invalid run index schema: ${String(index.schema_id)}`, 2);
+    }
+    return index;
+}
+function parseRunFlowKind(value) {
+    if (!allowedRunFlowKinds.includes(value)) {
+        throw new AppError("validation", "flow-kind is not supported for run start", 2, {
+            flow_kind: value,
+            allowed: allowedRunFlowKinds
+        });
+    }
+    return value;
+}
+function parseRunStatus(value) {
+    if (!["running", "done", "blocked", "cancelled", "failed"].includes(value)) {
+        throw new AppError("validation", "run status is not supported", 2, {
+            status: value,
+            allowed: ["running", "done", "blocked", "cancelled", "failed"]
+        });
+    }
+    return value;
+}
+function parseStageStatus(value) {
+    if (!["pending", "running", "done", "blocked", "skipped", "failed"].includes(value)) {
+        throw new AppError("validation", "stage status is not supported", 2, {
+            status: value,
+            allowed: ["pending", "running", "done", "blocked", "skipped", "failed"]
+        });
+    }
+    return value;
+}
+function requiredStageDir(value) {
+    const dir = requiredPlain(value, "dir");
+    if (!/^\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(dir)) {
+        throw new AppError("validation", "--dir must use NN-stage-slug format", 2, { dir });
+    }
+    return dir;
+}
+function requiredPlain(value, label) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new AppError("validation", `${label} must not be empty`, 2);
+    }
+    return trimmed;
+}
+function normalizeSlug(value) {
+    const slug = value
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+    if (!slug) {
+        throw new AppError("validation", "--slug must contain at least one ASCII letter or digit", 2);
+    }
+    return slug;
+}
+function resolveWorkspaceRoot(workspaceRoot) {
+    const absolute = path.resolve(workspaceRoot);
+    if (!fs.existsSync(absolute)) {
+        throw new AppError("not_found", `Workspace root does not exist: ${absolute}`, 1);
+    }
+    return fs.realpathSync(absolute);
+}
+function writeJsonFile(file, value) {
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}

package/dist/services/schema-validation.js

@@ -0,0 +1,185 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Ajv } from "ajv/dist/ajv.js";
+import { AppError } from "../shared/errors.js";
+const schemaNamePattern = /^[a-z0-9][a-z0-9-]*$/;
+const mandatoryMbUpgradeReviewAspectIds = [
+    "01-goal-and-delivery",
+    "02-knowledge-preservation",
+    "03-canonical-structure",
+    "04-target-coverage",
+    "05-path-traceability",
+    "06-def-settlement",
+    "07-verification-quality",
+    "08-git-merge-delivery",
+    "09-report-quality",
+    "10-agent-process-quality"
+];
+export function validateSchema(options) {
+    if (!schemaNamePattern.test(options.schemaName)) {
+        throw new AppError("usage", "--schema must be a schema name such as mb-upgrade-review-data", 2);
+    }
+    const schemaResolution = resolveSchema(options);
+    const schema = readJson(schemaResolution.path, "schema");
+    const filePath = path.resolve(options.file);
+    const data = readJson(filePath, "input file");
+    const ajv = new Ajv({ allErrors: true, strict: false, validateFormats: false });
+    const validate = ajv.compile(schema);
+    const valid = validate(data);
+    const errors = valid ? [] : (validate.errors ?? []).map(formatAjvError);
+    const semanticErrors = validateSemanticSchema(options.schemaName, data);
+    const allErrors = [...errors, ...semanticErrors];
+    if (allErrors.length > 0) {
+        throw new AppError("schema_validation", `${path.basename(filePath)} does not match schema`, 2, {
+            schema: schemaResolution,
+            file: filePath,
+            errors: allErrors
+        });
+    }
+    return {
+        ok: true,
+        schema: schemaResolution,
+        file: filePath,
+        errors: []
+    };
+}
+function resolveSchema(options) {
+    const fileName = `${options.schemaName}.schema.json`;
+    const candidates = [];
+    if (options.schemaDir) {
+        candidates.push({ path: path.join(path.resolve(options.schemaDir), fileName), source: "schema_dir" });
+    }
+    else {
+        const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+        candidates.push({ path: path.join(projectRoot, ".memory-bank", "dd-flow", "schemas", fileName), source: "project" });
+        candidates.push({ path: path.join(bundledSchemaDir(), fileName), source: "bundled" });
+    }
+    const found = candidates.find((candidate) => fs.existsSync(candidate.path));
+    if (!found) {
+        throw new AppError("schema_not_found", `Schema not found: ${options.schemaName}`, 2, {
+            schema: options.schemaName,
+            searched: candidates.map((candidate) => candidate.path)
+        });
+    }
+    const schema = readJson(found.path, "schema");
+    const schemaObject = asRecord(schema);
+    const id = schemaObject ? objectValue(schemaObject, "$id") : undefined;
+    return {
+        name: options.schemaName,
+        id: typeof id === "string" ? id : options.schemaName,
+        path: found.path,
+        source: found.source
+    };
+}
+function bundledSchemaDir() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "schemas");
+}
+function readJson(file, label) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        throw new AppError("validation", `Cannot read ${label}: ${file}`, 2, { cause: String(error) });
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new AppError("invalid_json", `Invalid JSON in ${label}: ${file}`, 2, { cause: String(error) });
+    }
+}
+function formatAjvError(error) {
+    return {
+        path: error.instancePath || "/",
+        message: error.message ?? "schema validation failed",
+        keyword: error.keyword
+    };
+}
+function validateSemanticSchema(schemaName, data) {
+    if (schemaName !== "mb-upgrade-review-data") {
+        return [];
+    }
+    const root = asRecord(data);
+    if (!root) {
+        return [];
+    }
+    return validateMbUpgradeReviewData(root);
+}
+function validateMbUpgradeReviewData(root) {
+    const errors = [];
+    const aspects = arrayValue(root, "aspects").filter(isRecord);
+    const findings = arrayValue(root, "findings").filter(isRecord);
+    const overall = recordValue(root, "overall");
+    const verdict = overall ? stringValue(overall, "verdict") : undefined;
+    const aspectIds = aspects.map((aspect) => stringValue(aspect, "id")).filter(isString);
+    for (const id of mandatoryMbUpgradeReviewAspectIds) {
+        const count = aspectIds.filter((value) => value === id).length;
+        if (count !== 1) {
+            errors.push({
+                path: "/aspects",
+                message: `mandatory aspect ${id} must be present exactly once`,
+                keyword: "dd-flow/aspect-id"
+            });
+        }
+    }
+    const aspectIdSet = new Set(aspectIds);
+    const findingIds = new Set(findings.map((finding) => stringValue(finding, "id")).filter(isString));
+    aspects.forEach((aspect, aspectIndex) => {
+        const refs = arrayValue(aspect, "findings").filter(isString);
+        refs.forEach((ref, refIndex) => {
+            if (!findingIds.has(ref)) {
+                errors.push({
+                    path: `/aspects/${aspectIndex}/findings/${refIndex}`,
+                    message: `finding reference does not exist: ${ref}`,
+                    keyword: "dd-flow/finding-ref"
+                });
+            }
+        });
+    });
+    findings.forEach((finding, findingIndex) => {
+        const aspectId = stringValue(finding, "aspect_id");
+        if (aspectId && !aspectIdSet.has(aspectId)) {
+            errors.push({
+                path: `/findings/${findingIndex}/aspect_id`,
+                message: `finding aspect_id does not exist in aspects: ${aspectId}`,
+                keyword: "dd-flow/aspect-ref"
+            });
+        }
+        const severity = stringValue(finding, "severity");
+        const tracking = recordValue(finding, "tracking");
+        const trackingStatus = tracking ? stringValue(tracking, "status") : undefined;
+        if ((verdict === "accepted" || verdict === "accepted_with_deferrals") && severity === "blocking" && trackingStatus !== "fixed_before_report") {
+            errors.push({
+                path: "/overall/verdict",
+                message: "accepted verdict cannot coexist with unresolved blocking findings",
+                keyword: "dd-flow/accepted-blocking"
+            });
+        }
+    });
+    return errors;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function isRecord(value) {
+    return Boolean(asRecord(value));
+}
+function isString(value) {
+    return typeof value === "string";
+}
+function objectValue(record, key) {
+    return record[key];
+}
+function recordValue(record, key) {
+    return asRecord(record[key]);
+}
+function stringValue(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+}
+function arrayValue(record, key) {
+    const value = record[key];
+    return Array.isArray(value) ? value : [];
+}