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

package/dist/schemas/global-dashboard-data.schema.json

@@ -4,7 +4,18 @@
   "title": "dd-flow global dashboard data",
   "type": "object",
   "additionalProperties": true,
-  "required": ["schema_id", "generated_at", "target_language", "page", "metrics", "project_cards", "warnings"],
+  "required": [
+    "schema_id",
+    "generated_at",
+    "target_language",
+    "page",
+    "metrics",
+    "supported_summary_versions",
+    "summary_version_groups",
+    "unsupported_projects",
+    "project_cards",
+    "warnings"
+  ],
   "properties": {
     "schema_id": { "const": "dd-flow/global-dashboard-data@1" },
     "generated_at": { "type": "string", "format": "date-time" },
@@ -12,6 +23,9 @@
     "page": { "$ref": "#/definitions/page" },
     "links": { "type": "object", "additionalProperties": { "$ref": "#/definitions/link" } },
     "metrics": { "type": "array", "items": { "$ref": "#/definitions/metric" } },
+    "supported_summary_versions": { "type": "array", "items": { "$ref": "#/definitions/summaryVersion" } },
+    "summary_version_groups": { "type": "array", "items": { "$ref": "#/definitions/summaryVersionGroup" } },
+    "unsupported_projects": { "type": "array", "items": { "$ref": "#/definitions/unsupportedProject" } },
     "project_cards": { "type": "array", "items": { "$ref": "#/definitions/card" } },
     "warnings": { "type": "array" }
   },
@@ -55,14 +69,58 @@
     "card": {
       "type": "object",
       "additionalProperties": true,
-      "required": ["id", "title", "display_status", "action_level", "metrics"],
+      "required": ["id", "title", "display_status", "action_level", "lifecycle_summary", "resource_summary", "metrics"],
       "properties": {
         "id": { "type": "string", "minLength": 1 },
         "title": { "type": "string", "minLength": 1 },
         "display_status": { "type": "string", "minLength": 1 },
         "action_level": { "type": "string", "enum": ["none", "watch", "actionable", "blocked"] },
+        "lifecycle_summary": { "type": "object", "additionalProperties": true },
+        "resource_summary": { "type": "object", "additionalProperties": true },
         "metrics": { "type": "object" }
       }
+    },
+    "summaryVersion": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["schema_id", "schema_version", "label", "status"],
+      "properties": {
+        "schema_id": { "type": "string", "minLength": 1 },
+        "schema_version": { "type": ["string", "null"] },
+        "label": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "minLength": 1 }
+      }
+    },
+    "summaryVersionGroup": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["schema_id", "schema_version", "compatible", "count", "project_ids", "project_names"],
+      "properties": {
+        "schema_id": { "type": "string", "minLength": 1 },
+        "schema_version": { "type": "string", "minLength": 1 },
+        "compatible": { "type": "boolean" },
+        "count": { "type": "integer", "minimum": 0 },
+        "project_ids": { "type": "array", "items": { "type": "string" } },
+        "project_names": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "unsupportedProject": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "title", "root", "status", "display_status", "reason", "summary_path"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "root": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "minLength": 1 },
+        "display_status": { "const": "unsupported" },
+        "reason": { "type": "string", "minLength": 1 },
+        "detail": { "type": "string" },
+        "summary_schema_id": { "type": ["string", "null"] },
+        "summary_schema_version": { "type": ["string", "null"] },
+        "summary_path": { "type": "string", "minLength": 1 },
+        "install_hint": { "type": ["string", "null"] }
+      }
     }
   }
 }

