新增 release artifact URL workflow action plan API

2026-06-16 15:01:39 +08:00
parent b7ec759645
commit e11c29533f
9 changed files with 230 additions and 4 deletions
--- a/PROJECT_COMPLETION_TRACKER.md
+++ b/PROJECT_COMPLETION_TRACKER.md
@@ -9,7 +9,7 @@ turn-by-turn continuation notes and next-batch execution records.
 ## Current Status

 - Active continuation file: `text14.txt`
- Latest completed batch: project release artifact URL workflow SDK gate
+- Latest completed batch: project release artifact URL workflow action-plan SDK API
 - Latest relevant commit: use `git log -1 --oneline` after each committed batch
 - Working tree at tracker creation: clean
 - Required policy: LinuxCNC remains the only CNC semantic source
@@ -43,7 +43,7 @@ The project is complete for the current scope when all of the following are true
 | Native nc_files baseline | Stable | Last recorded Layer 1: `total 107`, `pass 101`, `expected_fail 6`, `unexpected_fail 0`. |
 | Native sim configs baseline | Stable | Last recorded Layer 2: `total 159`, `pass 151`, `expected_fail 8`, `unexpected_fail 0`. |
 | OPFS/session persistence | Stable for current scope | Browser smoke passes, SDK re-exports OPFS/session helpers including `readMachineSessionReadiness()` and `createMachineSessionPersistenceSummary()`, the UI exposes `getMachineSessionPersistenceSummary()`, and `docs/opfs-session-persistence.md` defines the project-level release gate. |
-| SDK/API surface | Stable for current scope | SDK re-exports core, OPFS/session readiness/load helpers, sim-config staging, project release gate manifest/result matrix/action-plan/readiness summary view-model, project release readiness report/artifact JSON workflow/artifact URL workflow summary/artifact validation summary/action-plan plus URL loading workflow, INI panel entry/launcher/control-page/shell/workflow overview helpers, the session readiness workflow report, and the shell API surface inventory with dedicated Node smokes. |
+| SDK/API surface | Stable for current scope | SDK re-exports core, OPFS/session readiness/load helpers, sim-config staging, project release gate manifest/result matrix/action-plan/readiness summary view-model, project release readiness report/artifact JSON workflow/artifact URL workflow summary/action-plan/artifact validation summary/action-plan plus URL loading workflow, INI panel entry/launcher/control-page/shell/workflow overview helpers, the session readiness workflow report, and the shell API surface inventory with dedicated Node smokes. |
 | Browser/UI workflow | Stable for current scope | Workflow overview embedding mount DOM closure is complete, and INI panel session workflows plus read-only control/shell handoff expose, render, fetch, validate, summarize, and report OPFS/session readiness, OPFS/session persistence summary, release readiness artifact validation/rendering/URL workflow summaries, and API surface inventory before loading or reading WASM session state. |
 | Workflow overview embedding | Stable for current scope | Report/display/render, DOM contract/readiness/renderer, mount result/display/render, mount DOM contract/readiness/renderer/wrapper exist. |
 | Host/runtime boundary proof | Stable blocked state | Host smoke passes; runtime families remain blocked and `docs/host-runtime-boundary-handoff.md` records host readiness, promotion blockers, dispatch, and evidence gates. |
--- a/text14.txt
+++ b/text14.txt
@@ -3308,6 +3308,69 @@ ui_node_smokes=ok
 继续只做实质能力推进。优先选择可执行 gate、SDK/API surface、或真实 browser workflow；
 不要做只整理断言或局部常量化的批次。

