fix: 保留 catalog bootstrap 并同步 PaC pipeline

ci/pipelines/hwlab-jd01-v03-ci-image-publish.yaml

@@ -718,7 +718,7 @@
                   "value": "hyueapi.com,.hyueapi.com,127.0.0.1,localhost,::1,10.0.0.0/8,10.42.0.0/16,10.43.0.0/16,192.168.0.0/16,.svc,.cluster.local,kubernetes.default.svc,registry.hwlab-ci.svc,hwlab-registry.hwlab-ci.svc,git-mirror-http,git-mirror-http.devops-infra,git-mirror-http.devops-infra.svc,git-mirror-http.devops-infra.svc.cluster.local,git-mirror-write,git-mirror-write.devops-infra,git-mirror-write.devops-infra.svc,git-mirror-write.devops-infra.svc.cluster.local"
                 }
               ],
-              "script": "#!/bin/sh\nset -eu\necho '{\"event\":\"ci-base-image\",\"phase\":\"plan-artifacts\",\"image\":\"127.0.0.1:5000/hwlab/hwlab-ci-node-tools:node22-alpine-bun-v1\",\"policy\":\"no-runtime-apk\"}'\nfor tool in node git; do command -v \"$tool\" >/dev/null 2>&1 || { echo '{\"event\":\"ci-base-image\",\"phase\":\"plan-artifacts\",\"ok\":false,\"reason\":\"missing-tool\",\"tool\":\"'\"$tool\"'\"}'; exit 31; }; done\ncd /workspace/source/repo\nci_node_deps=\"${HWLAB_CI_NODE_DEPS:-/opt/hwlab-ci-node-deps/node_modules}\"\nif [ -d \"$ci_node_deps/yaml\" ] && [ ! -e node_modules/yaml ]; then\n  mkdir -p node_modules\n  ln -s \"$ci_node_deps/yaml\" node_modules/yaml\nfi\ntest \"$(git rev-parse HEAD)\" = \"$(params.revision)\"\nHWLAB_CATALOG_PATH=\"$(params.catalog-path)\" HWLAB_GIT_URL=\"$(params.git-url)\" HWLAB_GIT_READ_URL=\"$(params.git-read-url)\" HWLAB_GITOPS_BRANCH=\"$(params.gitops-branch)\" node scripts/ci/restore-artifact-catalog.mjs\nnode scripts/ci-plan.mjs --lane \"$(params.lane)\" --target-ref HEAD --deploy-config deploy/deploy.yaml --artifact-catalog \"$(params.catalog-path)\" --registry-prefix \"$(params.registry-prefix)\" --services \"$(params.services)\" --verify-reuse-registry > /workspace/source/ci-plan.json\nnode - <<'NODE'\nconst fs = require(\"node:fs\");\nconst plan = JSON.parse(fs.readFileSync(\"/workspace/source/ci-plan.json\", \"utf8\"));\nconst selected = String(process.env.HWLAB_SELECTED_SERVICES || \"\").split(\",\").map((item) => item.trim()).filter(Boolean);\nconst allServices = selected.length > 0 ? selected : [\"hwlab-cloud-api\",\"hwlab-cloud-web\",\"hwlab-gateway\",\"hwlab-edge-proxy\",\"hwlab-agent-skills\"];\nconst affected = new Set(plan.affectedServices || []);\nconst plannedBuildServices = Array.isArray(plan.buildServices) ? new Set(plan.buildServices) : null;\nconst selectedSet = new Set(selected);\nconst byService = new Map((plan.services || []).map((service) => [service.serviceId, service]));\nconst entries = allServices.map((serviceId) => {\n  const service = byService.get(serviceId) || {};\n  const serviceSelected = selectedSet.has(serviceId);\n  const rolloutAffected = serviceSelected && affected.has(serviceId);\n  const envReuse = service.runtimeMode === \"env-reuse-git-mirror-checkout\" || service.envReuse === true;\n  const buildRequired = serviceSelected && (plannedBuildServices ? plannedBuildServices.has(serviceId) : (envReuse ? service.envChanged === true : rolloutAffected));\n  return {\n    serviceId,\n    selected: serviceSelected,\n    affected: rolloutAffected,\n    buildRequired,\n    rolloutAffected,\n    runtimeMode: service.runtimeMode || \"service-image\",\n    envChanged: service.envChanged ?? null,\n    codeChanged: service.codeChanged ?? null\n  };\n});\nfor (const entry of entries) {\n  fs.writeFileSync(\"/tekton/results/affected-\" + entry.serviceId, entry.affected ? \"true\" : \"false\");\n  fs.writeFileSync(\"/tekton/results/build-\" + entry.serviceId, entry.buildRequired ? \"true\" : \"false\");\n}\nfs.writeFileSync(\"/workspace/source/affected-services.json\", JSON.stringify({\n  sourceCommitId: plan.sourceCommitId,\n  affectedServices: plan.affectedServices || [],\n  rolloutServices: plan.rolloutServices || plan.affectedServices || [],\n  buildServices: plan.buildServices || entries.filter((entry) => entry.buildRequired).map((entry) => entry.serviceId),\n  reusedServices: plan.reusedServices || [],\n  buildSkippedCount: plan.buildSkippedCount || 0,\n  envArtifactGroups: plan.envArtifactGroups || [],\n  changedPathSummary: plan.changedPathSummary || null,\n  ciCdPlan: plan.ciCdPlan || null,\n  services: plan.services || [],\n  entries\n}, null, 2) + String.fromCharCode(10));\nconsole.log(JSON.stringify({ event: \"g14-ci-plan\", sourceCommitId: plan.sourceCommitId, affectedServices: plan.affectedServices || [], rolloutServices: plan.rolloutServices || plan.affectedServices || [], buildServices: plan.buildServices || [], reusedServices: plan.reusedServices || [], buildSkippedCount: plan.buildSkippedCount || 0, envArtifactGroups: plan.envArtifactGroups || [] }));\nNODE\n"
+              "script": "#!/bin/sh\nset -eu\necho '{\"event\":\"ci-base-image\",\"phase\":\"plan-artifacts\",\"image\":\"127.0.0.1:5000/hwlab/hwlab-ci-node-tools:node22-alpine-bun-v1\",\"policy\":\"no-runtime-apk\"}'\nfor tool in node git; do command -v \"$tool\" >/dev/null 2>&1 || { echo '{\"event\":\"ci-base-image\",\"phase\":\"plan-artifacts\",\"ok\":false,\"reason\":\"missing-tool\",\"tool\":\"'\"$tool\"'\"}'; exit 31; }; done\ncd /workspace/source/repo\nci_node_deps=\"${HWLAB_CI_NODE_DEPS:-/opt/hwlab-ci-node-deps/node_modules}\"\nif [ -d \"$ci_node_deps/yaml\" ] && [ ! -e node_modules/yaml ]; then\n  mkdir -p node_modules\n  ln -s \"$ci_node_deps/yaml\" node_modules/yaml\nfi\ntest \"$(git rev-parse HEAD)\" = \"$(params.revision)\"\nHWLAB_CATALOG_PATH=\"$(params.catalog-path)\" HWLAB_GIT_URL=\"$(params.git-url)\" HWLAB_GIT_READ_URL=\"$(params.git-read-url)\" HWLAB_GITOPS_BRANCH=\"$(params.gitops-branch)\" HWLAB_SERVICES=\"$(params.services)\" node scripts/ci/restore-artifact-catalog.mjs\nnode scripts/ci-plan.mjs --lane \"$(params.lane)\" --target-ref HEAD --deploy-config deploy/deploy.yaml --artifact-catalog \"$(params.catalog-path)\" --registry-prefix \"$(params.registry-prefix)\" --services \"$(params.services)\" --verify-reuse-registry > /workspace/source/ci-plan.json\nnode - <<'NODE'\nconst fs = require(\"node:fs\");\nconst plan = JSON.parse(fs.readFileSync(\"/workspace/source/ci-plan.json\", \"utf8\"));\nconst selected = String(process.env.HWLAB_SELECTED_SERVICES || \"\").split(\",\").map((item) => item.trim()).filter(Boolean);\nconst allServices = selected.length > 0 ? selected : [\"hwlab-cloud-api\",\"hwlab-cloud-web\",\"hwlab-gateway\",\"hwlab-edge-proxy\",\"hwlab-agent-skills\"];\nconst affected = new Set(plan.affectedServices || []);\nconst plannedBuildServices = Array.isArray(plan.buildServices) ? new Set(plan.buildServices) : null;\nconst selectedSet = new Set(selected);\nconst byService = new Map((plan.services || []).map((service) => [service.serviceId, service]));\nconst entries = allServices.map((serviceId) => {\n  const service = byService.get(serviceId) || {};\n  const serviceSelected = selectedSet.has(serviceId);\n  const rolloutAffected = serviceSelected && affected.has(serviceId);\n  const envReuse = service.runtimeMode === \"env-reuse-git-mirror-checkout\" || service.envReuse === true;\n  const buildRequired = serviceSelected && (plannedBuildServices ? plannedBuildServices.has(serviceId) : (envReuse ? service.envChanged === true : rolloutAffected));\n  return {\n    serviceId,\n    selected: serviceSelected,\n    affected: rolloutAffected,\n    buildRequired,\n    rolloutAffected,\n    runtimeMode: service.runtimeMode || \"service-image\",\n    envChanged: service.envChanged ?? null,\n    codeChanged: service.codeChanged ?? null\n  };\n});\nfor (const entry of entries) {\n  fs.writeFileSync(\"/tekton/results/affected-\" + entry.serviceId, entry.affected ? \"true\" : \"false\");\n  fs.writeFileSync(\"/tekton/results/build-\" + entry.serviceId, entry.buildRequired ? \"true\" : \"false\");\n}\nfs.writeFileSync(\"/workspace/source/affected-services.json\", JSON.stringify({\n  sourceCommitId: plan.sourceCommitId,\n  affectedServices: plan.affectedServices || [],\n  rolloutServices: plan.rolloutServices || plan.affectedServices || [],\n  buildServices: plan.buildServices || entries.filter((entry) => entry.buildRequired).map((entry) => entry.serviceId),\n  rolloutWithoutImageBuildServices: plan.rolloutWithoutImageBuildServices || [],\n  reusedServices: plan.reusedServices || [],\n  serviceReusedCount: plan.serviceReusedCount || 0,\n  imageBuildSkippedServices: plan.imageBuildSkippedServices || [],\n  buildSkippedCount: plan.buildSkippedCount || 0,\n  artifactCatalog: plan.artifactCatalog || null,\n  envArtifactGroups: plan.envArtifactGroups || [],\n  changedPathSummary: plan.changedPathSummary || null,\n  ciCdPlan: plan.ciCdPlan || null,\n  services: plan.services || [],\n  entries\n}, null, 2) + String.fromCharCode(10));\nconsole.log(JSON.stringify({ event: \"g14-ci-plan\", sourceCommitId: plan.sourceCommitId, affectedServices: plan.affectedServices || [], rolloutServices: plan.rolloutServices || plan.affectedServices || [], buildServices: plan.buildServices || [], rolloutWithoutImageBuildServices: plan.rolloutWithoutImageBuildServices || [], reusedServices: plan.reusedServices || [], serviceReusedCount: plan.serviceReusedCount || 0, imageBuildSkippedServices: plan.imageBuildSkippedServices || [], buildSkippedCount: plan.buildSkippedCount || 0, artifactCatalog: plan.artifactCatalog || null, noImageBuildReason: plan.ciCdPlan?.noImageBuildReason || null, envArtifactGroups: plan.envArtifactGroups || [] }));\nNODE\n"
             }
           ]
         },