package/dist/schemas/mb-upgrade-migration-report.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/mb-upgrade-migration-report@1",
+  "title": "mb-upgrade runtime/home migration report",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "ok",
+    "schema_id",
+    "generated_at",
+    "project",
+    "migration",
+    "backup",
+    "active_state",
+    "primary_data",
+    "derived_artifacts",
+    "verification"
+  ],
+  "properties": {
+    "ok": { "const": true },
+    "schema_id": { "const": "dd-flow/mb-upgrade-migration-report@1" },
+    "generated_at": { "type": "string", "minLength": 1 },
+    "project": {
+      "type": "object",
+      "required": ["id", "root", "memory_bank_version"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "root": { "type": "string", "minLength": 1 },
+        "memory_bank_version": { "type": ["string", "null"] }
+      }
+    },
+    "migration": {
+      "type": "object",
+      "required": [
+        "mode",
+        "status",
+        "source_memory_bank_version",
+        "target_memory_bank_version",
+        "adjacent_only",
+        "chain",
+        "blocked_reasons"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "mode": { "const": "mb-upgrade-only" },
+        "status": { "enum": ["ready", "blocked", "noop", "completed", "failed", "degraded"] },
+        "source_memory_bank_version": { "type": "string", "minLength": 1 },
+        "target_memory_bank_version": { "type": "string", "minLength": 1 },
+        "adjacent_only": { "const": true },
+        "chain": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "from", "to", "status"],
+            "additionalProperties": true,
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "from": { "type": "string", "minLength": 1 },
+              "to": { "type": "string", "minLength": 1 },
+              "status": { "enum": ["planned", "applied", "skipped", "failed", "blocked"] }
+            }
+          }
+        },
+        "blocked_reasons": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "backup": {
+      "type": "object",
+      "required": ["status", "path", "created_at", "rollback_route"],
+      "additionalProperties": true,
+      "properties": {
+        "status": { "enum": ["present", "planned", "missing"] },
+        "path": { "type": ["string", "null"] },
+        "created_at": { "type": ["string", "null"] },
+        "rollback_route": { "type": "string", "minLength": 1 }
+      }
+    },
+    "active_state": { "type": "object", "additionalProperties": true },
+    "primary_data": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "derived_artifacts": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "verification": { "type": "object", "additionalProperties": true }
+  }
+}

package/dist/schemas/project-dashboard-data.schema.json

@@ -4,7 +4,7 @@
   "title": "dd-flow project dashboard data",
   "type": "object",
   "additionalProperties": true,
-  "required": ["schema_id", "generated_at", "target_language", "page", "project", "metrics", "protocol_cards", "warnings"],
+  "required": ["schema_id", "generated_at", "target_language", "page", "project", "metrics", "lifecycle_summary", "resource_summary", "protocol_cards", "warnings"],
   "properties": {
     "schema_id": { "const": "dd-flow/project-dashboard-data@1" },
     "generated_at": { "type": "string", "format": "date-time" },
@@ -24,8 +24,11 @@
     },
     "links": { "type": "object", "additionalProperties": { "$ref": "#/definitions/link" } },
     "metrics": { "type": "array", "items": { "$ref": "#/definitions/metric" } },
+    "lifecycle_summary": { "type": "object", "additionalProperties": true },
+    "resource_summary": { "type": "object", "additionalProperties": true },
     "protocol_cards": { "type": "array", "items": { "$ref": "#/definitions/protocolCard" } },
     "review_runs": { "type": "array", "items": { "$ref": "#/definitions/reviewRun" } },
+    "queued_protocols": { "type": "array" },
     "merge_queue": { "type": "array" },
     "sessions": { "type": "array" },
     "locks": { "type": "array" },
@@ -71,16 +74,37 @@
     "protocolCard": {
       "type": "object",
       "additionalProperties": true,
-      "required": ["id", "short_id", "display_status", "action_level", "current_stage", "href"],
+      "required": ["id", "short_id", "display_status", "action_level", "lifecycle", "current_stage", "href"],
       "properties": {
         "id": { "type": "string", "minLength": 1 },
         "short_id": { "type": "string", "minLength": 1 },
         "display_status": { "type": "string", "minLength": 1 },
         "action_level": { "type": "string", "enum": ["none", "watch", "actionable", "blocked"] },
+        "lifecycle": { "$ref": "#/definitions/lifecycle" },
+        "lifecycle_stage": { "type": "string" },
+        "lifecycle_status": { "type": "string" },
+        "resource": { "type": "object", "additionalProperties": true },
         "current_stage": { "type": "string", "minLength": 1 },
         "href": { "type": "string", "minLength": 1 }
       }
     },
