@actiondock/cli 2.10.0 → 2.12.0

package/dist/commands/run.js

@@ -1,51 +1,34 @@
 import { validateActionInputValue, mapInputValidationFailure, } from "@actiondock/core/project";
 import { resolveTarget, } from "@actiondock/core/profile";
-import { resolveExecutionHint, } from "@actiondock/core";
+import { ACTION_NOT_FOUND, NOT_FOUND, resolveExecutionHint, } from "@actiondock/core";
 import { ArgumentError, ExecutionError, SigintError, packageNotFoundError } from "../errors.js";
-import { writeStderr, writeStdout } from "../renderer.js";
+import { extractTextFieldPayload, resolveActionDefaultTextField, writeStderr, writeStdout, } from "../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, resolveActionInput, resolveLocalPackageRoot, resolveTimeoutMs, withService, } from "../utils/index.js";
 /**
  * 以原始纯文本形式渲染 Action 执行终态结果（默认纯文本模式）。
  *
  * 设计契约：
- * 1. stdout: 仅承载业务有效载荷（payload）。保持原生排版、未转义多行与真实换行，供用户阅读或下游管道直接消费。
+ * - 通用纯文本透传：标量直接输出，结构化对象按标准规范呈现，杜绝私有业务字段嗅探。
+ * - 显式或声明式正文输出：指定 textField 时仅输出该自有字符串字段至 stdout，剩余字段以 JSON 对象形式输出至 stderr。
+ * - 标准输出仅承载业务有效载荷，保持原生排版与真实换行，供用户调阅或下游管道消费。
  */