+五十六、2026-06-16 继续执行记录：project release artifact URL workflow action-plan SDK API
+
+本轮继续按“每批必须产出可调用 API、可验证 workflow、可执行 gate、或真实 UI/browser 能力”推进，
+把 SDK 侧 release artifact URL workflow 的 blocked 状态提升为 workflow-level action-plan API。外部
+CI/dashboard 现在可以区分缺调用输入、URL fetch 问题和可执行 gate 命令，不需要从 summary rows 或
+validation action-plan 里自行推断下一步。
+
+完成内容：
+
+- `runtime/sdk/src/project-release-readiness.js` 新增：
+  - `createProjectReleaseReadinessArtifactUrlWorkflowActionPlan()`；
+- 新 action-plan 返回：
+  - `apiName: project-release-readiness-artifact-url-workflow-action-plan`；
+  - `planVersion: 1`；
+  - `phase/ready`；
+  - `missing`；
+  - `actionCount/commandCount`；
+  - `nextActionId/nextCommand`；
+  - `actions[]`；
+  - `commands[]`；
+  - `shellScript`；
+  - display `rows[]`；
+- ready URL workflow 返回空 actions 和 ready shellScript；
+- missing URL/fetch 返回 input actions 加 validation command actions；
+- HTTP failure 和 thrown fetch 返回 fetch action 加 validation command actions；
+- `runtime/sdk/src/index.js` re-export 新 action-plan API；
+- `verify_project_release_artifact_url_workflow.mjs` 覆盖 ready、missing input、HTTP failure、thrown fetch
+  的 workflow-level action-plan；
+- `verify_sdk_surface.mjs` 覆盖 SDK export、README 可发现性和 ready shellScript；
+- `runtime/sdk/README.md`、`docs/project-release-handoff.md`、`verify_project_release_handoff_docs.mjs`
+  记录 URL workflow action-plan API；
+- `PROJECT_COMPLETION_TRACKER.md` 同步 latest completed batch 和 SDK/API surface 状态；
+- 未新增控制按钮；
+- 未执行 opt-in runtime probes；
+- 未解析 G-code；
+- 未解释 canonical events；
+- 未新增 JS CNC 语义；
+- 未 promotion blocked runtime family；
+- 未改变 LinuxCNC interpreter、tool、parameter、planner、kinematics、remap 或 LinuxCNC-owned
+  runtime semantics。
+
+验证已通过（先行 targeted）：
+
+```bash
+wasm-port/tests/sdk/node/verify_project_release_artifact_url_workflow.sh
+wasm-port/tests/sdk/node/verify_sdk_surface.sh
+wasm-port/tests/docs/node/verify_project_release_handoff_docs.sh
+```
+
+关键输出：
+
+```text
+project_release_artifact_url_workflow_node_smoke=ok
+sdk_surface_node_smoke=ok
+project_release_gate_manifest_node_smoke=ok
+project_release_handoff_docs_node_smoke=ok
+```
+
+下一步工作计划：
+
+继续只做实质能力推进。优先选择可执行 gate、SDK/API surface、或真实 browser workflow；
+不要做只整理断言或局部常量化的批次。
+
 五十五、2026-06-16 继续执行记录：project release artifact URL workflow SDK gate

 本轮继续按“每批必须产出可调用 API、可验证 workflow、可执行 gate、或真实 UI/browser 能力”推进，
--- a/wasm-port/docs/project-release-handoff.md
+++ b/wasm-port/docs/project-release-handoff.md
@@ -67,6 +67,8 @@ continuation records are in `../text14.txt`.
  implementation, including fetch status and next-command output.
  `createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel()` turns
  that SDK URL workflow into stable dashboard rows and status text.
+  `createProjectReleaseReadinessArtifactUrlWorkflowActionPlan()` turns blocked
+  URL workflows into ordered input, fetch, and command actions for CI tooling.
  Browser shells can also pass the JSON to
  `linuxCncIniPanelWorkflowOverviewApi.validateWorkflowOverviewReleaseReadinessArtifactJson()`
  through the workflow overview iframe and receive stable validation rows. They
--- a/wasm-port/runtime/sdk/README.md
+++ b/wasm-port/runtime/sdk/README.md
@@ -57,6 +57,7 @@ import {
  createProjectReleaseGateManifest,
  createProjectReleaseGateResultMatrix,
  createProjectReleaseReadinessArtifactJsonWorkflow,
+  createProjectReleaseReadinessArtifactUrlWorkflowActionPlan,
  createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel,
  createProjectReleaseReadinessArtifactValidation,
  createProjectReleaseReadinessArtifactValidationActionPlan,
@@ -252,10 +253,15 @@ action-plan output without executing release gates.
 `createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel()` turns the
 URL workflow result into stable dashboard status text and rows for ready,
 missing-input, fetch-failure, and artifact-validation-blocked states.
+`createProjectReleaseReadinessArtifactUrlWorkflowActionPlan()` turns the same
+URL workflow into ordered workflow-level actions, distinguishing caller input,
+fetch checks, and executable gate commands while preserving a shell script for
+command actions.
 `tests/sdk/node/verify_project_release_artifact_url_workflow.sh` is the
 dedicated executable SDK gate for that URL workflow. It verifies caller-provided
-fetch handling, ready summaries, missing input, HTTP failure, thrown fetch
-errors, and ends with `project_release_artifact_url_workflow_node_smoke=ok`.
+fetch handling, ready summaries, action plans, missing input, HTTP failure,
+thrown fetch errors, and ends with
+`project_release_artifact_url_workflow_node_smoke=ok`.

 ## OPFS/session persistence exports

--- a/wasm-port/runtime/sdk/src/index.js
+++ b/wasm-port/runtime/sdk/src/index.js
@@ -5,6 +5,7 @@ export {
  createProjectReleaseGateManifest,
  createProjectReleaseGateResultMatrix,
  createProjectReleaseReadinessArtifactJsonWorkflow,
+  createProjectReleaseReadinessArtifactUrlWorkflowActionPlan,
  createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel,
  createProjectReleaseReadinessArtifactValidation,
  createProjectReleaseReadinessArtifactValidationActionPlan,
--- a/wasm-port/runtime/sdk/src/project-release-readiness.js
+++ b/wasm-port/runtime/sdk/src/project-release-readiness.js
@@ -727,6 +727,88 @@ export function createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel
  };
 }