scripts/ci-plan.mjs

@@ -28,11 +28,13 @@ if (args.help) {
 const noDepsPlan = tryCreateNoDepsPlan(args);
 if (noDepsPlan) {
   const artifactCatalog = await noDepsArtifactCatalogSummary(args);
-  noDepsPlan.artifactCatalog = artifactCatalog;
-  noDepsPlan.compatibility.artifactCatalog = artifactCatalog.status === "missing" ? null : artifactCatalog.catalogPath;
-  noDepsPlan.compatibility.artifactCatalogAuthority = artifactCatalog.authority;
-  process.stdout.write(args.pretty ? `${JSON.stringify(noDepsPlan, null, 2)}\n` : `${JSON.stringify(noDepsPlan)}\n`);
-  process.exit(0);
+  if (catalogAllowsNoDepsReuse(artifactCatalog, args.services)) {
+    noDepsPlan.artifactCatalog = artifactCatalog;
+    noDepsPlan.compatibility.artifactCatalog = artifactCatalog.catalogPath;
+    noDepsPlan.compatibility.artifactCatalogAuthority = artifactCatalog.authority;
+    process.stdout.write(args.pretty ? `${JSON.stringify(noDepsPlan, null, 2)}\n` : `${JSON.stringify(noDepsPlan)}\n`);
+    process.exit(0);
+  }
 }
 
 const { createCiPlan } = await import("./src/ci-plan-lib.mjs");
@@ -43,7 +45,8 @@ function tryCreateNoDepsPlan(options) {
   const services = Array.isArray(options.services) ? options.services.filter(Boolean) : [];
   if (services.length === 0) return null;
   const targetRef = options.targetRef ?? "HEAD";
-  const baseRef = options.baseRef ?? (gitValue(["rev-parse", `${targetRef}^`]) || targetRef);
+  const inferredBaseRef = options.baseRef ?? tryGitValue(["rev-parse", `${targetRef}^`]);
+  const baseRef = inferredBaseRef || targetRef;
   const changedPaths = gitValue(["diff", "--name-only", baseRef, targetRef]).split("\n").map((line) => line.trim()).filter(Boolean);
   const summary = classifyNoDepsGlobalChange(changedPaths);
   if (!summary.gitopsOnly && !summary.docsOnly && !summary.testOnly && summary.summary !== "no-source-diff") return null;
@@ -118,12 +121,21 @@ async function noDepsArtifactCatalogSummary(options) {
       gitopsCommitId: null,
       catalogSourceCommitId: null,
       serviceCount: 0,
-      catalogSha256: null
+      catalogSha256: null,
+      coverage: null,
+      bootstrapReason: null
     };
   }
   return readArtifactCatalogSummary({ repoRoot: process.cwd(), catalogPath });
 }
 
