diff --git a/docs/reference/ci.md b/docs/reference/ci.md index 71fc93f8..a13e7a4b 100644 --- a/docs/reference/ci.md +++ b/docs/reference/ci.md @@ -124,7 +124,7 @@ The CI user-service artifact task must follow these rules: - For D601 direct services, `findjob` and `pipeline` have reviewed dev/prod D601 Compose artifact consumers, `met-nonlinear` is dry-run only until the long-running service image contract matches the published artifact, and `k3sctl-adapter` is supervisor-only because it is the native k3s control bridge outside the k3s failure domain. - ClaudeQQ source comes from `https://gitee.com/lyon1998/agent_skills`; the producer exports the `claudeqq/` subtree and overlays the UniDesk Dockerfile plus API adapter from `src/components/microservices/claudeqq/` before building. Runtime topology and deploy intent still live in manifests and `deploy.json`, not in `CI.json`. -The same command also has a read-only preflight mode: `bun scripts/cli.ts ci publish-user-service --service --commit --dry-run`. That mode may be called from the main server or through remote frontend passthrough, and it must return `runnerDisposition`, `missingChannels`, `channels`, `registry`, `artifactSummary`, `boundary` and `next` without creating a PipelineRun or pushing an image. If backend-core, database or provider channels are missing, the result must be structured `infra-blocked`, not a bare container lookup failure. +The same command also has a read-only preflight mode: `bun scripts/cli.ts ci publish-user-service --service --commit --dry-run`. That mode may be called from the main server or through remote frontend passthrough, and it must return `runnerDisposition`, `missingChannels`, `missingControlChannels`, `channels`, `controlChannels`, `registry`, `artifactSummary`, `controlledPublish`, `boundary` and `next` without creating a PipelineRun or pushing an image. `missingChannels` is the detailed probe list, while `missingControlChannels` is the runner-facing domain list using only `backend-core`, `database`, `provider` and `registry`. `controlledPublish` must point at the real producer boundary: D601, namespace `unidesk-ci`, PipelineRun `unidesk-user-service-artifact-publish`, and the non-dry-run `ci publish-user-service` command shape. If backend-core, database, provider or registry channels are missing, the result must be structured `infra-blocked`, not a bare container lookup failure. Publish a Baidu Netdisk artifact: diff --git a/docs/reference/cicd-standardization.md b/docs/reference/cicd-standardization.md index f1275dca..2e5923e4 100644 --- a/docs/reference/cicd-standardization.md +++ b/docs/reference/cicd-standardization.md @@ -188,4 +188,4 @@ backend-core and D601 `code-queue` remain restricted to dev image validation in This precheck uses lightweight parsing and dry-run evidence only. It intentionally does not run full `check`, e2e, Playwright, or other broad browser/runtime test suites on the master server because those are outside the precheck scope and may exceed master-server resource limits. `backend-core` and D601 `code-queue` production validation are also out of scope; backend-core dev rollout can be attempted only through the existing D601 dev path, and a provider-offline result is an infrastructure blocker rather than permission to validate production. -The structured read-only preflight entrypoints are `artifact-registry status|health` and `ci publish-user-service --dry-run`. Remote runners may call them through the frontend passthrough path, and the result must classify missing backend-core, database or provider channels as `runnerDisposition=infra-blocked` with explicit missing channel names. Those cases are infrastructure blockers, not business failures and not a license to retry a real publish. +The structured read-only preflight entrypoints are `artifact-registry status|health` and `ci publish-user-service --dry-run`. Remote runners may call them through the frontend passthrough path, and the result must classify missing backend-core, database, provider or registry channels as `runnerDisposition=infra-blocked`. The detailed probe list remains in `missingChannels`; the stable runner-facing domain list is `missingControlChannels` with only `backend-core`, `database`, `provider` and `registry`. Those cases are infrastructure blockers, not business failures and not a license to retry a real publish. A non-dry-run publish may be attempted only where `controlledPublish` points: D601 CI, namespace `unidesk-ci`, PipelineRun `unidesk-user-service-artifact-publish`. diff --git a/docs/reference/user-service-delivery.md b/docs/reference/user-service-delivery.md index c0e65fea..2284d554 100644 --- a/docs/reference/user-service-delivery.md +++ b/docs/reference/user-service-delivery.md @@ -37,6 +37,7 @@ The default release flow for a user-service change is: - Commit-pinned image tags are the deployment truth; mutable `latest` tags are not. - Root `CI.json` is an artifact catalog only. It lists CI producer inputs such as `serviceId`, artifact kind, source repository, repo-relative Dockerfile, image repository naming, upstream image digest/mirror metadata and the required artifact summary fields; it must not carry runtime topology or replace `deploy.json`. - The standard CI artifact producer is `bun scripts/cli.ts ci publish-user-service --service --commit `. It accepts only a pushed Git commit and a service id registered in `CI.json`, reads `source.repo` and `source.dockerfile` from that catalog, rejects ad hoc `--repo` overrides, and reports `serviceId`, `sourceCommit`, `sourceRepo`, `dockerfile`, `imageRef`, `tag`, `digest` and `digestRef`. +- The producer dry-run preflight is `bun scripts/cli.ts ci publish-user-service --service --commit --dry-run`. It is read-only and reports detailed `missingChannels` plus stable `missingControlChannels` for `backend-core`, `database`, `provider` and `registry`; any missing control channel is `runnerDisposition=infra-blocked`. The `controlledPublish` field names D601 `unidesk-ci` as the only controlled environment for the subsequent real publish. - The CI artifact producer is not a deploy executor. It must not mutate the production namespace, restart production services, or update `deploy.json`. - `CI.json` may list `blocked` source-build entries when the source input is known but the publish/CD boundary is not yet reviewed. It may also list `upstream-image` entries for image-only services such as File Browser; those entries pin upstream digest and mirror intent but must not be treated as Dockerfile builds. - Every production release must finish with a manual acceptance step after the automated checks pass. diff --git a/scripts/ci-publish-user-service-preflight-contract-test.ts b/scripts/ci-publish-user-service-preflight-contract-test.ts index d0d5a402..509f1ca8 100644 --- a/scripts/ci-publish-user-service-preflight-contract-test.ts +++ b/scripts/ci-publish-user-service-preflight-contract-test.ts @@ -58,22 +58,34 @@ async function main(): Promise { const record = asRecord(result, "preflight"); const source = asRecord(record.source, "source"); const channels = Array.isArray(record.channels) ? record.channels.map((item) => asRecord(item, "channel")) : []; + const controlChannels = Array.isArray(record.controlChannels) ? record.controlChannels.map((item) => asRecord(item, "control channel")) : []; const registry = asRecord(record.registry, "registry"); + const controlledPublish = asRecord(record.controlledPublish, "controlledPublish"); const backendCore = asRecord(channels.find((item) => item.channel === "backend-core-api")?.detail, "backendCore detail"); const backendCoreTransport = asRecord(backendCore.detail, "backendCore transport payload"); const backendCoreBody = asRecord(backendCoreTransport.body, "backendCore body payload"); const providerDispatch = asRecord(channels.find((item) => item.channel === "provider-dispatch")?.detail, "providerDispatch detail"); const missingChannels = Array.isArray(record.missingChannels) ? record.missingChannels as string[] : []; + const missingControlChannels = Array.isArray(record.missingControlChannels) ? record.missingControlChannels as string[] : []; assertCondition(record.ok === false, "infra-blocked preflight should fail", record); assertCondition(record.mode === "dry-run-preflight", "dry-run preflight mode should be reported", record); assertCondition(record.runnerDisposition === "infra-blocked", "runnerDisposition should be infra-blocked", record); assertCondition(Array.isArray(record.missingChannels), "missingChannels should be an array", record); + assertCondition(Array.isArray(record.missingControlChannels), "missingControlChannels should be an array", record); assertCondition(missingChannels.includes("backend-core-api"), "backend-core-api should be missing", record); assertCondition(missingChannels.includes("database"), "database should be missing", record); assertCondition(missingChannels.includes("provider-dispatch"), "provider-dispatch should be missing", record); assertCondition(missingChannels.includes("provider-host-ssh"), "provider-host-ssh should be missing", record); assertCondition(missingChannels.includes("artifact-registry"), "artifact-registry should be missing", record); + assertCondition(missingControlChannels.join(",") === "backend-core,database,provider,registry", "missingControlChannels should name runner-facing domains", record); + assertCondition(controlChannels.length === 4, "controlChannels should report four runner-facing domains", controlChannels); + assertCondition(controlChannels.every((item) => item.ok === false), "infra-blocked transport should fail every control channel", controlChannels); + assertCondition( + (controlChannels.find((item) => item.channel === "provider")?.probes as unknown[]).join(",") === "provider-dispatch,provider-host-ssh", + "provider control channel should map provider dispatch and host ssh probes", + controlChannels, + ); assertCondition(!JSON.stringify(record).includes("No such container: unidesk-database"), "raw container error should not leak", record); assertCondition(backendCoreBody.failureKind === "target-stack-not-running", "backend-core detail should classify target-stack-not-running", backendCoreBody); assertCondition(providerDispatch.status === "infra-blocked", "provider dispatch should be infra-blocked", providerDispatch); @@ -82,6 +94,10 @@ async function main(): Promise { assertCondition(source.mode === "planned-only", "source should remain planned-only", source); assertCondition(source.repoFetchUrl === "git@github.com:pikasTech/unidesk.git", "source repo should use CI catalog ssh form", source); assertCondition(asRecord(record.artifactSummary, "artifactSummary").imageRef === `127.0.0.1:5000/unidesk/frontend:${commit}`, "artifact ref should remain commit-pinned", record.artifactSummary); + assertCondition(controlledPublish.environment === "D601", "controlledPublish should name the controlled environment", controlledPublish); + assertCondition(controlledPublish.namespace === "unidesk-ci", "controlledPublish should name the Tekton namespace", controlledPublish); + assertCondition(controlledPublish.pipeline === "unidesk-user-service-artifact-publish", "controlledPublish should name the user-service pipeline", controlledPublish); + assertCondition(String(controlledPublish.command ?? "").includes("--wait-ms 1200000"), "controlledPublish should provide the real publish command shape", controlledPublish); assertCondition(String(record.boundary ?? "").includes("read-only"), "boundary should state preflight is read-only", record); process.stdout.write(`${JSON.stringify({ @@ -90,8 +106,11 @@ async function main(): Promise { "dry-run preflight returns infra-blocked when backend-core/database/provider channels are absent", "missing channel list names the absent channels", "artifact summary remains commit-pinned and read-only", + "missingControlChannels maps detailed probes to backend-core/database/provider/registry", + "controlledPublish identifies D601 unidesk-ci as the only place for the real publish", ], missingChannels: record.missingChannels, + missingControlChannels: record.missingControlChannels, registry, }, null, 2)}\n`); } diff --git a/scripts/src/ci.ts b/scripts/src/ci.ts index 9d664830..9fd6e857 100644 --- a/scripts/src/ci.ts +++ b/scripts/src/ci.ts @@ -87,13 +87,24 @@ interface DispatchResult { raw: unknown; } +type PublishPreflightControlChannel = "backend-core" | "database" | "provider" | "registry"; +type PublishPreflightDetailedChannel = "backend-core-api" | "provider-dispatch" | "provider-host-ssh" | "database" | "artifact-registry"; + interface PublishPreflightChannelProbe { - channel: "backend-core-api" | "provider-dispatch" | "provider-host-ssh" | "database" | "artifact-registry"; + channel: PublishPreflightDetailedChannel; + controlChannel: PublishPreflightControlChannel; ok: boolean; requiredFor: string; detail: unknown; } +interface PublishPreflightControlChannelProbe { + channel: PublishPreflightControlChannel; + ok: boolean; + requiredFor: string[]; + probes: PublishPreflightDetailedChannel[]; +} + interface PublishPreflight { ok: boolean; runnerDisposition: "ready" | "infra-blocked"; @@ -102,6 +113,8 @@ interface PublishPreflight { providerId: string; supportedArtifactPublish: boolean; missingChannels: string[]; + missingControlChannels: PublishPreflightControlChannel[]; + controlChannels: PublishPreflightControlChannelProbe[]; channels: PublishPreflightChannelProbe[]; registry: unknown; next: string[]; @@ -362,12 +375,27 @@ function responseOk(response: unknown): boolean { } function channelProbe( - channel: PublishPreflightChannelProbe["channel"], + channel: PublishPreflightDetailedChannel, + controlChannel: PublishPreflightControlChannel, ok: boolean, requiredFor: string, detail: unknown, ): PublishPreflightChannelProbe { - return { channel, ok, requiredFor, detail }; + return { channel, controlChannel, ok, requiredFor, detail }; +} + +const publishPreflightControlChannelOrder: PublishPreflightControlChannel[] = ["backend-core", "database", "provider", "registry"]; + +function summarizePublishControlChannels(channels: PublishPreflightChannelProbe[]): PublishPreflightControlChannelProbe[] { + return publishPreflightControlChannelOrder.map((channel) => { + const probes = channels.filter((item) => item.controlChannel === channel); + return { + channel, + ok: probes.length > 0 && probes.every((item) => item.ok), + requiredFor: Array.from(new Set(probes.map((item) => item.requiredFor))), + probes: probes.map((item) => item.channel), + }; + }); } function backendCoreUnavailable(value: unknown): boolean { @@ -1292,7 +1320,7 @@ async function publishUserServicePreflight( const overview = await transport.coreFetch("/api/overview", { maxResponseBytes: 500_000 }); const overviewBody = coreBody(overview); const backendCoreOk = responseOk(overview) && overviewBody?.dbReady === true; - channels.push(channelProbe("backend-core-api", backendCoreOk, "dispatch API, provider catalog, task polling, and database-backed CI state", { + channels.push(channelProbe("backend-core-api", "backend-core", backendCoreOk, "dispatch API, provider catalog, task polling, and database-backed CI state", { ok: responseOk(overview), dbReady: overviewBody?.dbReady ?? null, runnerDisposition: asRecord(overview)?.runnerDisposition ?? null, @@ -1302,7 +1330,7 @@ async function publishUserServicePreflight( body: overviewBody, }, })); - channels.push(channelProbe("database", backendCoreOk, "backend-core task dispatch, provider state, Tekton task polling, and source identity lookup", { + channels.push(channelProbe("database", "database", backendCoreOk, "backend-core task dispatch, provider state, Tekton task polling, and source identity lookup", { dbReady: overviewBody?.dbReady ?? false, observedThrough: "backend-core /api/overview", })); @@ -1316,14 +1344,14 @@ async function publishUserServicePreflight( "test -S /var/run/docker.sock || test -S /run/docker.sock || true", ].join("\n"); const sshProbe = await transport.dispatchHostSsh(probeScript, 30_000, 15_000); - channels.push(channelProbe("provider-dispatch", sshProbe.taskId !== null || sshProbe.ok, "backend-core /api/dispatch can create D601 host.ssh tasks", { + channels.push(channelProbe("provider-dispatch", "provider", sshProbe.taskId !== null || sshProbe.ok, "backend-core /api/dispatch can create D601 host.ssh tasks", { taskId: sshProbe.taskId, status: sshProbe.status, ok: sshProbe.taskId !== null || sshProbe.ok, exitCode: sshProbe.exitCode, stderrTail: sshProbe.stderr.slice(-1200), })); - channels.push(channelProbe("provider-host-ssh", sshProbe.ok, "D601 source export, registry checks, kubectl/Tekton submission, and artifact summary reads", { + channels.push(channelProbe("provider-host-ssh", "provider", sshProbe.ok, "D601 source export, registry checks, kubectl/Tekton submission, and artifact summary reads", { taskId: sshProbe.taskId, status: sshProbe.status, exitCode: sshProbe.exitCode, @@ -1339,9 +1367,11 @@ async function publishUserServicePreflight( const registry = artifactRegistryReadonlyResultFromCommand(registryProbe, registryCommand); const registryRecord = asRecord(registry); const registryOk = registryRecord?.ok === true || registryRecord?.runtimeApiHealthy === true; - channels.push(channelProbe("artifact-registry", registryOk, "commit-pinned image push and later CD manifest checks", registry)); + channels.push(channelProbe("artifact-registry", "registry", registryOk, "commit-pinned image push and later CD manifest checks", registry)); const missingChannels = channels.filter((item) => !item.ok).map((item) => item.channel); + const controlChannels = summarizePublishControlChannels(channels); + const missingControlChannels = controlChannels.filter((item) => !item.ok).map((item) => item.channel); const ready = missingChannels.length === 0; return { ok: ready, @@ -1351,6 +1381,8 @@ async function publishUserServicePreflight( providerId, supportedArtifactPublish: true, missingChannels, + missingControlChannels, + controlChannels, channels, registry, next: ready @@ -1359,6 +1391,7 @@ async function publishUserServicePreflight( `later CD must consume ${plannedArtifact.imageRef}; CI itself must not deploy production`, ] : [ + `Restore missing control channel(s): ${missingControlChannels.join(", ") || "unknown"}.`, "Run from the main-server CLI or use remote frontend transport against a healthy frontend/backend-core path.", "Restore backend-core/database/provider-gateway/Host SSH connectivity before retrying artifact publication.", "Use bun scripts/cli.ts artifact-registry health --provider-id D601 to recheck registry reachability after the control bridge is restored.", @@ -1536,6 +1569,8 @@ async function publishUserServiceArtifact(config: UniDeskConfig, options: CiPubl serviceId: options.serviceId, supportedArtifactPublish: preflight.supportedArtifactPublish, missingChannels: preflight.missingChannels, + missingControlChannels: preflight.missingControlChannels, + controlChannels: preflight.controlChannels, channels: preflight.channels, registry: preflight.registry, sourceHostPath: options.sourceHostPath, @@ -1555,6 +1590,13 @@ async function publishUserServiceArtifact(config: UniDeskConfig, options: CiPubl }, artifact: plannedArtifact.imageRef, artifactSummary: plannedArtifact, + controlledPublish: { + environment: "D601", + namespace: "unidesk-ci", + pipeline: "unidesk-user-service-artifact-publish", + command: `bun scripts/cli.ts ci publish-user-service --service ${options.serviceId} --commit ${options.commit} --wait-ms 1200000`, + requiresReadyControlChannels: publishPreflightControlChannelOrder, + }, boundary: preflight.boundary, next: preflight.next, }; @@ -1652,6 +1694,8 @@ export async function runCiPublishUserServiceDryRunPreflight( serviceId: options.serviceId, supportedArtifactPublish: preflight.supportedArtifactPublish, missingChannels: preflight.missingChannels, + missingControlChannels: preflight.missingControlChannels, + controlChannels: preflight.controlChannels, channels: preflight.channels, registry: preflight.registry, sourceHostPath: options.sourceHostPath, @@ -1671,6 +1715,13 @@ export async function runCiPublishUserServiceDryRunPreflight( }, artifact: plannedArtifact.imageRef, artifactSummary: plannedArtifact, + controlledPublish: { + environment: "D601", + namespace: "unidesk-ci", + pipeline: "unidesk-user-service-artifact-publish", + command: `bun scripts/cli.ts ci publish-user-service --service ${options.serviceId} --commit ${options.commit} --wait-ms 1200000`, + requiresReadyControlChannels: publishPreflightControlChannelOrder, + }, boundary: preflight.boundary, next: preflight.next, };