+export function createProjectReleaseReadinessArtifactUrlWorkflowActionPlan(
+  workflow = {},
+) {
+  const missing = arrayOrEmpty(workflow?.missing);
+  const ready = workflow?.ready === true;
+  const validationCommands = arrayOrEmpty(workflow?.actionPlan?.commands);
+  const inputActions = [
+    ...(missing.includes("artifact-url")
+      ? [{
+        id: "provide-artifact-url",
+        label: "Provide release readiness artifact URL",
+        kind: "input",
+        command: null,
+        expectedOutput: null,
+      }]
+      : []),
+    ...(missing.includes("fetch")
+      ? [{
+        id: "provide-fetch",
+        label: "Provide fetch implementation",
+        kind: "input",
+        command: null,
+        expectedOutput: null,
+      }]
+      : []),
+    ...(missing.includes("artifact-fetch")
+      ? [{
+        id: "verify-artifact-url-fetch",
+        label: "Verify release readiness artifact URL fetch",
+        kind: "fetch",
+        command: null,
+        expectedOutput: null,
+      }]
+      : []),
+  ];
+  const commandActions = validationCommands.map((command) => ({
+    id: command.id ?? command.gateId ?? `command-${command.step}`,
+    label: command.label,
+    kind: "command",
+    command: command.command,
+    expectedOutput: command.expectedOutput ?? null,
+  }));
+  const actions = ready ? [] : [...inputActions, ...commandActions].map((action, index) => ({
+    step: index + 1,
+    ...action,
+  }));
+  const commands = actions.filter(({ command }) => typeof command === "string" && command.length > 0);
+  const shellScript = commands.length > 0
+    ? [
+      "#!/usr/bin/env bash",
+      "set -euo pipefail",
+      "",
+      ...commands.map(({ command }) => command),
+      "",
+    ].join("\n")
+    : (ready
+      ? "# Project release readiness artifact URL workflow is already ready.\n"
+      : "# Project release readiness artifact URL workflow requires non-shell input.\n");
+
+  return {
+    apiName: "project-release-readiness-artifact-url-workflow-action-plan",
+    planVersion: 1,
+    phase: ready ? "ready" : "blocked",
+    ready,
+    missing,
+    actionCount: actions.length,
+    commandCount: commands.length,
+    nextActionId: actions[0]?.id ?? null,
+    nextCommand: commands[0]?.command ?? null,
+    actions,
+    commands,
+    shellScript,
+    rows: actions.map(({ id, label, kind, command, expectedOutput }) => ({
+      id,
+      label,
+      kind,
+      value: command ?? kind,
+      expectedOutput,
+    })),
+  };
+}
+
 export function createProjectReleaseReadinessArtifactValidation(artifact = {}) {
  const artifactObject = objectOrEmpty(artifact);
  const releaseGate = objectOrEmpty(artifactObject.releaseGate);
--- a/wasm-port/tests/docs/node/verify_project_release_handoff_docs.mjs
+++ b/wasm-port/tests/docs/node/verify_project_release_handoff_docs.mjs
@@ -42,6 +42,7 @@ for (const phrase of [
  "createProjectReleaseReadinessArtifactValidationActionPlan()",
  "createProjectReleaseReadinessArtifactValidationSummaryViewModel()",
  "loadProjectReleaseReadinessArtifactUrlWorkflow()",
+  "createProjectReleaseReadinessArtifactUrlWorkflowActionPlan()",
  "createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel()",
  "embedded gate manifest, result matrix, and action plan",
  "validateWorkflowOverviewReleaseReadinessArtifactJson()",
@@ -125,6 +126,7 @@ for (const phrase of [
  "gateActionPlanReady",
  "loadIniPanelShellWorkflowOverviewReleaseReadinessArtifactUrl()",
  "loadProjectReleaseReadinessArtifactUrlWorkflow()",
+  "createProjectReleaseReadinessArtifactUrlWorkflowActionPlan()",
  "createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel()",
  "verify_project_release_artifact_url_workflow.sh",
  "project_release_artifact_url_workflow_node_smoke=ok",
--- a/wasm-port/tests/sdk/node/verify_project_release_artifact_url_workflow.mjs
+++ b/wasm-port/tests/sdk/node/verify_project_release_artifact_url_workflow.mjs
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";

 import {
  createProjectReleaseGateManifest,
+  createProjectReleaseReadinessArtifactUrlWorkflowActionPlan,
  createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel,
  createProjectReleaseReadinessReport,
  loadProjectReleaseReadinessArtifactUrlWorkflow,
@@ -25,6 +26,7 @@ const readyWorkflow = await loadProjectReleaseReadinessArtifactUrlWorkflow({
  },
 });
 const readySummary = createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel(readyWorkflow);
+const readyActionPlan = createProjectReleaseReadinessArtifactUrlWorkflowActionPlan(readyWorkflow);

 assert.equal(fetchedUrl, "/project-release-readiness.json");
 assert.equal(readyWorkflow.apiName, "project-release-readiness-artifact-url-workflow");
@@ -49,6 +51,21 @@ assert.deepEqual(
    ["missing", "none"],
  ],
 );
+assert.deepEqual(readyActionPlan, {
+  apiName: "project-release-readiness-artifact-url-workflow-action-plan",
+  planVersion: 1,
+  phase: "ready",
+  ready: true,
+  missing: [],
+  actionCount: 0,
+  commandCount: 0,
+  nextActionId: null,
+  nextCommand: null,
+  actions: [],
+  commands: [],
+  shellScript: "# Project release readiness artifact URL workflow is already ready.\n",
+  rows: [],
+});

 const missingInputWorkflow = await loadProjectReleaseReadinessArtifactUrlWorkflow({
  artifactUrl: "",
@@ -57,11 +74,30 @@ const missingInputWorkflow = await loadProjectReleaseReadinessArtifactUrlWorkflo
 const missingInputSummary = createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel(
  missingInputWorkflow,
 );
+const missingInputActionPlan = createProjectReleaseReadinessArtifactUrlWorkflowActionPlan(
+  missingInputWorkflow,
+);
 assert.equal(missingInputWorkflow.ready, false);
 assert.equal(missingInputWorkflow.fetched, false);
 assert.deepEqual(missingInputWorkflow.missing.slice(0, 2), ["artifact-url", "fetch"]);
 assert.match(missingInputSummary.statusLine, /^Blocked: artifact-url, fetch/);
 assert.equal(missingInputSummary.rows.find(({ id }) => id === "artifact-url")?.value, "missing");
+assert.equal(missingInputActionPlan.phase, "blocked");
+assert.equal(missingInputActionPlan.actionCount, 4);
+assert.equal(missingInputActionPlan.commandCount, 2);
+assert.equal(missingInputActionPlan.nextActionId, "provide-artifact-url");
+assert.equal(
+  missingInputActionPlan.nextCommand,
+  "wasm-port/tests/host/verify_project_release_gate.sh",
+);
+assert.deepEqual(
+  missingInputActionPlan.actions.slice(0, 2).map(({ id, kind, command }) => [id, kind, command]),
+  [
+    ["provide-artifact-url", "input", null],
+    ["provide-fetch", "input", null],
+  ],
+);
+assert.match(missingInputActionPlan.shellScript, /^#!\/usr\/bin\/env bash\nset -euo pipefail\n/);

 const httpFailureWorkflow = await loadProjectReleaseReadinessArtifactUrlWorkflow({
  artifactUrl: "/missing.json",
@@ -74,6 +110,9 @@ const httpFailureWorkflow = await loadProjectReleaseReadinessArtifactUrlWorkflow
 const httpFailureSummary = createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel(
  httpFailureWorkflow,
 );
+const httpFailureActionPlan = createProjectReleaseReadinessArtifactUrlWorkflowActionPlan(
+  httpFailureWorkflow,
+);
 assert.equal(httpFailureWorkflow.ready, false);
 assert.equal(httpFailureWorkflow.fetched, false);
 assert.equal(httpFailureWorkflow.httpStatus, 404);
@@ -85,6 +124,14 @@ assert.equal(
 );
 assert.match(httpFailureSummary.statusLine, /^Blocked: artifact-fetch/);
 assert.equal(httpFailureSummary.rows.find(({ id }) => id === "fetch")?.value, "blocked");
+assert.equal(httpFailureActionPlan.phase, "blocked");
+assert.equal(httpFailureActionPlan.actionCount, 3);
+assert.equal(httpFailureActionPlan.commandCount, 2);
+assert.equal(httpFailureActionPlan.nextActionId, "verify-artifact-url-fetch");
+assert.equal(
+  httpFailureActionPlan.rows[0].value,
+  "fetch",
+);

 const thrownFetchWorkflow = await loadProjectReleaseReadinessArtifactUrlWorkflow({
  artifactUrl: "/throws.json",
@@ -95,11 +142,16 @@ const thrownFetchWorkflow = await loadProjectReleaseReadinessArtifactUrlWorkflow
 const thrownFetchSummary = createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel(
  thrownFetchWorkflow,
 );
+const thrownFetchActionPlan = createProjectReleaseReadinessArtifactUrlWorkflowActionPlan(
+  thrownFetchWorkflow,
+);
 assert.equal(thrownFetchWorkflow.ready, false);
 assert.equal(thrownFetchWorkflow.fetched, false);
 assert.equal(thrownFetchWorkflow.httpStatus, null);
 assert.equal(thrownFetchWorkflow.fetchError, "network unavailable");
 assert.equal(thrownFetchWorkflow.missing[0], "artifact-fetch");
 assert.match(thrownFetchSummary.statusLine, /^Blocked: artifact-fetch/);
+assert.equal(thrownFetchActionPlan.nextActionId, "verify-artifact-url-fetch");
+assert.equal(thrownFetchActionPlan.commands.length, 2);

 console.log("project_release_artifact_url_workflow_node_smoke=ok");
--- a/wasm-port/tests/sdk/node/verify_sdk_surface.mjs
+++ b/wasm-port/tests/sdk/node/verify_sdk_surface.mjs
@@ -38,6 +38,7 @@ import {
  createProjectReleaseGateManifest,
  createProjectReleaseGateResultMatrix,
  createProjectReleaseReadinessArtifactJsonWorkflow,
+  createProjectReleaseReadinessArtifactUrlWorkflowActionPlan,
  createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel,
  createProjectReleaseReadinessArtifactValidation,
  createProjectReleaseReadinessArtifactValidationActionPlan,
@@ -98,6 +99,10 @@ const requiredExports = [
  ["createProjectReleaseGateManifest", createProjectReleaseGateManifest],
  ["createProjectReleaseGateResultMatrix", createProjectReleaseGateResultMatrix],
  ["createProjectReleaseReadinessArtifactJsonWorkflow", createProjectReleaseReadinessArtifactJsonWorkflow],
+  [
+    "createProjectReleaseReadinessArtifactUrlWorkflowActionPlan",
+    createProjectReleaseReadinessArtifactUrlWorkflowActionPlan,
+  ],
  [
    "createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel",
    createProjectReleaseReadinessArtifactUrlWorkflowSummaryViewModel,
@@ -386,6 +391,19 @@ assert.equal(
  ).statusLine,
  "Ready: Artifact URL workflow complete",
 );
+assert.equal(
+  createProjectReleaseReadinessArtifactUrlWorkflowActionPlan(
+    await loadProjectReleaseReadinessArtifactUrlWorkflow({
+      artifactUrl: "/project-release-readiness.json",
+      fetchRef: async () => ({
+        ok: true,
+        status: 200,
+        text: async () => JSON.stringify(releaseReadinessArtifact),
+      }),
+    }),
+  ).shellScript,
+  "# Project release readiness artifact URL workflow is already ready.\n",
+);
 assert.equal(
  (await loadProjectReleaseReadinessArtifactUrlWorkflow({
    artifactUrl: "/missing.json",