+function catalogAllowsNoDepsReuse(artifactCatalog, selectedServices) {
+  if (artifactCatalog?.status !== "hydrated" || artifactCatalog.authority !== "gitops-branch") return false;
+  const catalogServiceIds = artifactCatalog.coverage?.catalogServiceIds;
+  if (!Array.isArray(catalogServiceIds)) return false;
+  return selectedServices.every((serviceId) => catalogServiceIds.includes(serviceId));
+}
+
 function classifyNoDepsGlobalChange(changedPaths) {
   const relevant = changedPaths.filter(Boolean);
   const testOnly = relevant.length > 0 && relevant.every(isNoDepsTestOnlyPath);
@@ -178,6 +190,14 @@ function gitValue(args) {
   return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 15000 }).trim();
 }
 
+function tryGitValue(args) {
+  try {
+    return gitValue(args);
+  } catch {
+    return "";
+  }
+}
+
 function booleanEnv(value) {
   return ["1", "true", "yes", "on"].includes(String(value ?? "").trim().toLowerCase());
 }

scripts/ci-plan.test.mjs

@@ -87,6 +87,40 @@ test("v03 planner keeps affected code rollouts out of catalog reuse", async () =
   assert.equal(plan.artifactCatalog.serviceCount, 3);
 });
 