+    "lifecycle": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["flow", "stage", "status", "terminal", "raw_stage", "raw_status"],
+      "properties": {
+        "flow": { "type": "string", "minLength": 1 },
+        "stage": { "type": "string", "minLength": 1 },
+        "substage": { "type": ["string", "null"] },
+        "status": { "type": "string", "minLength": 1 },
+        "terminal": { "type": "boolean" },
+        "legacy_stage": { "type": ["string", "null"] },
+        "legacy_status": { "type": ["string", "null"] },
+        "raw_stage": { "type": "string", "minLength": 1 },
+        "raw_status": { "type": "string", "minLength": 1 },
+        "queue_status": { "type": ["string", "null"] }
+      }
+    },
     "reviewRun": {
       "type": "object",
       "additionalProperties": true,

package/dist/schemas/project-summary.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "dd-flow/project-summary@1",
+  "title": "dd-flow project summary",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_id",
+    "schema_version",
+    "generated_at",
+    "project_id",
+    "name",
+    "root",
+    "root_exists",
+    "status",
+    "memorybank_version",
+    "cli_version",
+    "engine_version",
+    "summary_path",
+    "protocol_counts",
+    "active_protocols",
+    "waiting_items",
+    "resource_summary",
+    "warnings",
+    "last_activity_at"
+  ],
+  "properties": {
+    "schema_id": { "const": "dd-flow/project-summary@1" },
+    "schema_version": { "const": "1.0.0" },
+    "generated_at": { "type": "string", "minLength": 1 },
+    "project_id": { "type": "string", "minLength": 1 },
+    "name": { "type": "string", "minLength": 1 },
+    "root": { "type": "string", "minLength": 1 },
+    "root_exists": { "type": "boolean" },
+    "status": { "type": "string", "minLength": 1 },
+    "memorybank_version": { "type": ["string", "null"] },
+    "memorybank_status": { "type": "string" },
+    "flow_pack_status": { "type": "string" },
+    "required_engine_range": { "type": ["string", "null"] },
+    "cli_version": { "type": "string", "minLength": 1 },
+    "engine_version": { "type": ["string", "null"] },
+    "engine_status": { "type": "string" },
+    "summary_path": { "type": "string", "minLength": 1 },
+    "dashboard_path": { "type": "string" },
+    "protocol_counts": {
+      "type": "object",
+      "required": ["active", "waiting", "done", "total"],
+      "additionalProperties": true,
+      "properties": {
+        "active": { "type": "integer", "minimum": 0 },
+        "waiting": { "type": "integer", "minimum": 0 },
+        "done": { "type": "integer", "minimum": 0 },
+        "total": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "active_protocols": { "type": "array" },
+    "waiting_items": { "type": "array" },
+    "resource_summary": {
+      "type": "object",
+      "required": ["queue", "locks", "waiters", "sessions", "open_defs"],
+      "additionalProperties": true,
+      "properties": {
+        "queue": { "type": "integer", "minimum": 0 },
+        "locks": { "type": "integer", "minimum": 0 },
+        "waiters": { "type": "integer", "minimum": 0 },
+        "sessions": { "type": "integer", "minimum": 0 },
+        "open_defs": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "warnings": { "type": "array" },
+    "last_activity_at": { "type": "string", "minLength": 1 }
+  }
+}

package/dist/schemas/protocol-dashboard-data.schema.json

@@ -4,7 +4,7 @@
   "title": "dd-flow protocol dashboard data",
   "type": "object",
   "additionalProperties": true,
-  "required": ["schema_id", "generated_at", "target_language", "page", "project", "protocol", "primary_run_id", "run_history", "stage_pipeline", "metrics", "warnings"],
+  "required": ["schema_id", "generated_at", "target_language", "page", "project", "protocol", "resource", "primary_run_id", "run_history", "stage_pipeline", "metrics", "warnings"],
   "properties": {
     "schema_id": { "const": "dd-flow/protocol-dashboard-data@1" },
     "generated_at": { "type": "string", "format": "date-time" },
@@ -14,17 +14,23 @@
     "protocol": {
       "type": "object",
       "additionalProperties": true,
-      "required": ["id", "short_id", "raw_status", "raw_stage", "display_status", "action_level", "updated_at"],
+      "required": ["id", "short_id", "lifecycle", "raw_status", "raw_stage", "display_status", "action_level", "updated_at"],
       "properties": {
         "id": { "type": "string", "minLength": 1 },
         "short_id": { "type": "string", "minLength": 1 },
         "raw_status": { "type": "string", "minLength": 1 },
         "raw_stage": { "type": "string", "minLength": 1 },
+        "lifecycle": { "$ref": "#/definitions/lifecycle" },
+        "lifecycle_stage": { "type": "string" },
+        "lifecycle_status": { "type": "string" },
         "display_status": { "type": "string", "minLength": 1 },
         "action_level": { "type": "string", "enum": ["none", "watch", "actionable", "blocked"] },
         "updated_at": { "type": "string", "minLength": 1 }
       }
     },
+    "resource": { "type": "object", "additionalProperties": true },
+    "queue_item": { "type": ["object", "null"], "additionalProperties": true },
+    "claim": { "type": ["object", "null"], "additionalProperties": true },
     "links": { "type": "object", "additionalProperties": { "$ref": "#/definitions/link" } },
     "primary_run_id": { "type": ["string", "null"] },
     "primary_run_reason": { "type": "string" },
@@ -84,6 +90,23 @@
         "display_status": { "type": "string", "minLength": 1 },
         "stages": { "type": "array" }
       }
+    },
+    "lifecycle": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["flow", "stage", "status", "terminal", "raw_stage", "raw_status"],
+      "properties": {
+        "flow": { "type": "string", "minLength": 1 },
+        "stage": { "type": "string", "minLength": 1 },
+        "substage": { "type": ["string", "null"] },
+        "status": { "type": "string", "minLength": 1 },
+        "terminal": { "type": "boolean" },
+        "legacy_stage": { "type": ["string", "null"] },
+        "legacy_status": { "type": ["string", "null"] },
+        "raw_stage": { "type": "string", "minLength": 1 },
+        "raw_status": { "type": "string", "minLength": 1 },
+        "queue_status": { "type": ["string", "null"] }
+      }
     }
   }
 }

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

