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

package/dist/services/branch-context.js

@@ -0,0 +1,254 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { requireProjectByRoot } from "./projects.js";
+import { normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
+export function getProtocolBranchContext(context, input) {
+    const resolved = resolveBranchContextInput(context, input);
+    const rows = context.db.all(`SELECT id, project_id, project_root, status, stage, next_action, workspace_json, route_json, active_def_json, updated_at
+     FROM protocols
+     WHERE project_id = ?
+     ORDER BY updated_at ASC, id ASC`, [resolved.project.id]);
+    const queues = new Map(context.db
+        .all(`SELECT protocol_id, status, claimed_by_session_id, claimed_at, attempts_count, updated_at
+         FROM merge_queue
+         WHERE project_id = ?`, [resolved.project.id])
+        .map((row) => [row.protocol_id, row]));
+    const worktrees = new Map(context.db
+        .all(`SELECT protocol_id, integration_branch, feature_branch, base_ref, worktree_path, status
+         FROM worktree_records
+         WHERE project_id = ?`, [resolved.project.id])
+        .map((row) => [row.protocol_id, row]));
+    const sessions = context.db.all(`SELECT protocol_id, worker_id, flow_kind, status, current_stage, next_action
+     FROM flow_sessions
+     WHERE project_id = ? AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [resolved.project.id]);
+    const sessionsByProtocol = new Map();
+    for (const session of sessions) {
+        if (!session.protocol_id)
+            continue;
+        sessionsByProtocol.set(session.protocol_id, [...(sessionsByProtocol.get(session.protocol_id) ?? []), session]);
+    }
+    const candidates = rows.map((row) => summarizeProtocol(row, queues.get(row.id), worktrees.get(row.id), sessionsByProtocol.get(row.id) ?? []));
+    const protocols = candidates.filter((candidate) => protocolMatchesBranch(candidate, resolved));
+    const eligible = protocols.filter((item) => item.bundle_eligible).map((item) => item.id);
+    const notReady = protocols.filter((item) => !item.bundle_eligible && !terminalStage(item.stage) && item.queue_status !== "claimed").map((item) => item.id);
+    const claimed = protocols.filter((item) => item.queue_status === "claimed").map((item) => item.id);
+    const blocked = protocols.filter((item) => item.stage === "blocked" || item.bundle_blockers.length > 0).map((item) => item.id);
+    const diagnostics = branchDiagnostics(resolved);
+    const diagnosticBlockers = diagnostics.filter((item) => item.severity === "error").map((item) => String(item.code));
+    const claimable = eligible.length > 0 && notReady.length === 0 && claimed.length === 0 && blocked.length === 0 && diagnosticBlockers.length === 0;
+    return {
+        ok: true,
+        branch_context: {
+            current_protocol_id: resolved.protocol?.id ?? null,
+            project_id: resolved.project.id,
+            project_root: resolved.project.root,
+            integration_branch: resolved.integrationBranch,
+            feature_branch: resolved.featureBranch,
+            worktree_path: resolved.workspacePath,
+            grouping_key: resolved.groupingKey,
+            git: resolved.git,
+            diagnostics,
+            protocols,
+            merge_bundle: {
+                eligible_protocols: eligible,
+                not_ready_protocols: notReady,
+                claimed_protocols: claimed,
+                blocked_protocols: blocked,
+                claimable,
+                reason: claimable ? "claimable" : bundleReason(eligible, notReady, claimed, blocked, diagnosticBlockers)
+            }
+        }
+    };
+}
+export function requireClaimableBranchBundle(context, input) {
+    const branchContext = getProtocolBranchContext(context, { projectRoot: input.projectRoot, workspacePath: input.workspacePath });
+    const contextBody = branchContext.branch_context;
+    const bundle = contextBody.merge_bundle;
+    if (bundle.claimable !== true) {
+        throw new AppError("merge_bundle_not_claimable", "Branch bundle is not claimable", 1, { branch_context: contextBody });
+    }
+    const protocolIds = Array.isArray(bundle.eligible_protocols) ? bundle.eligible_protocols.map(String) : [];
+    if (protocolIds.length === 0) {
+        throw new AppError("merge_bundle_empty", "Branch bundle has no ready protocols", 1, { branch_context: contextBody });
+    }
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    return { project, branchContext, protocolIds };
+}
+function resolveBranchContextInput(context, input) {
+    if (input.protocolId) {
+        const protocol = context.db.get(`SELECT id, project_id, project_root, status, stage, next_action, workspace_json, route_json, active_def_json, updated_at
+       FROM protocols
+       WHERE id = ?`, [input.protocolId]);
+        if (!protocol) {
+            throw new AppError("not_found", `Protocol is not registered: ${input.protocolId}`, 1, { protocol_id: input.protocolId });
+        }
+        const project = requireProjectByRoot(context, protocol.project_root);
+        const workspace = parseRecord(protocol.workspace_json);
+        const worktree = context.db.get("SELECT * FROM worktree_records WHERE protocol_id = ?", [protocol.id]);
+        const workspacePath = normalizePath(input.workspacePath ?? stringValue(worktree?.worktree_path) ?? stringValue(workspace.worktree_path));
+        const git = gitFacts(workspacePath ?? project.root);
+        const featureBranch = stringValue(worktree?.feature_branch) ?? stringValue(workspace.feature_branch) ?? stringValue(git.actual_branch);
+        return {
+            project,
+            protocol,
+            featureBranch,
+            workspacePath,
+            integrationBranch: stringValue(worktree?.integration_branch) ?? stringValue(workspace.integration_branch),
+            groupingKey: groupingKey(project.id, featureBranch, workspacePath),
+            git: { ...git, matches_runtime: branchMatches(featureBranch, stringValue(git.actual_branch)) }
+        };
+    }
+    if (!input.projectRoot) {
+        throw new AppError("usage", "branch context requires <protocol-id> or --project-root", 2);
+    }
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const workspacePath = normalizePath(input.workspacePath ?? project.root);
+    const git = gitFacts(workspacePath ?? project.root);
+    const featureBranch = stringValue(git.actual_branch);
+    return {
+        project,
+        protocol: null,
+        featureBranch,
+        workspacePath,
+        integrationBranch: null,
+        groupingKey: groupingKey(project.id, featureBranch, workspacePath),
+        git: { ...git, matches_runtime: true }
+    };
+}
+function summarizeProtocol(row, queue, worktree, activeSessions) {
+    const workspace = parseRecord(row.workspace_json);
+    const featureBranch = stringValue(worktree?.feature_branch) ?? stringValue(workspace.feature_branch);
+    const worktreePath = normalizePath(stringValue(worktree?.worktree_path) ?? stringValue(workspace.worktree_path));
+    const activeDef = parseJsonArray(row.active_def_json);
+    const queueStatus = queue?.status ?? null;
+    const bundleBlockers = bundleBlockersFor(row.stage, queueStatus, activeDef.length);
+    return {
+        id: row.id,
+        stage: row.stage,
+        status: row.status,
+        lifecycle: normalizeProtocolLifecycle({ rawStage: row.stage, rawStatus: row.status, queueStatus }),
+        queue_status: queueStatus,
+        queue_claimed_by: queue?.claimed_by_session_id ?? null,
+        active_sessions: activeSessions,
+        integration_branch: stringValue(worktree?.integration_branch) ?? stringValue(workspace.integration_branch),
+        feature_branch: featureBranch,
+        worktree_path: worktreePath,
+        bundle_eligible: ["ready_for_merge", "queued_for_merge"].includes(row.stage) && ["ready", "requeued"].includes(queueStatus ?? "") && activeDef.length === 0,
+        bundle_blockers: bundleBlockers,
+        updated_at: row.updated_at
+    };
+}
+function protocolMatchesBranch(item, resolved) {
+    if (resolved.featureBranch && item.feature_branch) {
+        return item.feature_branch === resolved.featureBranch;
+    }
+    if (resolved.workspacePath && item.worktree_path) {
+        return item.worktree_path === resolved.workspacePath;
+    }
+    return false;
+}
+function gitFacts(workspacePath) {
+    if (!fs.existsSync(workspacePath)) {
+        return { status: "missing_workspace", actual_branch: null, dirty: null, path: workspacePath };
+    }
+    const branch = spawnSync("git", ["-C", workspacePath, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+    if (branch.status !== 0) {
+        return { status: "not_git_checkout", actual_branch: null, dirty: null, path: workspacePath };
+    }
+    const status = spawnSync("git", ["-C", workspacePath, "status", "--porcelain"], { encoding: "utf8" });
+    return {
+        status: "ok",
+        actual_branch: branch.stdout.trim() || null,
+        dirty: status.status === 0 ? status.stdout.trim().length > 0 : null,
+        path: workspacePath
+    };
+}
+function branchDiagnostics(resolved) {
+    const diagnostics = [];
+    if (resolved.git.status !== "ok") {
+        diagnostics.push({ code: "git_workspace_degraded", severity: "warning", summary: `Git workspace status is ${String(resolved.git.status)}` });
+    }
+    if (resolved.featureBranch && resolved.git.actual_branch && resolved.featureBranch !== resolved.git.actual_branch) {
+        diagnostics.push({
+            code: "branch_runtime_mismatch",
+            severity: "error",
+            summary: `Runtime branch ${resolved.featureBranch} does not match Git branch ${String(resolved.git.actual_branch)}.`
+        });
+    }
+    return diagnostics;
+}
+function bundleBlockersFor(stage, queueStatus, activeDefCount) {
+    const blockers = [];
+    if (activeDefCount > 0)
+        blockers.push("active_def");
+    if (stage === "blocked")
+        blockers.push("protocol_blocked");
+    if (queueStatus === "claimed")
+        blockers.push("already_claimed");
+    return blockers;
+}
+function bundleReason(eligible, notReady, claimed, blocked, diagnostics) {
+    if (diagnostics.length > 0)
+        return diagnostics[0] ?? "diagnostic_blocker";
+    if (claimed.length > 0)
+        return "branch_has_claimed_protocols";
+    if (blocked.length > 0)
+        return "branch_has_blocked_protocols";
+    if (notReady.length > 0)
+        return "branch_has_not_ready_protocols";
+    if (eligible.length === 0)
+        return "no_ready_protocols";
+    return "unknown";
+}
+function terminalStage(stage) {
+    return ["closed", "cancelled"].includes(stage);
+}
+function groupingKey(projectId, featureBranch, workspacePath) {
+    if (featureBranch)
+        return `${projectId}:branch:${featureBranch}`;
+    if (workspacePath)
+        return `${projectId}:worktree:${workspacePath}`;
+    return `${projectId}:unknown`;
+}
+function branchMatches(expected, actual) {
+    if (!expected || !actual)
+        return null;
+    return expected === actual;
+}
+function normalizePath(value) {
+    if (!value)
+        return null;
+    const absolute = path.resolve(value);
+    if (fs.existsSync(absolute))
+        return fs.realpathSync(absolute);
+    const parent = path.dirname(absolute);
+    if (fs.existsSync(parent))
+        return path.join(fs.realpathSync(parent), path.basename(absolute));
+    return absolute;
+}
+function parseRecord(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function parseJsonArray(value) {
+    if (typeof value !== "string")
+        return [];
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : null;
+}

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;
+}

package/dist/services/compatibility-preflight.js

@@ -0,0 +1,127 @@
+import { AppError } from "../shared/errors.js";
+import { getCliBuildInfo } from "./build-info.js";
+import { classifyCliOperation } from "./cli-operation-classifier.js";
+import { selectEngine } from "./engines.js";
+import { requireProtocol } from "./protocols.js";
+export function preflightCliCompatibility(context, args, env = process.env) {
+    const classification = classifyCliOperation(args, env);
+    if (classification.mode === "router_native") {
+        return { ok: true, classification, compatibility: null };
+    }
+    const projectRoot = resolveOperationProjectRoot(context, args);
+    if (!projectRoot) {
+        return { ok: true, classification, compatibility: null };
+    }
+    const selection = selectEngine(context, { projectRoot });
+    const compatibility = compatibilityReport(selection, classification);
+    if (classification.mode === "read_only_diagnostics" || classification.mode === "mb_upgrade") {
+        return { ok: true, classification, compatibility };
+    }
+    if (selection.status !== "selected" || !selection.selected) {
+        throw new AppError("compatibility_preflight_failed", "dd-flow compatibility preflight blocked a state-changing command", 1, {
+            compatibility,
+            remediation: remediationForSelection(selection)
+        });
+    }
+    return { ok: true, classification, compatibility };
+}
+export function compatibilityReport(selection, classification) {
+    const build = getCliBuildInfo();
+    const normalWriteAllowed = selection.status === "selected" && Boolean(selection.selected);
+    return {
+        verdict: selection.status === "selected" ? "ok" : "incompatible",
+        memorybank_version: selection.memory_bank_version,
+        router_version: build.version,
+        cli_version: build.version,
+        engine_version: selection.selected?.engine_version ?? selection.selected?.package_version ?? null,
+        engine_resolution: selection.status,
+        required_engine_range: selection.required_range,
+        recommended_engine_version: selection.recommended_version,
+        allowed_modes: normalWriteAllowed
+            ? ["read_only_diagnostics", "normal_write", "mb_upgrade"]
+            : ["read_only_diagnostics", "mb_upgrade"],
+        operation_mode: classification.mode,
+        blocked_operation: classification.mode === "normal_write" && !normalWriteAllowed ? classification.operation : null,
+        install_hint: selection.install_hint,
+        project_root: selection.project_root,
+        diagnostics: selection.diagnostics
+    };
+}
+function remediationForSelection(selection) {
+    return {
+        install_hint: selection.install_hint,
+        mb_upgrade_mode: "Run through mb-upgrade with --compatibility-mode mb-upgrade only when intentionally migrating the project.",
+        diagnostics: selection.diagnostics
+    };
+}
+function resolveOperationProjectRoot(context, args) {
+    const [family, command, ...rest] = args;
+    const parsed = parseLightArgs(rest);
+    const explicitRoot = option(parsed, "project-root") ?? option(parsed, "root");
+    if (explicitRoot)
+        return explicitRoot;
+    if (family === "protocol") {
+        const protocolId = positional(parsed, 0);
+        if (protocolId && command && ["ready-for-merge", "cancel", "status"].includes(command)) {
+            return requireProtocol(context, protocolId).project_root;
+        }
+    }
+    if (family === "transition") {
+        const transitionParsed = parseLightArgs([command ?? "", ...rest]);
+        const protocolId = positional(transitionParsed, 0);
+        return protocolId ? requireProtocol(context, protocolId).project_root : null;
+    }
+    if (family === "plan" && (command === "set" || command === "status")) {
+        const protocolId = positional(parsed, 0);
+        return protocolId ? requireProtocol(context, protocolId).project_root : null;
+    }
+    if (family === "plan" && command === "item") {
+        const protocolId = positional(parsed, 1);
+        return protocolId ? requireProtocol(context, protocolId).project_root : null;
+    }
+    if (family === "merge-queue" && ["complete", "fail", "cancel", "note"].includes(command ?? "")) {
+        const protocolId = positional(parsed, 0);
+        return protocolId ? requireProtocol(context, protocolId).project_root : null;
+    }
+    if (family === "worktree") {
+        const protocolId = option(parsed, "protocol-id");
+        return protocolId ? requireProtocol(context, protocolId).project_root : null;
+    }
+    return null;
+}
+function parseLightArgs(args) {
+    const positional = [];
+    const options = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value?.startsWith("--")) {
+            const equal = value.indexOf("=");
+            if (equal > 2) {
+                const key = value.slice(2, equal);
+                options.set(key, [...(options.get(key) ?? []), value.slice(equal + 1)]);
+                continue;
+            }
+            const key = value.slice(2);
+            const next = args[index + 1];
+            if (!next || next.startsWith("--")) {
+                options.set(key, [...(options.get(key) ?? []), ""]);
+            }
+            else {
+                options.set(key, [...(options.get(key) ?? []), next]);
+                index += 1;
+            }
+        }
+        else if (value) {
+            positional.push(value);
+        }
+    }
+    return { positional, options };
+}
+function option(parsed, key) {
+    const values = parsed.options.get(key);
+    const value = values?.[values.length - 1];
+    return value ? value : null;
+}
+function positional(parsed, index) {
+    return parsed.positional[index] ?? null;
+}

package/dist/services/config.js

@@ -62,6 +62,12 @@ export function projectDashboardJsonPath(context, projectId) {
 export function projectDashboardHtmlPath(context, projectId) {
     return path.join(projectDashboardDir(context.ddFlowHome, projectId), "project-dashboard.html");
 }
+export function projectSummaryDir(context, projectId) {
+    return path.join(projectHome(context.ddFlowHome, projectId), "summary");
+}
+export function projectSummaryJsonPath(context, projectId) {
+    return path.join(projectSummaryDir(context, projectId), "project-summary.json");
+}
 export function protocolDashboardJsonPath(context, projectId, protocolId) {
     return path.join(projectDashboardDir(context.ddFlowHome, projectId), "protocols", `${protocolId}.json`);
 }

package/dist/services/dashboard-targets.js

@@ -0,0 +1,95 @@
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { requireProjectByReference, requireProjectByRoot } from "./projects.js";
+export function resolveDashboardTarget(context, input) {
+    if (input.all) {
+        if (input.action !== "refresh") {
+            throw new AppError("validation", "--all is supported only for dashboard refresh", 2, {
+                preferred_command: "dd-flow dashboard refresh --all",
+                related_commands: relatedDashboardCommands("refresh")
+            });
+        }
+        if (input.project || input.projectRoot || input.protocol || input.global) {
+            throw new AppError("validation", "--all cannot be combined with --project, --project-root, --protocol, or --global", 2, {
+                related_commands: relatedDashboardCommands("refresh")
+            });
+        }
+        return { kind: "all_projects" };
+    }
+    if (input.global && (input.project || input.projectRoot || input.protocol)) {
+        throw new AppError("validation", "--global cannot be combined with project or protocol targets", 2, {
+            related_commands: relatedDashboardCommands(input.action)
+        });
+    }
+    const project = resolveDashboardProject(context, input.project, input.projectRoot);
+    if (input.protocol) {
+        if (!project) {
+            throw new AppError("validation", "--protocol requires --project or --project-root", 2, {
+                related_commands: relatedDashboardCommands(input.action, "project")
+            });
+        }
+        return { kind: "protocol", project, protocolId: input.protocol };
+    }
+    if (project) {
+        return { kind: "project", project };
+    }
+    return { kind: "global" };
+}
+export function dashboardTargetSummary(target) {
+    if (target.kind === "project") {
+        return { kind: "project", project_id: target.project.id, project_root: target.project.root };
+    }
+    if (target.kind === "protocol") {
+        return { kind: "protocol", project_id: target.project.id, project_root: target.project.root, protocol_id: target.protocolId };
+    }
+    return { kind: target.kind };
+}
+export function preferredDashboardCommand(action, target) {
+    if (target.kind === "project") {
+        return `dd-flow dashboard ${action} --project <project>`;
+    }
+    if (target.kind === "protocol") {
+        return `dd-flow dashboard ${action} --project <project> --protocol <protocol>`;
+    }
+    if (target.kind === "all_projects") {
+        return "dd-flow dashboard refresh --all";
+    }
+    return `dd-flow dashboard ${action}`;
+}
+export function relatedDashboardCommands(action, targetKind = "global") {
+    if (targetKind === "all_projects") {
+        return ["dd-flow dashboard refresh --all", "dd-flow dashboard open", "dd-flow dashboard open --project <project>"];
+    }
+    if (targetKind === "project" || targetKind === "protocol") {
+        return uniqueCommands([
+            `dd-flow dashboard ${action} --project <project>`,
+            "dd-flow dashboard refresh --project <project>",
+            "dd-flow dashboard open --project <project>",
+            "dd-flow dashboard data --project <project> --json"
+        ]);
+    }
+    return uniqueCommands([
+        `dd-flow dashboard ${action}`,
+        "dd-flow dashboard open",
+        "dd-flow dashboard refresh",
+        "dd-flow dashboard refresh --all",
+        "dd-flow dashboard open --project <project>"
+    ]);
+}
+function resolveDashboardProject(context, project, projectRoot) {
+    if (!project && !projectRoot) {
+        return null;
+    }
+    const byProject = project ? requireProjectByReference(context, project) : null;
+    const byRoot = projectRoot ? requireProjectByRoot(context, resolveProjectRoot(projectRoot)) : null;
+    if (byProject && byRoot && byProject.id !== byRoot.id) {
+        throw new AppError("validation", "--project and --project-root resolve to different projects", 2, {
+            project: { id: byProject.id, root: byProject.root },
+            project_root: { id: byRoot.id, root: byRoot.root }
+        });
+    }
+    return byProject ?? byRoot;
+}
+function uniqueCommands(commands) {
+    return Array.from(new Set(commands));
+}