+test("tracked PaC remote pipelines pass selected services to catalog restore", async () => {
+  const targets = [
+    {
+      node: "NC01",
+      pipelineName: "hwlab-nc01-v03-ci-image-publish",
+      pipelinePath: "ci/pipelines/hwlab-nc01-v03-ci-image-publish.yaml",
+      pacPath: ".tekton/hwlab-nc01-v03-pac.yaml"
+    },
+    {
+      node: "JD01",
+      pipelineName: "hwlab-jd01-v03-ci-image-publish",
+      pipelinePath: "ci/pipelines/hwlab-jd01-v03-ci-image-publish.yaml",
+      pacPath: ".tekton/hwlab-jd01-v03-pac.yaml"
+    }
+  ];
+
+  for (const target of targets) {
+    const pipeline = JSON.parse(await readFile(target.pipelinePath, "utf8"));
+    assert.equal(pipeline.metadata?.name, target.pipelineName, `${target.node} tracked Pipeline name`);
+    const planArtifacts = pipeline.spec?.tasks?.find((task) => task.name === "plan-artifacts");
+    assert.ok(planArtifacts, `${target.node} tracked Pipeline plan-artifacts task`);
+    assert.ok(planArtifacts.taskSpec?.params?.some((param) => param.name === "services"), `${target.node} plan-artifacts services param`);
+    assert.ok(planArtifacts.params?.some((param) => param.name === "services" && param.value === "$(params.services)"), `${target.node} plan-artifacts services binding`);
+    const script = planArtifacts.taskSpec?.steps?.[0]?.script ?? "";
+    assert.match(script, /HWLAB_SERVICES="\$\(params\.services\)" node scripts\/ci\/restore-artifact-catalog\.mjs/u);
+    assert.match(script, /rolloutWithoutImageBuildServices/u);
+    assert.match(script, /artifactCatalog: plan\.artifactCatalog/u);
+
+    const pac = await readFile(target.pacPath, "utf8");
+    assert.ok(pac.includes(`pipelinesascode.tekton.dev/pipeline: "${target.pipelinePath}"`), `${target.node} PaC remote Pipeline path`);
+    assert.ok(pac.includes(`pipelineRef:\n    name: ${target.pipelineName}`), `${target.node} PaC PipelineRef`);
+  }
+});
+
 test("artifact catalog restore refreshes GitOps authority even when a source file exists", async () => {
   const repo = await createFixtureRepo();
   const sourceBranch = (await git(repo, ["branch", "--show-current"])).stdout.trim();
@@ -117,6 +151,7 @@ test("artifact catalog restore refreshes GitOps authority even when a source fil
   assert.equal(authority.authority, "gitops-branch");
   assert.equal(authority.gitopsCommitId, gitopsCommitId);
   assert.equal(authority.catalogSourceCommitId, "a".repeat(40));
+  assert.equal(authority.coverage.status, "exact");
   assert.match(restore.stderr, /"status":"hydrated"/u);
 
   const plan = await createCiPlan({
@@ -130,10 +165,21 @@ test("artifact catalog restore refreshes GitOps authority even when a source fil
   assert.equal(plan.artifactCatalog.status, "hydrated");
   assert.equal(plan.artifactCatalog.authority, "gitops-branch");
   assert.equal(plan.artifactCatalog.gitopsCommitId, gitopsCommitId);
+  assert.equal(plan.artifactCatalog.coverage.status, "exact");
   assert.equal(plan.compatibility.artifactCatalogAuthority, "gitops-branch");
+
+  const fastPlan = await runCiPlanCli(repo, [
+    "--lane", "v03",
+    "--base-ref", "HEAD",
+    "--target-ref", "HEAD",
+    "--artifact-catalog", "deploy/artifact-catalog.v03.json",
+    "--services", "hwlab-cloud-api,hwlab-cloud-web"
+  ]);
+  assert.equal(fastPlan.compatibility.mode, "no-deps-global-change-fast-path");
+  assert.deepEqual(sortedServiceIds(fastPlan.reusedServices), ["hwlab-cloud-api", "hwlab-cloud-web"]);
 });
 
-test("artifact catalog restore rejects a GitOps service-set mismatch", async () => {
+test("artifact catalog restore hydrates partial GitOps coverage and builds missing services", async () => {
   const repo = await createFixtureRepo();
   const sourceBranch = (await git(repo, ["branch", "--show-current"])).stdout.trim();
   await git(repo, ["checkout", "-b", "fixture-gitops-mismatch"]);
@@ -145,21 +191,200 @@ test("artifact catalog restore rejects a GitOps service-set mismatch", async ()
   await git(repo, ["commit", "-m", "remove a service from gitops catalog"]);
   await git(repo, ["checkout", sourceBranch]);
 
+  const restore = await execFileAsync(process.execPath, [path.resolve("scripts/ci/restore-artifact-catalog.mjs")], {
+    cwd: repo,
+    env: {
+      ...process.env,
+      HWLAB_CATALOG_PATH: "deploy/artifact-catalog.v03.json",
+      HWLAB_GITOPS_BRANCH: "fixture-gitops-mismatch",
+      HWLAB_GIT_READ_URL: repo,
+      HWLAB_SERVICES: "hwlab-cloud-api,hwlab-cloud-web"
+    }
+  });
+  assert.match(restore.stderr, /"status":"partial"/u);
+  assert.match(restore.stderr, /"missingSelectedServices":\["hwlab-cloud-web"\]/u);
+
+  const plan = await createCiPlan({
+    repoRoot: repo,
+    lane: "v03",
+    baseRef: "HEAD",
+    targetRef: "HEAD",
+    artifactCatalogPath: "deploy/artifact-catalog.v03.json",
+    services: ["hwlab-cloud-api", "hwlab-cloud-web"]
+  });
+  assert.equal(plan.artifactCatalog.authority, "gitops-branch");
+  assert.equal(plan.artifactCatalog.coverage.status, "partial");
+  assert.deepEqual(plan.artifactCatalog.coverage.missingSelectedServices, ["hwlab-cloud-web"]);
+  assert.deepEqual(sortedServiceIds(plan.buildServices), ["hwlab-cloud-web"]);
+
+  const cliPlan = await runCiPlanCli(repo, [
+    "--lane", "v03",
+    "--base-ref", "HEAD",
+    "--target-ref", "HEAD",
+    "--artifact-catalog", "deploy/artifact-catalog.v03.json",
+    "--services", "hwlab-cloud-api,hwlab-cloud-web"
+  ]);
+  assert.equal(cliPlan.changedPathSummary.summary, "no-source-diff");
+  assert.equal(cliPlan.compatibility.mode, "advisory-read-only");
+  assert.deepEqual(cliPlan.artifactCatalog.coverage.missingSelectedServices, ["hwlab-cloud-web"]);
+  assert.deepEqual(sortedServiceIds(cliPlan.buildServices), ["hwlab-cloud-web"]);
+});
+
+test("v03 planner builds all services when the GitOps branch is absent", async () => {
+  const repo = await createFixtureRepo({ catalog: false });
+  const serviceIds = ["hwlab-cloud-api", "hwlab-cloud-web"];
+  const restore = await execFileAsync(process.execPath, [path.resolve("scripts/ci/restore-artifact-catalog.mjs")], {
+    cwd: repo,
+    env: {
+      ...process.env,
+      HWLAB_CATALOG_PATH: "deploy/artifact-catalog.v03.json",
+      HWLAB_GITOPS_BRANCH: "fixture-gitops-missing",
+      HWLAB_GIT_READ_URL: repo,
+      HWLAB_SERVICES: serviceIds.join(",")
+    }
+  });
+  assert.match(restore.stderr, /"status":"missing"/u);
+  assert.match(restore.stderr, /"reason":"gitops-branch-missing"/u);
+
+  const plan = await createCiPlan({
+    repoRoot: repo,
+    lane: "v03",
+    baseRef: "HEAD",
+    targetRef: "HEAD",
+    artifactCatalogPath: "deploy/artifact-catalog.v03.json",
+    services: serviceIds
+  });
+  assert.equal(plan.artifactCatalog.authority, "none");
+  assert.deepEqual(sortedServiceIds(plan.buildServices), sortedServiceIds(serviceIds));
+});
+
+test("ci-plan CLI bypasses no-deps reuse when the v03 artifact catalog is missing", async () => {
+  const repo = await createFixtureRepo({ catalog: false });
+  const serviceIds = ["hwlab-cloud-api", "hwlab-cloud-web"];
+  const commonArgs = [
+    "--lane", "v03",
+    "--target-ref", "HEAD",
+    "--artifact-catalog", "deploy/artifact-catalog.v03.json",
+    "--services", serviceIds.join(",")
+  ];
+
+  const initialPlan = await runCiPlanCli(repo, commonArgs);
+  assert.equal(initialPlan.baseRef, "HEAD");
+  assert.equal(initialPlan.changedPathSummary.summary, "no-source-diff");
+  assert.equal(initialPlan.compatibility.mode, "advisory-read-only");
+  assert.equal(initialPlan.artifactCatalog.authority, "none");
+  assert.deepEqual(sortedServiceIds(initialPlan.buildServices), sortedServiceIds(serviceIds));
+  assert.deepEqual(initialPlan.reusedServices, []);
+
+  await mkdir(path.join(repo, "docs/reference"), { recursive: true });
+  await writeFile(path.join(repo, "docs/reference/bootstrap.md"), "bootstrap docs\n");
+  await git(repo, ["add", "docs/reference/bootstrap.md"]);
+  await git(repo, ["commit", "-m", "add bootstrap docs"]);
+
+  const docsPlan = await runCiPlanCli(repo, ["--base-ref", "HEAD~1", ...commonArgs]);
+  assert.equal(docsPlan.changedPathSummary.docsOnly, true);
+  assert.equal(docsPlan.compatibility.mode, "advisory-read-only");
+  assert.deepEqual(sortedServiceIds(docsPlan.buildServices), sortedServiceIds(serviceIds));
+  assert.deepEqual(docsPlan.reusedServices, []);
+});
+
+test("v03 planner builds all services when the GitOps branch has no catalog", async () => {
+  const repo = await createFixtureRepo({ catalog: false });
+  const sourceBranch = (await git(repo, ["branch", "--show-current"])).stdout.trim();
+  const serviceIds = ["hwlab-cloud-api", "hwlab-cloud-web"];
+  const restore = await execFileAsync(process.execPath, [path.resolve("scripts/ci/restore-artifact-catalog.mjs")], {
+    cwd: repo,
+    env: {
+      ...process.env,
+      HWLAB_CATALOG_PATH: "deploy/artifact-catalog.v03.json",
+      HWLAB_GITOPS_BRANCH: sourceBranch,
+      HWLAB_GIT_READ_URL: repo,
+      HWLAB_SERVICES: serviceIds.join(",")
+    }
+  });
+  assert.match(restore.stderr, /"status":"missing"/u);
+  assert.match(restore.stderr, /"reason":"gitops-catalog-missing"/u);
+
+  const plan = await createCiPlan({
+    repoRoot: repo,
+    lane: "v03",
+    baseRef: "HEAD",
+    targetRef: "HEAD",
+    artifactCatalogPath: "deploy/artifact-catalog.v03.json",
+    services: serviceIds
+  });
+  assert.equal(plan.artifactCatalog.authority, "none");
+  assert.deepEqual(sortedServiceIds(plan.buildServices), sortedServiceIds(serviceIds));
+});
+
+test("v02 planner accepts a current contract skeleton when the GitOps catalog is absent", async () => {
+  const repo = await createFixtureRepo({ catalog: false });
+  const sourceBranch = (await git(repo, ["branch", "--show-current"])).stdout.trim();
+  const sourceCommitId = (await git(repo, ["rev-parse", "HEAD"])).stdout.trim();
+  const catalogPath = path.join(repo, "deploy/artifact-catalog.v02.json");
+  const serviceIds = ["hwlab-cloud-api", "hwlab-cloud-web"];
+  const skeleton = {
+    catalogVersion: "v1",
+    kind: "hwlab-artifact-catalog",
+    environment: "v02",
+    profile: "v02",
+    namespace: "hwlab-v02",
+    commitId: sourceCommitId,
+    artifactState: "contract-skeleton",
+    publish: { sourceCommitId },
+    services: serviceIds.map((serviceId) => ({
+      serviceId,
+      sourceCommitId,
+      digest: null,
+      buildBackend: "contract-skeleton"
+    }))
+  };
+  await writeFile(catalogPath, `${JSON.stringify(skeleton, null, 2)}\n`);
+
+  const restore = await execFileAsync(process.execPath, [path.resolve("scripts/ci/restore-artifact-catalog.mjs")], {
+    cwd: repo,
+    env: {
+      ...process.env,
+      HWLAB_CATALOG_PATH: "deploy/artifact-catalog.v02.json",
+      HWLAB_GITOPS_BRANCH: sourceBranch,
+      HWLAB_GIT_READ_URL: repo,
+      HWLAB_SERVICES: serviceIds.join(",")
+    }
+  });
+  assert.match(restore.stderr, /"status":"bootstrap"/u);
+  assert.match(restore.stderr, /"authority":"source-bootstrap"/u);
+
+  const plan = await createCiPlan({
+    repoRoot: repo,
+    lane: "v02",
+    baseRef: "HEAD",
+    targetRef: "HEAD",
+    artifactCatalogPath: "deploy/artifact-catalog.v02.json",
+    services: serviceIds
+  });
+  assert.equal(plan.artifactCatalog.status, "bootstrap");
+  assert.equal(plan.artifactCatalog.authority, "source-bootstrap");
+  assert.equal(plan.artifactCatalog.sourceCommitId, sourceCommitId);
+  assert.equal(plan.artifactCatalog.coverage.status, "exact");
+  assert.deepEqual(sortedServiceIds(plan.buildServices), sortedServiceIds(serviceIds));
+});
+
+test("artifact catalog restore rejects a non-bootstrap source catalog when GitOps is absent", async () => {
+  const repo = await createFixtureRepo();
   await assert.rejects(
     execFileAsync(process.execPath, [path.resolve("scripts/ci/restore-artifact-catalog.mjs")], {
       cwd: repo,
       env: {
         ...process.env,
         HWLAB_CATALOG_PATH: "deploy/artifact-catalog.v03.json",
-        HWLAB_GITOPS_BRANCH: "fixture-gitops-mismatch",
+        HWLAB_GITOPS_BRANCH: "fixture-gitops-missing",
         HWLAB_GIT_READ_URL: repo,
         HWLAB_SERVICES: "hwlab-cloud-api,hwlab-cloud-web"
       }
     }),
     (error) => {
       assert.equal(error.code, 1);
-      assert.match(error.stderr, /"reason":"gitops-catalog-service-ids-mismatch"/u);
-      assert.match(error.stderr, /missing=hwlab-cloud-web/u);
+      assert.match(error.stderr, /existing source catalog is not an allowed v02 contract skeleton/u);
       return true;
     }
   );
@@ -1743,6 +1968,11 @@ function uniquePreserveOrder(values) {
   return result;
 }
 
+async function runCiPlanCli(repo, args) {
+  const { stdout } = await execFileAsync(process.execPath, [path.resolve("scripts/ci-plan.mjs"), ...args], { cwd: repo });
+  return JSON.parse(stdout);
+}
+
 async function git(cwd, args) {
   return execFileAsync("git", ["-c", "user.name=HWLAB Test", "-c", "user.email=hwlab-test@example.invalid", ...args], { cwd });
 }

scripts/ci/restore-artifact-catalog.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 // Restore the node/lane artifact catalog from the GitOps branch before CI planning.
 
-import { execFileSync } from "node:child_process";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 
 import {
   artifactCatalogAuthorityPath,
+  artifactCatalogServiceCoverage,
+  createBootstrapArtifactCatalogAuthority,
   createHydratedArtifactCatalogAuthority
 } from "../src/artifact-catalog-authority.mjs";
 
@@ -42,6 +44,21 @@ function git(args, options = {}) {
   });
 }
 
+function gitProbe(args, options = {}) {
+  const result = spawnSync("git", args, {
+    cwd: process.cwd(),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: options.timeoutMs ?? 45_000
+  });
+  if (result.error) throw result.error;
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? ""
+  };
+}
+
 const catalogPath = env("HWLAB_CATALOG_PATH");
 const gitopsBranch = env("HWLAB_GITOPS_BRANCH");
 const remote = env("HWLAB_GIT_READ_URL") ?? env("HWLAB_GIT_URL");
@@ -60,27 +77,42 @@ if (!catalogPath || !gitopsBranch || !remote || selectedServices.length === 0) {
 }
 
 try {
+  const selectedServiceCoverageInput = uniqueSorted(selectedServices);
+  if (selectedServiceCoverageInput.length !== selectedServices.length) {
+    throw new Error("selected services contain duplicate service ids");
+  }
+  const branchProbe = gitProbe(["ls-remote", "--exit-code", "--heads", remote, `refs/heads/${gitopsBranch}`], { timeoutMs: 45_000 });
+  if (branchProbe.status === 2) {
+    restoreBootstrapOrMissing({ reason: "gitops-branch-missing", selectedServices: selectedServiceCoverageInput });
+    process.exit(0);
+  }
+  if (branchProbe.status !== 0) {
+    throw new Error(`gitops branch probe failed: ${boundedError(branchProbe.stderr)}`);
+  }
   git(["fetch", "--depth=1", remote, `refs/heads/${gitopsBranch}`], { capture: false, timeoutMs: 60_000 });
   const gitopsCommitId = git(["rev-parse", "FETCH_HEAD"], { timeoutMs: 15_000 }).trim();
+  const catalogProbe = gitProbe(["ls-tree", "-z", "--full-tree", "--name-only", "FETCH_HEAD", "--", catalogPath], { timeoutMs: 15_000 });
+  if (catalogProbe.status !== 0) {
+    throw new Error(`gitops catalog tree probe failed: ${boundedError(catalogProbe.stderr)}`);
+  }
+  if (catalogProbe.stdout.length === 0) {
+    restoreBootstrapOrMissing({ reason: "gitops-catalog-missing", selectedServices: selectedServiceCoverageInput });
+    process.exit(0);
+  }
   const content = git(["show", `FETCH_HEAD:${catalogPath}`], { timeoutMs: 30_000 });
   const parsed = JSON.parse(content);
   if (!Array.isArray(parsed?.services) || parsed.services.length === 0) {
     throw new Error("gitops catalog has no services");
   }
-  const actualServices = parsed.services.map((service) => nonEmptyText(service?.serviceId)).filter(Boolean);
-  const expected = uniqueSorted(selectedServices);
-  const actual = uniqueSorted(actualServices);
-  const missing = expected.filter((serviceId) => !actual.includes(serviceId));
-  const extra = actual.filter((serviceId) => !expected.includes(serviceId));
-  const invalidEntryCount = parsed.services.length - actualServices.length;
-  const duplicateCount = actualServices.length - actual.length;
-  if (missing.length > 0 || extra.length > 0 || invalidEntryCount > 0 || duplicateCount > 0) {
-    const error = new Error(`gitops catalog service ids mismatch: missing=${missing.join(",") || "none"} extra=${extra.join(",") || "none"} invalid=${invalidEntryCount} duplicate=${duplicateCount}`);
-    error.code = "catalog-service-ids-mismatch";
-    throw error;
-  }
+  const coverage = artifactCatalogServiceCoverage(parsed, selectedServiceCoverageInput);
   const authorityPath = artifactCatalogAuthorityPath(catalogPath);
-  const authority = createHydratedArtifactCatalogAuthority({ catalog: parsed, catalogPath, gitopsBranch, gitopsCommitId });
+  const authority = createHydratedArtifactCatalogAuthority({
+    catalog: parsed,
+    catalogPath,
+    gitopsBranch,
+    gitopsCommitId,
+    selectedServices: selectedServiceCoverageInput
+  });
   mkdirSync(dirname(catalogPath), { recursive: true });
   writeFileSync(catalogPath, JSON.stringify(parsed, null, 2) + "\n");
   writeFileSync(authorityPath, JSON.stringify(authority, null, 2) + "\n");
@@ -94,22 +126,78 @@ try {
     catalogSha256: authority.catalogSha256,
     serviceCount: parsed.services.length,
     selectedServiceCount: selectedServices.length,
+    coverage,
     bytes: Buffer.byteLength(content)
   });
 } catch (error) {
   emit({
     status: "failed",
-    reason: error?.code === "catalog-service-ids-mismatch" ? "gitops-catalog-service-ids-mismatch" : "gitops-catalog-unavailable",
+    reason: "gitops-catalog-unavailable",
     error: error instanceof Error ? error.message.slice(0, 500) : String(error).slice(0, 500)
   });
   process.exit(1);
 }
 
-function nonEmptyText(value) {
-  const result = typeof value === "string" ? value.trim() : "";
-  return result || null;
+function restoreBootstrapOrMissing({ reason, selectedServices }) {
+  const authorityPath = artifactCatalogAuthorityPath(catalogPath);
+  if (!existsSync(catalogPath)) {
+    if (existsSync(authorityPath)) throw new Error(`artifact catalog authority exists without catalog ${catalogPath}`);
+    emit({
+      status: "missing",
+      reason,
+      authority: "none",
+      selectedServiceCount: selectedServices.length
+    });
+    return;
+  }
+  const catalog = JSON.parse(readFileSync(catalogPath, "utf8"));
+  const sourceCommitId = git(["rev-parse", "HEAD"], { timeoutMs: 15_000 }).trim();
+  validateBootstrapCatalog({ catalog, sourceCommitId, selectedServices });
+  const authority = createBootstrapArtifactCatalogAuthority({
+    catalog,
+    catalogPath,
+    sourceCommitId,
+    reason,
+    selectedServices
+  });
+  writeFileSync(authorityPath, JSON.stringify(authority, null, 2) + "\n");
+  emit({
+    status: "bootstrap",
+    reason,
+    authority: authority.authority,
+    authorityPath,
+    sourceCommitId,
+    serviceCount: authority.serviceCount,
+    catalogSha256: authority.catalogSha256,
+    coverage: authority.coverage
+  });
 }
 
 function uniqueSorted(values) {
   return [...new Set(values)].sort();
 }
+
+function validateBootstrapCatalog({ catalog, sourceCommitId, selectedServices }) {
+  if (catalog?.catalogVersion !== "v1" || catalog?.kind !== "hwlab-artifact-catalog" || catalog?.artifactState !== "contract-skeleton" || catalog?.environment !== "v02" || catalog?.profile !== "v02") {
+    throw new Error(`existing source catalog is not an allowed v02 contract skeleton for ${catalogPath}`);
+  }
+  if (catalog?.publish?.sourceCommitId !== sourceCommitId) {
+    throw new Error(`v02 contract skeleton source commit does not match HEAD for ${catalogPath}`);
+  }
+  const coverage = artifactCatalogServiceCoverage(catalog, selectedServices);
+  if (coverage.status !== "exact") {
+    throw new Error(`v02 contract skeleton service coverage is ${coverage.status} for ${catalogPath}`);
+  }
+  const unsafe = catalog.services.filter((service) => (
+    service?.sourceCommitId !== sourceCommitId
+    || service?.buildBackend !== "contract-skeleton"
+    || service?.digest !== null
+    || (service?.environmentDigest !== undefined && service?.environmentDigest !== null)
+  ));
+  if (unsafe.length > 0) throw new Error(`v02 contract skeleton contains reusable artifacts for ${catalogPath}`);
+}
+
+function boundedError(value) {
+  const result = String(value ?? "").replace(/\s+/gu, " ").trim();
+  return result ? result.slice(0, 300) : "exit-without-stderr";
+}

scripts/src/artifact-catalog-authority.mjs

@@ -17,7 +17,27 @@ export function artifactCatalogSourceCommitId(catalog) {
   return serviceCommits.length === 1 ? serviceCommits[0] : null;
 }
 
-export function createHydratedArtifactCatalogAuthority({ catalog, catalogPath, gitopsBranch, gitopsCommitId }) {
+export function artifactCatalogServiceCoverage(catalog, selectedServices) {
+  if (!Array.isArray(catalog?.services)) throw new Error("artifact catalog services must be an array");
+  const selectedServiceIds = normalizedServiceIds(selectedServices, "selected services");
+  const catalogServiceIds = normalizedServiceIds(catalog.services.map((service) => service?.serviceId), "artifact catalog services");
+  const missingSelectedServices = selectedServiceIds.filter((serviceId) => !catalogServiceIds.includes(serviceId));
+  const extraCatalogServices = catalogServiceIds.filter((serviceId) => !selectedServiceIds.includes(serviceId));
+  return {
+    status: missingSelectedServices.length > 0
+      ? (extraCatalogServices.length > 0 ? "divergent" : "partial")
+      : (extraCatalogServices.length > 0 ? "superset" : "exact"),
+    selectedServiceCount: selectedServiceIds.length,
+    selectedServicePresentCount: selectedServiceIds.length - missingSelectedServices.length,
+    catalogServiceCount: catalogServiceIds.length,
+    selectedServiceIds,
+    catalogServiceIds,
+    missingSelectedServices,
+    extraCatalogServices
+  };
+}
+
+export function createHydratedArtifactCatalogAuthority({ catalog, catalogPath, gitopsBranch, gitopsCommitId, selectedServices }) {
   return {
     schemaVersion: "v1",
     status: "hydrated",
@@ -27,7 +47,23 @@ export function createHydratedArtifactCatalogAuthority({ catalog, catalogPath, g
     gitopsCommitId: text(gitopsCommitId),
     catalogSourceCommitId: artifactCatalogSourceCommitId(catalog),
     serviceCount: Array.isArray(catalog?.services) ? catalog.services.length : 0,
-    catalogSha256: artifactCatalogSha256(catalog)
+    catalogSha256: artifactCatalogSha256(catalog),
+    coverage: artifactCatalogServiceCoverage(catalog, selectedServices)
+  };
+}
+
+export function createBootstrapArtifactCatalogAuthority({ catalog, catalogPath, sourceCommitId, reason, selectedServices }) {
+  return {
+    schemaVersion: "v1",
+    status: "bootstrap",
+    authority: "source-bootstrap",
+    catalogPath: normalizeCatalogPath(catalogPath),
+    sourceCommitId: text(sourceCommitId),
+    bootstrapReason: text(reason),
+    catalogSourceCommitId: artifactCatalogSourceCommitId(catalog),
+    serviceCount: Array.isArray(catalog?.services) ? catalog.services.length : 0,
+    catalogSha256: artifactCatalogSha256(catalog),
+    coverage: artifactCatalogServiceCoverage(catalog, selectedServices)
   };
 }
 
@@ -46,7 +82,9 @@ export async function readArtifactCatalogSummary({ repoRoot, catalogPath, author
       gitopsCommitId: null,
       catalogSourceCommitId: null,
       serviceCount: 0,
-      catalogSha256: null
+      catalogSha256: null,
+      coverage: null,
+      bootstrapReason: null
     };
   }
 
@@ -63,27 +101,49 @@ export async function readArtifactCatalogSummary({ repoRoot, catalogPath, author
       gitopsCommitId: null,
       catalogSourceCommitId,
       serviceCount,
-      catalogSha256
+      catalogSha256,
+      coverage: null,
+      bootstrapReason: null
     };
   }
 
-  validateHydratedAuthority({ authority, catalogPath: normalizedCatalogPath, serviceCount, catalogSha256 });
+  const coverage = validateCatalogAuthority({ authority, catalog: loadedCatalog, catalogPath: normalizedCatalogPath, serviceCount, catalogSha256 });
+  if (authority.authority === "gitops-branch") {
+    return {
+      status: "hydrated",
+      authority: "gitops-branch",
+      catalogPath: normalizedCatalogPath,
+      authorityPath: normalizeCatalogPath(authorityPath),
+      gitopsBranch: text(authority.gitopsBranch),
+      gitopsCommitId: text(authority.gitopsCommitId),
+      catalogSourceCommitId: text(authority.catalogSourceCommitId) || catalogSourceCommitId,
+      serviceCount,
+      catalogSha256,
+      coverage,
+      bootstrapReason: null
+    };
+  }
   return {
-    status: "hydrated",
-    authority: "gitops-branch",
+    status: "bootstrap",
+    authority: "source-bootstrap",
     catalogPath: normalizedCatalogPath,
     authorityPath: normalizeCatalogPath(authorityPath),
-    gitopsBranch: text(authority.gitopsBranch),
-    gitopsCommitId: text(authority.gitopsCommitId),
+    gitopsBranch: null,
+    gitopsCommitId: null,
+    sourceCommitId: text(authority.sourceCommitId),
     catalogSourceCommitId: text(authority.catalogSourceCommitId) || catalogSourceCommitId,
     serviceCount,
-    catalogSha256
+    catalogSha256,
+    coverage,
+    bootstrapReason: text(authority.bootstrapReason)
   };
 }
 
-function validateHydratedAuthority({ authority, catalogPath, serviceCount, catalogSha256 }) {
-  if (authority.schemaVersion !== "v1" || authority.status !== "hydrated" || authority.authority !== "gitops-branch") {
-    throw new Error(`artifact catalog authority for ${catalogPath} is not a hydrated gitops-branch record`);
+function validateCatalogAuthority({ authority, catalog, catalogPath, serviceCount, catalogSha256 }) {
+  const gitopsAuthority = authority.schemaVersion === "v1" && authority.status === "hydrated" && authority.authority === "gitops-branch";
+  const bootstrapAuthority = authority.schemaVersion === "v1" && authority.status === "bootstrap" && authority.authority === "source-bootstrap";
+  if (!gitopsAuthority && !bootstrapAuthority) {
+    throw new Error(`artifact catalog authority for ${catalogPath} is not a supported authority record`);
   }
   if (normalizeCatalogPath(authority.catalogPath) !== catalogPath) {
     throw new Error(`artifact catalog authority path mismatch: expected ${catalogPath}, got ${authority.catalogPath ?? "missing"}`);
@@ -94,9 +154,21 @@ function validateHydratedAuthority({ authority, catalogPath, serviceCount, catal
   if (authority.catalogSha256 !== catalogSha256) {
     throw new Error(`artifact catalog authority fingerprint mismatch for ${catalogPath}`);
   }
-  if (!text(authority.gitopsBranch) || !/^[a-f0-9]{40}$/u.test(text(authority.gitopsCommitId) ?? "")) {
+  const coverage = artifactCatalogServiceCoverage(catalog, authority.coverage?.selectedServiceIds);
+  validateCoverageRecord(authority.coverage, coverage, catalogPath);
+  if (gitopsAuthority && (!text(authority.gitopsBranch) || !/^[a-f0-9]{40}$/u.test(text(authority.gitopsCommitId) ?? ""))) {
     throw new Error(`artifact catalog authority gitops provenance is incomplete for ${catalogPath}`);
   }
+  if (bootstrapAuthority) {
+    const sourceCommitId = text(authority.sourceCommitId);
+    if (!/^[a-f0-9]{40}$/u.test(sourceCommitId ?? "") || !text(authority.bootstrapReason)) {
+      throw new Error(`artifact catalog bootstrap authority is incomplete for ${catalogPath}`);
+    }
+    if (sourceCommitId !== artifactCatalogSourceCommitId(catalog)) {
+      throw new Error(`artifact catalog bootstrap source commit mismatch for ${catalogPath}`);
+    }
+  }
+  return coverage;
 }
 
 async function readJsonIfPresent(repoRoot, filePath) {
@@ -121,3 +193,38 @@ function text(value) {
 function unique(values) {
   return [...new Set(values)];
 }
+
+function normalizedServiceIds(values, label) {
+  if (!Array.isArray(values) || values.length === 0) throw new Error(`${label} must be a non-empty array`);
+  const normalized = values.map(text);
+  if (normalized.some((value) => value === null)) throw new Error(`${label} contains an empty service id`);
+  const deduplicated = unique(normalized);
+  if (deduplicated.length !== normalized.length) throw new Error(`${label} contains duplicate service ids`);
+  return deduplicated.sort();
+}
+
+function validateCoverageRecord(actual, expected, catalogPath) {
+  const scalarFields = ["status", "selectedServiceCount", "selectedServicePresentCount", "catalogServiceCount"];
+  const arrayFields = ["selectedServiceIds", "catalogServiceIds", "missingSelectedServices", "extraCatalogServices"];
+  const expectedFields = [...scalarFields, ...arrayFields].sort();
+  const actualFields = actual && typeof actual === "object" && !Array.isArray(actual)
+    ? Object.keys(actual).sort()
+    : [];
+  if (!sameArray(actualFields, expectedFields)) {
+    throw new Error(`artifact catalog authority coverage fields mismatch for ${catalogPath}`);
+  }
+  for (const field of scalarFields) {
+    if (actual[field] !== expected[field]) {
+      throw new Error(`artifact catalog authority coverage ${field} mismatch for ${catalogPath}`);
+    }
+  }
+  for (const field of arrayFields) {
+    if (!sameArray(actual[field], expected[field])) {
+      throw new Error(`artifact catalog authority coverage ${field} mismatch for ${catalogPath}`);
+    }
+  }
+}
+
+function sameArray(left, right) {
+  return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((value, index) => value === right[index]);
+}