@@ -135,13 +135,14 @@
     "flowPack": {
       "type": ["object", "null"],
       "additionalProperties": true,
-      "required": ["manifest_path", "schema_id", "pack_version", "source_commit", "canon_version_at_source_commit", "status", "canonical_only_files"],
+      "required": ["manifest_path", "schema_id", "pack_version", "source_commit", "canon_version_at_source_commit", "flow_contract", "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"] },
+        "flow_contract": { "type": ["string", "null"] },
         "status": { "type": "string", "enum": ["present", "missing", "invalid", "degraded"] },
         "reason": { "type": "string" },
         "canonical_only_files": {
@@ -153,10 +154,11 @@
     "drift": {
       "type": ["object", "null"],
       "additionalProperties": true,
-      "required": ["memory_bank_version", "flow_pack_commit", "overall", "next_action"],
+      "required": ["memory_bank_version", "flow_pack_commit", "flow_contract", "overall", "next_action"],
       "properties": {
         "memory_bank_version": { "$ref": "#/definitions/comparison" },
         "flow_pack_commit": { "$ref": "#/definitions/comparison" },
+        "flow_contract": { "$ref": "#/definitions/comparison" },
         "overall": {
           "type": "string",
           "enum": ["same", "behind", "ahead", "diverged", "missing", "invalid", "unknown", "not_applicable"]

package/dist/services/cleanup.js

@@ -13,6 +13,7 @@ const actionKinds = new Set([
     "cancel_queue_job",
     "close_flow_session",
     "expire_lane_lock",
+    "expire_lane_waiter",
     "close_worktree_record"
 ]);
 export function cleanupScan(context, input) {
@@ -98,6 +99,18 @@ export function cleanupScan(context, input) {
             action: { kind: "expire_lane_lock", project_id: project.id, lock_id: lock.id }
         });
     }
+    const expiredWaiters = context.db.all(`SELECT id, lane, worker_id, expires_at FROM lane_waiters
+     WHERE project_id = ? AND status = 'queued' AND expires_at IS NOT NULL AND expires_at <= ?
+     ORDER BY id ASC`, [project.id, now]);
+    for (const waiter of expiredWaiters) {
+        pushFinding(findings, actions, "expired_lane_waiter", "warning", {
+            waiter_id: waiter.id,
+            lane: waiter.lane,
+            worker_id: waiter.worker_id,
+            expires_at: waiter.expires_at,
+            action: { kind: "expire_lane_waiter", project_id: project.id, waiter_id: waiter.id }
+        });
+    }
     const staleWorktrees = context.db.all(`SELECT wr.protocol_id, wr.worktree_path FROM worktree_records wr
      JOIN protocols p ON p.id = wr.protocol_id
      WHERE wr.project_id = ?
@@ -285,6 +298,24 @@ function applyAction(context, action, reason, force, now) {
             lock_id: action.lock_id
         };
     }
+    if (action.kind === "expire_lane_waiter" && typeof action.waiter_id === "number") {
+        const result = context.db.run("UPDATE lane_waiters SET status = 'expired', reason = ?, updated_at = ? WHERE project_id = ? AND id = ? AND status = 'queued'", [reason, now, action.project_id, action.waiter_id]);
+        if (result.changes === 1) {
+            appendAudit(context, {
+                projectId: action.project_id,
+                eventType: "lane_waiter.expired",
+                reason,
+                forced: force,
+                payload: { waiter_id: action.waiter_id, source: "cleanup.apply" }
+            });
+        }
+        return {
+            kind: action.kind,
+            changed: result.changes === 1,
+            ...(result.changes === 1 ? {} : { skipped: true, reason: "already_inactive" }),
+            waiter_id: action.waiter_id
+        };
+    }
     if (action.kind === "close_worktree_record" && action.protocol_id) {
         const worktreePath = action.worktree_path ?? context.db.get("SELECT worktree_path FROM worktree_records WHERE project_id = ? AND protocol_id = ?", [action.project_id, action.protocol_id])?.worktree_path;
         const status = worktreePath && fs.existsSync(worktreePath) ? "kept" : "removed";

package/dist/services/cli-operation-classifier.js

@@ -0,0 +1,104 @@
+export function classifyCliOperation(args, env = process.env) {
+    const positional = positionalArgs(args);
+    const [family = null, command = null, action = null] = positional;
+    const operation = [family, command, action].filter(Boolean).join(".") || "help";
+    if (isMbUpgradeMode(args, env)) {
+        return { mode: "mb_upgrade", operation, family, command, action };
+    }
+    if (isRouterNative(args)) {
+        return { mode: "router_native", operation, family, command, action };
+    }
+    if (isReadOnlyDiagnostic(family, command, action)) {
+        return { mode: "read_only_diagnostics", operation, family, command, action };
+    }
+    return { mode: "normal_write", operation, family, command, action };
+}
+function positionalArgs(args) {
+    const positional = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (!value)
+            continue;
+        if (value.startsWith("--")) {
+            if (!value.includes("=") && args[index + 1] && !args[index + 1]?.startsWith("--"))
+                index += 1;
+            continue;
+        }
+        positional.push(value);
+    }
+    return positional;
+}
+export function isReadOnlyCliOperation(args, env = process.env) {
+    return classifyCliOperation(args, env).mode === "read_only_diagnostics";
+}
+export function isMbUpgradeCliOperation(args, env = process.env) {
+    return classifyCliOperation(args, env).mode === "mb_upgrade";
+}
+function isMbUpgradeMode(args, env) {
+    if (env.DD_FLOW_COMPATIBILITY_MODE === "mb-upgrade" || env.DD_FLOW_MB_UPGRADE_MODE === "1") {
+        return true;
+    }
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--compatibility-mode" && args[index + 1] === "mb-upgrade")
+            return true;
+        if (arg === "--mb-upgrade-mode")
+            return true;
+        if (arg?.startsWith("--compatibility-mode="))
+            return arg.slice("--compatibility-mode=".length) === "mb-upgrade";
+    }
+    return false;
+}
+function isRouterNative(args) {
+    const first = args[0];
+    if (!first || first === "--version")
+        return true;
+    if (first === "--help" || first === "-h")
+        return true;
+    if (args.includes("--help") || args.includes("-h"))
+        return true;
+    return ["engine", "version", "schema"].includes(first);
+}
+function isReadOnlyDiagnostic(family, command, action) {
+    if (!family)
+        return true;
+    if (family === "status" || family === "version" || family === "id" || family === "integration")
+        return true;
+    if (family === "canon")
+        return command === "status" || command === "resolve";
+    if (family === "project")
+        return command === "status" || command === "resolve";
+    if (family === "protocol")
+        return ["status", "ready", "blockers", "implement"].includes(command ?? "");
+    if (family === "plan")
+        return command === "status";
+    if (family === "run")
+        return command === "status" || command === "list";
+    if (family === "lane") {
+        return (command === "status" ||
+            command === "waiters" ||
+            (command === "lock" && action === "status") ||
+            (command === "workspace" && action === "check"));
+    }
+    if (family === "merge")
+        return command === "status";
+    if (family === "merge-worker")
+        return command === "status";
+    if (family === "merge-queue")
+        return command === "status";
+    if (family === "migration")
+        return ["plan", "report", "verify"].includes(command ?? "");
+    if (family === "session")
+        return command === "status";
+    if (family === "dashboard")
+        return command === "data" || command === "open";
+    if (family === "memory")
+        return command === "permissions" && action === "preflight";
+    if (family === "codex" && command === "hooks")
+        return action === "print" || action === "status";
+    if (family === "codex" && command === "home")
+        return ["plan", "status", "print-env"].includes(action ?? "");
+    if (family === "worktree")
+        return command === "plan" || command === "status";
+    return false;
+}