-export function renderRawExecutionResult(targetRef, result, context) {
+export function renderRawExecutionResult(targetRef, result, context, options) {
     if (result.ok) {
+        if (options?.textField !== undefined) {
+            const { text, metadata } = extractTextFieldPayload(result.data, options.textField);
+            writeStdout(text, context);
+            if (metadata) {
+                writeStderr(JSON.stringify(metadata, null, 2), context);
+            }
+            return;
+        }
         const data = result.data;
         let rawText;
-        let metaInfo;
         if (typeof data === "string") {
             rawText = data;
         }
         else if (data !== null && typeof data === "object") {
-            if ("content" in data && data.content !== undefined) {
-                rawText =
-                    typeof data.content === "object" && data.content !== null
-                        ? JSON.stringify(data.content, null, 2)
-                        : String(data.content);
-                const { content, ...rest } = data;
-                if (Object.keys(rest).length > 0) {
-                    metaInfo = rest;
-                }
-            }
-            else if ("text" in data && typeof data.text === "string") {
-                rawText = data.text;
-                const { text, ...rest } = data;
-                if (Object.keys(rest).length > 0) {
-                    metaInfo = rest;
-                }
-            }
-            else if ("message" in data && typeof data.message === "string") {
-                rawText = data.message;
-                const { message, ...rest } = data;
-                if (Object.keys(rest).length > 0) {
-                    metaInfo = rest;
-                }
-            }
-            else {
-                rawText = JSON.stringify(data, null, 2);
-            }
+            rawText = JSON.stringify(data, null, 2);
         }
         else if (data !== undefined) {
             rawText = String(data);
@@ -53,32 +36,6 @@ export function renderRawExecutionResult(targetRef, result, context) {
         else {
             rawText = "";
         }
-        if (metaInfo) {
-            const parts = [];
-            const title = metaInfo.path ? String(metaInfo.path) : targetRef;
-            parts.push(title);
-            if (metaInfo.startLine !== undefined && metaInfo.endLine !== undefined) {
-                parts.push(`lines ${metaInfo.startLine}-${metaInfo.endLine}`);
-            }
-            else if (metaInfo.line !== undefined) {
-                parts.push(`line ${metaInfo.line}`);
-            }
-            if (metaInfo.hasMore !== undefined) {
-                parts.push(`hasMore: ${metaInfo.hasMore}`);
-            }
-            if (metaInfo.truncated) {
-                parts.push("truncated: true");
-            }
-            const handled = new Set(["path", "startLine", "endLine", "line", "hasMore", "truncated"]);
-            for (const [k, v] of Object.entries(metaInfo)) {
-                if (!handled.has(k) && v !== undefined) {
-                    parts.push(`${k}: ${typeof v === "object" ? JSON.stringify(v) : v}`);
-                }
-            }
-            if (parts.length > 0) {
-                writeStderr(`[${parts.join(" | ")}]`, context);
-            }
-        }
         writeStdout(rawText, context);
     }
     else {
@@ -110,6 +67,17 @@ export async function executeAction(id, options, context, flatArgs, control) {
     if (!id) {
         throw new ArgumentError("Action ID is required for run");
     }
+    if (options.textField !== undefined) {
+        if (typeof options.textField !== "string" || options.textField.trim() === "") {
+            throw new ArgumentError("The --text-field option requires a non-empty field name.");
+        }
+        if (options.json) {
+            throw new ArgumentError("Cannot specify both --text-field and --json.");
+        }
+        if (options.async) {
+            throw new ArgumentError("Cannot specify both --text-field and --async.");
+        }
+    }
     const effectiveControl = control ?? context?.control;
     const effectiveSignal = effectiveControl?.signal;
     const effectiveFlatArgs = flatArgs ?? options.flatArgs;
@@ -183,6 +151,21 @@ export async function executeAction(id, options, context, flatArgs, control) {
                 }
             }
             else {
+                let effectiveTextField = options.textField;
+                if (!isMachine && effectiveTextField === undefined) {
+                    try {
+                        const spec = await service.discovery.describeAction(targetRef);
+                        effectiveTextField = resolveActionDefaultTextField(spec.annotations);
+                    }
+                    catch (err) {
+                        if (err?.code === ACTION_NOT_FOUND || err?.code === NOT_FOUND) {
+                            // 若动作未找到，继续交由 execution.run 生成统一的执行与提示结果
+                        }
+                        else {
+                            throw err;
+                        }
+                    }
+                }
                 const result = await service.execution.run(targetRef, input, {
                     signal: effectiveSignal,
                     timeoutMs,
@@ -204,7 +187,7 @@ export async function executeAction(id, options, context, flatArgs, control) {
                     }
                 }
                 else {
-                    renderRawExecutionResult(targetRef, result, context);
+                    renderRawExecutionResult(targetRef, result, context, { textField: effectiveTextField });
                 }
                 if (!result.ok) {
                     if (context) {
@@ -255,6 +238,10 @@ Flat Input Syntax & Examples:
     # Nested object properties
     ad run <id> -- user.name="alice" user.age:=30
 
+  Text Field Output:
+    # Extract specific text field to stdout (remaining fields as JSON to stderr)
+    ad run <id> --text-field content -- path="README.md"
+
   Complex or multiline inputs:
     # Pass via JSON file with --input-file to avoid shell escaping issues
     ad run <id> --input-file input.json`;
@@ -281,6 +268,7 @@ export function attachRunCommand(parent, context) {
         .option("--async", "Execute asynchronously in background (requires remote server or profile)")
         .option("--data-dir <path>", "Custom database directory")
         .option("--json", "Output as JSON")
+        .option("--text-field <field>", "Extract and output a specific top-level string field as raw text")
         .addHelpText("after", RUN_HELP_AFTER_TEXT)
         .action(async (id, params, rawOptions, cmd) => {
         let flatArgs;

package/dist/commands/runs.d.ts

@@ -1,7 +1,12 @@
 import { Command } from "commander";
 import type { CliContext } from "../types.js";
 /**
- * 注册 runs 动作执行历史管理命令（list、show、clear、cancel）。
+ * 归一化 requestId 选项值为去重后的非空原样字符串数组。
+ * 将 requestId 作为不作解释的原样字符串，不拆分逗号、不剔除首尾空白，只做非空有效字符串检查与去重。
+ */
+export declare function normalizeRequestIds(raw: unknown): string[];
+/**
+ * 注册 runs 动作执行历史管理命令（list、show、watch、clear、cancel）。
  *
  * @param program Commander 实例
  * @param context 命令行上下文

package/dist/commands/runs.js

@@ -1,19 +1,17 @@
-import { findProjectRoot, loadProjectConfig, parseDuration, } from "@actiondock/core";
+import { loadProjectConfig, parseDuration, } from "@actiondock/core";
 import { filterWithFallbackInfo, } from "@actiondock/core/project";
-import { listLinkedPackages, resolvePackageRoot, } from "@actiondock/core/registry";
-import { ArgumentError, ExecutionError, NO_PROJECT_NO_LINKED_MESSAGE, packageNotFoundError, } from "../errors.js";
-import { renderResult, renderRunDetail, renderRunsList } from "../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, remoteTargetSuffix, requirePackageRoot, resolveFallbackStrategy, resolveIntent, withService, } from "../utils/index.js";
+import { listLinkedPackages, } from "@actiondock/core/registry";
+import { ArgumentError, ExecutionError, NO_PROJECT_NO_LINKED_MESSAGE, } from "../errors.js";
+import { renderResult, renderRunDetail, renderRunsList, writeStdout } from "../renderer.js";
+import { pollRunsUntilTerminal, renderWatchSummary, resolveRunsByRequestIds, } from "../services/run-watch.js";
+import { applyTargetOptions, getEffectiveOptions, remoteTargetSuffix, requirePackageRoot, resolveFallbackStrategy, resolveIntent, resolveLocalPackageRoot, withService, } from "../utils/index.js";
 /**
  * 解析本地目标包根目录与工程配置（仅在 local 分支调用）。
  * 显式指定包且寻址失败时抛出参数错误；工程清单损坏时降级为链接包视图。
  */
 function resolveLocalRunScope(packageOption) {
     if (packageOption) {
-        const root = resolvePackageRoot(packageOption);
-        if (!root) {
-            throw packageNotFoundError(packageOption);
-        }
+        const { root } = requirePackageRoot(packageOption);
         try {
             return { targetPackageRoot: root, projConfig: loadProjectConfig(root) };
         }
@@ -22,7 +20,7 @@ function resolveLocalRunScope(packageOption) {
             return { targetPackageRoot: root, projConfig: null };
         }
     }
-    const root = findProjectRoot();
+    const root = resolveLocalPackageRoot();
     if (!root) {
         return { targetPackageRoot: undefined, projConfig: null };
     }
@@ -35,7 +33,51 @@ function resolveLocalRunScope(packageOption) {
     }
 }
 /**
- * 注册 runs 动作执行历史管理命令（list、show、clear、cancel）。
+ * 解析 watch 命令的正时长选项值（毫秒）。
+ * 格式非法或非正值时抛参数错误（退出码 2）。
+ */
+function parsePositiveDuration(raw, flagName) {
+    if (raw === undefined || raw === null || String(raw).trim() === "") {
+        throw new ArgumentError(`Invalid ${flagName} argument: value is required`);
+    }
+    let ms;
+    try {
+        ms = parseDuration(String(raw));
+    }
+    catch (err) {
+        throw new ArgumentError(`Invalid ${flagName} argument: ${err.message}`);
+    }
+    if (ms === undefined || ms <= 0) {
+        throw new ArgumentError(`Invalid ${flagName} argument: must be a positive duration (e.g. 500ms, 2s)`);
+    }
+    return ms;
+}
+/**
+ * Commander 可重复选项收集函数：同一选项多次出现时累积为数组。
+ */
+function collectRepeatableOption(value, previous) {
+    return previous.concat([value]);
+}
+/**
+ * 归一化 requestId 选项值为去重后的非空原样字符串数组。
+ * 将 requestId 作为不作解释的原样字符串，不拆分逗号、不剔除首尾空白，只做非空有效字符串检查与去重。
+ */
+export function normalizeRequestIds(raw) {
+    const items = Array.isArray(raw) ? raw : raw !== undefined && raw !== null ? [raw] : [];
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        if (typeof item === "string" && item.length > 0) {
+            if (!seen.has(item)) {
+                seen.add(item);
+                result.push(item);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * 注册 runs 动作执行历史管理命令（list、show、watch、clear、cancel）。
  *
  * @param program Commander 实例
  * @param context 命令行上下文
@@ -51,6 +93,7 @@ export function registerRunsCommands(program, context) {
         .option("-P, --package <id>", "Target package ID or path")
         .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
         .option("-a, --action <actionId>", "Filter by action ID")
+        .option("--request-id <id>", "Filter by idempotency request ID (repeatable)", collectRepeatableOption, [])
         .option("-n, --limit <count>", "Maximum number of records to return", "20"))
         .option("--fallback", "Enable fallback to full list when no items match intent")
         .option("--no-fallback", "Disable fallback to full list when no items match intent")
@@ -61,6 +104,7 @@ export function registerRunsCommands(program, context) {
         const effectiveIntent = resolveIntent(options.intent, patterns);
         const { shouldFallback } = resolveFallbackStrategy(options);
         const limit = Number.parseInt(options.limit, 10) || 20;
+        const requestIds = normalizeRequestIds(options.requestId);
         const scope = resolveLocalRunScope(options.package);
         // 通过 Service 门面统一访问
         await withService(options, context, async (service, resolved) => {
@@ -71,6 +115,7 @@ export function registerRunsCommands(program, context) {
             const records = await service.runs.list({
                 packageId: options.package,
                 actionId: options.action,
+                requestIds: requestIds.length > 0 ? requestIds : undefined,
                 limit: queryLimit,
             });
             // 若处于本地无项目环境且无任何软链接包，则直接输出友好提示
@@ -140,6 +185,224 @@ export function registerRunsCommands(program, context) {
             });
         }, { localRoot: scope.targetPackageRoot, scanLinkedPackages: true });
     });
+    // runs watch [ids...] / --request-id <id>
+    applyTargetOptions(runsCmd
+        .command("watch [ids...]")
+        .description("Block until the given runs reach a terminal state, then aggregate results")
+        .option("-P, --package <id>", "Target package ID or path")
+        .option("--request-id <id>", "Wait by idempotency request ID(s) instead of run IDs (repeatable)", collectRepeatableOption, []))
+        .option("--resolve-timeout <duration>", "Budget for resolving --request-id to run IDs (e.g. 30s)", "30s")
+        .option("--timeout <duration>", "Overall wait limit (e.g. 30s, 5m, 500ms); exits with current statuses on expiry")
+        .option("--interval <duration>", "Polling interval (e.g. 500ms, 30s)", "2s")
+        .option("-q, --quiet", "Suppress periodic waiting progress lines")
+        .option("--data-dir <path>", "Custom database storage directory")
+        .option("--json", "Output as JSON")
+        .action(async (ids, rawOptions, cmd) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        const watchIds = (ids || []).filter((id) => id && id.trim());
+        const requestIds = normalizeRequestIds(options.requestId);
+        if (watchIds.length === 0 && requestIds.length === 0) {
+            throw new ArgumentError("At least one run ID or --request-id is required for watch");
+        }
+        const intervalMs = parsePositiveDuration(options.interval, "--interval");
+        const timeoutMs = options.timeout
+            ? parsePositiveDuration(options.timeout, "--timeout")
+            : undefined;
+        const resolveTimeoutMs = parsePositiveDuration(options.resolveTimeout, "--resolve-timeout");
+        // 从命令入口开始计算统一绝对截止时间
+        const commandStartedAt = Date.now();
+        const overallDeadline = timeoutMs !== undefined ? commandStartedAt + timeoutMs : undefined;
+        const effectiveControl = context?.control;
+        const externalSignal = effectiveControl?.signal;
+        // 绑定统一超时与外部取消信号至读取取消控制器
+        const timeoutController = overallDeadline !== undefined ? new AbortController() : undefined;
+        let timeoutTimer;
+        if (overallDeadline !== undefined) {
+            const remainingDelay = Math.max(0, overallDeadline - commandStartedAt);
+            timeoutTimer = setTimeout(() => {
+                timeoutController?.abort();
+            }, remainingDelay);
+            if (timeoutTimer.unref)
+                timeoutTimer.unref();
+        }
+        const readSignal = externalSignal && timeoutController
+            ? AbortSignal.any([externalSignal, timeoutController.signal])
+            : externalSignal ?? timeoutController?.signal;
+        try {
+            // 单一环境服务生命周期：一次 withService 包住标识解析和整个等待过程
+            await withService(options, context, async (service, resolved) => {
+                const scope = resolved.type === "local"
+                    ? resolveLocalRunScope(options.package)
+                    : undefined;
+                const normalizedPackageId = options.package
+                    ? (resolved.type === "remote" ? options.package : scope?.projConfig?.id || options.package)
+                    : undefined;
+                const whereDescription = resolved.type === "remote"
+                    ? `on remote server ${resolved.serverUrl || ""}`
+                    : options.package
+                        ? `in package '${normalizedPackageId}'`
+                        : "in current project or any linked packages";
+                // 1. 解析 requestId
+                const resolvedMap = new Map();
+                if (requestIds.length > 0) {
+                    const current = Date.now();
+                    const resolveDeadline = overallDeadline !== undefined
+                        ? Math.min(overallDeadline, commandStartedAt + resolveTimeoutMs)
+                        : commandStartedAt + resolveTimeoutMs;
+                    const remainingResolveBudgetMs = Math.max(0, resolveDeadline - current);
+                    const resolveTimeoutController = new AbortController();
+                    let resolveTimer;
+                    if (remainingResolveBudgetMs < Infinity) {
+                        resolveTimer = setTimeout(() => {
+                            resolveTimeoutController.abort();
+                        }, remainingResolveBudgetMs);
+                        if (resolveTimer.unref)
+                            resolveTimer.unref();
+                    }
+                    const resolveSignals = [resolveTimeoutController.signal];
+                    if (externalSignal)
+                        resolveSignals.push(externalSignal);
+                    if (timeoutController)
+                        resolveSignals.push(timeoutController.signal);
+                    const resolveSignal = AbortSignal.any(resolveSignals);
+                    let hits = [];
+                    let unresolved = [];
+                    try {
+                        const res = await resolveRunsByRequestIds(service, requestIds, {
+                            packageId: normalizedPackageId,
+                            intervalMs,
+                            resolveTimeoutMs: remainingResolveBudgetMs,
+                            deadline: resolveDeadline,
+                            signal: resolveSignal,
+                        });
+                        hits = res.resolved;
+                        unresolved = res.unresolved;
+                    }
+                    finally {
+                        if (resolveTimer)
+                            clearTimeout(resolveTimer);
+                    }
+                    // 查询返回后再次校验截止时间
+                    if (unresolved.length > 0 || Date.now() >= resolveDeadline) {
+                        const missingList = unresolved.length > 0 ? unresolved : requestIds;
+                        throw new ExecutionError(`Request ID(s) not found ${whereDescription} within ${options.resolveTimeout}: ${missingList.join(", ")}`);
+                    }
+                    for (const hit of hits) {
+                        resolvedMap.set(hit.requestId, hit);
+                    }
+                }
+                // 2. 保持用户输入顺序与 runId 去重
+                const sources = [];
+                const seenRunIds = new Set();
+                // 先按用户输入的位置参数添加
+                for (const id of watchIds) {
+                    if (seenRunIds.has(id))
+                        continue;
+                    seenRunIds.add(id);
+                    sources.push({ runId: id, source: resolved.type });
+                }
+                // 再按用户输入的 --request-id 顺序添加或补齐
+                for (const reqId of requestIds) {
+                    const hit = resolvedMap.get(reqId);
+                    if (!hit)
+                        continue;
+                    const existing = sources.find((s) => s.runId === hit.runId);
+                    if (existing) {
+                        if (!existing.requestId)
+                            existing.requestId = hit.requestId;
+                        if (!existing.initialRecord)
+                            existing.initialRecord = hit.record;
+                    }
+                    else if (!seenRunIds.has(hit.runId)) {
+                        seenRunIds.add(hit.runId);
+                        sources.push({
+                            runId: hit.runId,
+                            source: resolved.type,
+                            requestId: hit.requestId,
+                            initialRecord: hit.record,
+                        });
+                    }
+                }
+                // 3. 校验位置参数 runId 是否存在与归属校验
+                const notFound = [];
+                for (const source of sources) {
+                    if (!source.initialRecord) {
+                        const record = await service.runs.get(source.runId, { signal: readSignal });
+                        if (record) {
+                            if (normalizedPackageId && record.packageId !== normalizedPackageId) {
+                                notFound.push(source.runId);
+                            }
+                            else {
+                                source.initialRecord = record;
+                            }
+                        }
+                        else {
+                            notFound.push(source.runId);
+                        }
+                    }
+                    else if (normalizedPackageId && source.initialRecord.packageId !== normalizedPackageId) {
+                        notFound.push(source.runId);
+                    }
+                }
+                if (notFound.length > 0) {
+                    throw new ExecutionError(`Run record(s) not found ${whereDescription}: ${notFound.join(", ")}`);
+                }
+                if (sources.length === 0) {
+                    throw new ArgumentError("At least one valid run is required for watch");
+                }
+                // 4. 等待结果
+                const remainingOverallMs = overallDeadline !== undefined
+                    ? Math.max(0, overallDeadline - Date.now())
+                    : undefined;
+                const aggregation = await pollRunsUntilTerminal(sources, {
+                    service,
+                    intervalMs,
+                    timeoutMs: remainingOverallMs,
+                    deadline: overallDeadline,
+                    signal: externalSignal,
+                    timeoutSignal: timeoutController?.signal,
+                    quiet: options.quiet || options.json,
+                    context,
+                });
+                // 5. 输出结果（携带 reason、timedOut、interrupted 与逐运行结果）
+                if (options.json) {
+                    writeStdout(JSON.stringify({
+                        ok: aggregation.ok,
+                        timedOut: aggregation.timedOut,
+                        interrupted: aggregation.interrupted,
+                        reason: aggregation.reason,
+                        runs: aggregation.runs.map((r) => ({
+                            runId: r.runId,
+                            source: r.source,
+                            ...(r.requestId !== undefined ? { requestId: r.requestId } : {}),
+                            status: r.status,
+                            terminal: r.terminal,
+                            ...(r.data !== undefined ? { data: r.data } : {}),
+                            ...(r.error !== undefined ? { error: r.error } : {}),
+                        })),
+                    }, null, 2), context);
+                }
+                else {
+                    writeStdout(renderWatchSummary(aggregation, resolved.type === "remote" ? remoteTargetSuffix(resolved) : undefined), context);
+                }
+                if (!aggregation.ok) {
+                    if (context) {
+                        context.exitCode = 1;
+                    }
+                    if (!context?.control) {
+                        process.exitCode = 1;
+                    }
+                }
+            }, {
+                localRoot: () => resolveLocalRunScope(options.package).targetPackageRoot,
+                scanLinkedPackages: !options.package,
+            });
+        }
+        finally {
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+        }
+    });
     // runs cancel
     applyTargetOptions(runsCmd
         .command("cancel <id>")

package/dist/commands/serve.js

@@ -213,7 +213,11 @@ export function registerServeCommand(program, context) {
                                     }
                                 }
                             }
-                            catch { }
+                            catch (err) {
+                                // 防御与透明：解析动作白名单引用失败时输出警告，不中断服务启动但确保配置异常可观测
+                                const reason = err instanceof Error ? err.message : String(err);
+                                writeStderr(`Warning: Invalid action reference '${actRef}' in action allowlist: ${reason}`, context);
+                            }
                         }
                     }
                 }
@@ -222,7 +226,6 @@ export function registerServeCommand(program, context) {
         const platform = createNodePlatform({
             customHome: context?.customHome,
             dataDir: options.dataDir || context?.dataDir,
-            rootDir: projectRoot || undefined,
         });
         const service = await createActionDock({
             type: "local",

package/dist/commands/state.js

@@ -1,10 +1,11 @@
 import { decodeStateKey, } from "@actiondock/sdk";
-import { findProjectRoot, loadProjectConfig, } from "@actiondock/core";
-import { resolvePackageRoot, } from "@actiondock/core/registry";
-import { ArgumentError, ExecutionError, packageNotFoundError } from "../errors.js";
+import { loadProjectConfig, } from "@actiondock/core";
+import { filterWithFallbackInfo, } from "@actiondock/core/project";
+import { listLinkedPackages, } from "@actiondock/core/registry";
+import { existsSync } from "node:fs";
+import { ArgumentError, ExecutionError, NO_PROJECT_NO_LINKED_MESSAGE } from "../errors.js";
 import { renderResult, renderStateList, writeStderr, writeStdout } from "../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, getTargetRoot, remoteTargetLabel, resolveFallbackStrategy, resolveIntent, resolveTargetFromOptions, withService, } from "../utils/index.js";
-import { renderLinkedPackagesStateList, renderProjectScopedStateList, } from "./state-list.js";
+import { applyTargetOptions, getEffectiveOptions, getTargetRoot, remoteTargetLabel, requirePackageRoot, resolveFallbackStrategy, resolveIntent, resolveLocalPackageRoot, resolveTargetFromOptions, withService, } from "../utils/index.js";
 /**
  * 统一预解码状态键寻址（get、set、delete 共享的单一事实源）。
  *
@@ -68,6 +69,81 @@ function resolveStateScope(resolved, options, rawKey) {
         localRoot: root,
     };
 }
+/**
+ * 渲染单个项目作用域的状态键列表（含 --detail JSON 明细分支）。
+ */
+async function renderProjectScopedStateList(args) {
+    const { service, targetRoot, actionId, prefix, options, effectiveIntent, shouldFallback, context } = args;
+    const projConfig = loadProjectConfig(targetRoot);
+    const allKeys = (await service.management?.state.list(projConfig.id, actionId, {
+        namespace: options.namespace !== undefined ? options.namespace : null,
+        prefix,
+    })) ?? [];
+    if (options.detail && options.json) {
+        const entries = [];
+        for (const k of allKeys) {
+            const entry = await service.management?.state.get(projConfig.id, actionId, k, {
+                namespace: options.namespace,
+                detail: true,
+            });
+            if (entry) {
+                entries.push(entry);
+            }
+        }
+        const filterRes = filterWithFallbackInfo(entries, effectiveIntent, [(e) => e.fullKey, (e) => e.key, (e) => e.namespace], shouldFallback);
+        renderResult(filterRes.items, {
+            json: true,
+            context,
+        });
+        return;
+    }
+    const filterRes = filterWithFallbackInfo(allKeys, effectiveIntent, [(k) => k], shouldFallback);
+    renderResult(filterRes.items, {
+        json: options.json,
+        humanFormatter: () => renderStateList(filterRes.items, `${projConfig.name} (${projConfig.id})`, filterRes.isFallback, effectiveIntent),
+        context,
+    });
+}
+/**
+ * 渲染全部链接包聚合的状态键列表（跳过磁盘失效与清单损坏的链接项）。
+ */
+async function renderLinkedPackagesStateList(args) {
+    const { service, actionId, prefix, options, effectiveIntent, shouldFallback, context } = args;
+    // 扫描所有链接的包状态
+    const linked = listLinkedPackages();
+    if (linked.length === 0) {
+        renderResult([], {
+            json: options.json,
+            humanFormatter: () => NO_PROJECT_NO_LINKED_MESSAGE,
+            context,
+        });
+        return;
+    }
+    const aggregatedKeys = [];
+    for (const pkg of linked) {
+        if (!existsSync(pkg.path))
+            continue;
+        try {
+            const config = loadProjectConfig(pkg.path);
+            const keys = (await service.management?.state.list(config.id, actionId, {
+                namespace: options.namespace !== undefined ? options.namespace : null,
+                prefix,
+            })) ?? [];
+            for (const k of keys) {
+                aggregatedKeys.push(`${config.id}/${k}`);
+            }
+        }
+        catch {
+            // 单个链接包清单损坏或状态读取失败时跳过，继续聚合其余包
+        }
+    }
+    const filterRes = filterWithFallbackInfo(aggregatedKeys, effectiveIntent, [(k) => k], shouldFallback);
+    renderResult(filterRes.items, {
+        json: options.json,
+        humanFormatter: () => renderStateList(filterRes.items, "Linked Packages State Store", filterRes.isFallback, effectiveIntent),
+        context,
+    });
+}
 /**
  * 注册 state 状态管理命令（get、set、delete、clear、keys、list）。
  *
@@ -99,16 +175,9 @@ export function registerStateCommands(program, context) {
                 return;
             }
             // 本地工程与链接包模式：按目标根目录决策输出范围
-            let targetRoot = null;
-            if (options.package) {
-                targetRoot = resolvePackageRoot(options.package);
-                if (!targetRoot) {
-                    throw packageNotFoundError(options.package);
-                }
-            }
-            else {
-                targetRoot = findProjectRoot();
-            }
+            const targetRoot = options.package
+                ? requirePackageRoot(options.package).root
+                : resolveLocalPackageRoot();
             if (targetRoot) {
                 await renderProjectScopedStateList({
                     service,