@norskvideo/ctl-dev-kit 0.2.37 → 0.2.38

package/conventions/build-image.yml

@@ -269,11 +269,205 @@ jobs:
             docker rm -f $s
           fi
 
+  # THE PUBLISH GATE. Nothing is published -- no dated tag, no channel tag, no
+  # channels row -- until both halves pass: the repo's own checks, and its guides
+  # (the end-to-end journey the nightly manual is generated from). Until
+  # 2026-10-06 publish needed only [label, build], so a bot push that passed unit
+  # tests shipped a probe whose preview was broken for four days, while the one
+  # test that knew sat red in a nightly nobody saw (task 57).
+  gate-checks:
+    uses: ./.github/workflows/checks.yml
+    with:
+      report: false
+    secrets: inherit
+
+  # The guides run from the SAME commit as the image, exactly as the nightly
+  # publish-docs.yml runs them -- these steps are its steps (a convention test
+  # holds them identical). Skipped, with the reason carried to the published row
+  # and the board, for a build-only repo, a product with no guides, or one that
+  # opted out in .github/publish-gate.json.
+  gate-guides:
+    needs: label
+    runs-on: x64
+    outputs:
+      guides: ${{ steps.plan.outputs.guides }}
+      reason: ${{ steps.plan.outputs.reason }}
+    steps:
+      # Runs BEFORE checkout, and does two things: points the harness's temp base
+      # out of the workspace for every later step in this job, and clears whatever
+      # the old repo-local default left behind on this runner. The body carries the
+      # why. It fails the job only when legacy litter survives -- which would take
+      # the checkout down a step later anyway, but report nothing useful.
+      - name: Route test-temp out of the workspace (pre-checkout)
+        run: |
+          set -uo pipefail
+          # These runners are docker-OUTSIDE-of-docker, so a bind-mount source the
+          # HOST daemon has not seen before is created by dockerd, as ROOT, on the
+          # host -- even when the launch passes --container-user (reproduced
+          # 2026-09-04). The harness's default base is repo-local for an OrbStack
+          # inotify constraint that binds macOS dev and nothing here, so every run
+          # seeded the CHECKOUT with root-owned dirs a non-root `git clean -ffdx`
+          # cannot remove. That took commentary's checks AND integration red on
+          # 2026-09-03. Use the sanctioned override, per-run and outside the
+          # checkout -- as 8ff17a8d did in June for one debug workflow, and stopped.
+          base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          mkdir -p "$base"
+          echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
+          # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
+          # EACCESes. They cannot wedge a checkout, but they do fill the disk.
+          for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
+            docker run --rm --user 0:0 -v "$RUNNER_TEMP":/t alpine sh -c 'rm -rf -- "/t/$1"' sh "$old" >/dev/null 2>&1 || true
+          done
+          # LEGACY: a runner that ran the old default still carries a workspace
+          # test-temp, and a checkout with clean:true dies on it. Reap the holders
+          # first -- rm cannot unlink a live mountpoint even as root (EBUSY), and a
+          # RESTARTING leaked container re-creates the path as root seconds after
+          # any clean. Match on mount SOURCE, not a label: the holders are untracked
+          # by construction, because a killed run labels nothing.
+          tt="$GITHUB_WORKSPACE/test-temp"
+          [ -d "$tt" ] || exit 0
+          stuck=""
+          for c in $(docker ps -aq 2>/dev/null || true); do
+            if docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null | grep -q "^$tt/"; then
+              stuck="$stuck $c"
+            fi
+          done
+          if [ -n "$stuck" ]; then
+            echo "reaping containers holding mounts under $tt:$stuck"
+            docker rm -f $stuck || true
+          fi
+          # The DIRECTORY, not just its contents: an empty but root-owned base
+          # still EACCESes a later mkdtemp. Mounting the PARENT is what lets a root
+          # container unlink the leaf.
+          docker run --rm --user 0:0 -v "$GITHUB_WORKSPACE":/w alpine \
+            sh -c 'rm -rf /w/test-temp' || rm -rf "$tt" || true
+          # Fail HERE if it survived. The checkout fails on it either way, but
+          # reports only an EACCES rmdir with no clue what was holding the path.
+          if [ -e "$tt" ]; then
+            echo "::error::$tt survived the pre-checkout clean"
+            ls -lan "$tt" || true
+            exit 1
+          fi
+
+      - uses: actions/checkout@v5
+        with:
+          clean: true
+
+      - name: Decide whether the guides gate this publish
+        id: plan
+        run: |
+          set -euo pipefail
+          skip() { echo "guides=skip" >> "$GITHUB_OUTPUT"; echo "reason=$1" >> "$GITHUB_OUTPUT"; echo "guides skipped: $1"; }
+          if [ "${{ needs.label.outputs.publish }}" != "true" ]; then
+            skip "build-only: nothing is published"
+          elif [ ! -f scripts/doc-guide/regen-manual.sh ]; then
+            skip "this product has no guides (scripts/doc-guide/regen-manual.sh)"
+          else
+            decision="$(nix develop .#build --command bash -c '
+              set -euo pipefail
+              bun install --frozen-lockfile >/dev/null
+              cli="$(bun -e "console.log(Bun.resolveSync(\"@norskvideo/ctl-dev-kit/publish/product-channel\", process.cwd()))")"
+              bun "$cli" guide-gate
+            ')"
+            if [ "$decision" = "run" ]; then
+              echo "guides=run" >> "$GITHUB_OUTPUT"
+            else
+              skip "${decision#skip$'\t'}"
+            fi
+          fi
+
+      - name: Write the Norsk license (from the org secret)
+        if: ${{ steps.plan.outputs.guides == 'run' }}
+        env:
+          NORSK_LICENSE_V2: ${{ secrets.NORSK_LICENSE_V2 }}
+        run: printf '%s' "$NORSK_LICENSE_V2" > "$RUNNER_TEMP/norsk-license.json"
+
+      - name: Download the released norsk-ctl binary (latest channel)
+        if: ${{ steps.plan.outputs.guides == 'run' }}
+        run: |
+          set -euo pipefail
+          S3="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
+          ver="$(curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/latest")"
+          echo "norsk-ctl latest channel -> $ver"
+          curl -fsSL --retry 3 --retry-all-errors --retry-delay 2 "$S3/$ver/norsk-ctl-$ver-linux-x64" -o "$RUNNER_TEMP/norsk-ctl"
+          chmod +x "$RUNNER_TEMP/norsk-ctl"
+          "$RUNNER_TEMP/norsk-ctl" --version || true
+
+      # Cold-runner first pulls overrun the harness's per-test launch timeouts;
+      # pre-pull the universal media + studio images (every product pins them in
+      # manifest.seed.json) so compose/run hit local images. A product needing
+      # more (e.g. a WHIP driver) pulls them in scripts/doc-guide/prepull-extra.sh.
+      - name: Pre-pull the media + studio images
+        if: ${{ steps.plan.outputs.guides == 'run' }}
+        run: |
+          set -euo pipefail
+          for img in "$(jq -r '.latest.media' manifest.seed.json)" "$(jq -r '.latest.studio' manifest.seed.json)"; do
+            echo "pre-pulling $img"
+            docker pull "$img"
+          done
+          if [ -x scripts/doc-guide/prepull-extra.sh ]; then
+            echo "running scripts/doc-guide/prepull-extra.sh"
+            ./scripts/doc-guide/prepull-extra.sh
+          fi
+
+      # Rebuild every workspace the manual depends on (a guide's engine tier packs
+      # the freshly-built dashboard + frontend dist into the launched template),
+      # then run the product's doc-guide tiers and assemble the manual.
+      # regen-manual.sh owns the slug list and which tiers run; with-display.sh
+      # wraps the whole run in an X display for headless chromium (the engine tier
+      # drives a raw chromium that needs one).
+      - name: Regenerate the illustrated manual (all tiers)
+        if: ${{ steps.plan.outputs.guides == 'run' }}
+        env:
+          NORSK_CTL_BINARY: ${{ runner.temp }}/norsk-ctl
+          NORSK_LICENSE_FILE: ${{ runner.temp }}/norsk-license.json
+          # This runner launches Studio as a HOST sibling (DooD), so the harness
+          # reaches host-published ports via the host-gateway alias, not
+          # localhost — same as the integration suite.
+          NORSK_TEST_HOST: host.docker.internal
+          # Reach launched instances over norsk-net by service DNS (as the
+          # integration tier already does) AND, on a ctl that supports it, launch
+          # them binding no host ports — so concurrent doc-guide instances can't
+          # collide on the product's deterministic host-port bands.
+          NORSK_TEST_NET: direct
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            # Belt-and-braces now that the checkout cleans: a persisted node_modules
+            # workspace dep whose version moved leaves stale copies that
+            # --frozen-lockfile does not reliably relink, so a new export is "not
+            # found". Nuke EVERY node_modules — including nested per-workspace ones
+            # — for a deterministic install. A nightly can afford it.
+            find . -name node_modules -type d -prune -exec rm -rf {} + 2>/dev/null || true
+            bun install --frozen-lockfile
+            bun run build:no-lint
+            bash scripts/with-display.sh scripts/doc-guide/regen-manual.sh
+          '
+
+      - name: Reap the containers this job launched
+        # Whatever the tests did. A teardown cut short by a test timeout leaves
+        # its instance running on the shared Docker daemon (see JOB_REAP_STEP in
+        # conventions/workflow-shell.ts); everything this job launched mounts its
+        # own test-temp, so that is what goes.
+        if: always()
+        run: |
+          base="${NORSK_CTL_TEST_TMP:-}"
+          tt="$GITHUB_WORKSPACE/test-temp"
+          s=""
+          for c in $(docker ps -aq); do
+            src="$(docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null)" || continue
+            if { [ -n "$base" ] && grep -q "^$base/" <<<"$src"; } || grep -q "^$tt/" <<<"$src"; then s="$s $c"; fi
+          done
+          if [ -n "$s" ]; then
+            echo "::warning::removing containers this job left running:$s"
+            docker rm -f $s
+          fi
+
   # Combine the per-arch images into a multi-arch manifest and write the two
   # published tags. Skipped for a build-only product (empty PUBLISH_IMAGE) and on
   # a dry run.
   publish:
-    needs: [label, build]
+    needs: [label, build, gate-checks, gate-guides]
     if: ${{ needs.label.outputs.publish == 'true' && !inputs.dry_run }}
     runs-on: x64
     steps:
@@ -375,12 +569,148 @@ jobs:
             docker rm -f $s
           fi
 
+  # Record the published image in this product's channels object
+  # (s3://norsk.video/products/<product>/channels.json), which ctl reads to
+  # register the product. Only reached after the gate passed, so a row is a
+  # statement that the image passed it. The role is per product and can write
+  # only its own prefix (norsk-ctl docs/ci/aws-oidc/apply-products.sh); until it
+  # exists this warns and records nothing, rather than failing a publish.
+  record:
+    needs: [label, gate-guides, publish]
+    if: ${{ needs.publish.result == 'success' }}
+    runs-on: x64
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      # Runs BEFORE checkout, and does two things: points the harness's temp base
+      # out of the workspace for every later step in this job, and clears whatever
+      # the old repo-local default left behind on this runner. The body carries the
+      # why. It fails the job only when legacy litter survives -- which would take
+      # the checkout down a step later anyway, but report nothing useful.
+      - name: Route test-temp out of the workspace (pre-checkout)
+        run: |
+          set -uo pipefail
+          # These runners are docker-OUTSIDE-of-docker, so a bind-mount source the
+          # HOST daemon has not seen before is created by dockerd, as ROOT, on the
+          # host -- even when the launch passes --container-user (reproduced
+          # 2026-09-04). The harness's default base is repo-local for an OrbStack
+          # inotify constraint that binds macOS dev and nothing here, so every run
+          # seeded the CHECKOUT with root-owned dirs a non-root `git clean -ffdx`
+          # cannot remove. That took commentary's checks AND integration red on
+          # 2026-09-03. Use the sanctioned override, per-run and outside the
+          # checkout -- as 8ff17a8d did in June for one debug workflow, and stopped.
+          base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          mkdir -p "$base"
+          echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
+          # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
+          # EACCESes. They cannot wedge a checkout, but they do fill the disk.
+          for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
+            docker run --rm --user 0:0 -v "$RUNNER_TEMP":/t alpine sh -c 'rm -rf -- "/t/$1"' sh "$old" >/dev/null 2>&1 || true
+          done
+          # LEGACY: a runner that ran the old default still carries a workspace
+          # test-temp, and a checkout with clean:true dies on it. Reap the holders
+          # first -- rm cannot unlink a live mountpoint even as root (EBUSY), and a
+          # RESTARTING leaked container re-creates the path as root seconds after
+          # any clean. Match on mount SOURCE, not a label: the holders are untracked
+          # by construction, because a killed run labels nothing.
+          tt="$GITHUB_WORKSPACE/test-temp"
+          [ -d "$tt" ] || exit 0
+          stuck=""
+          for c in $(docker ps -aq 2>/dev/null || true); do
+            if docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null | grep -q "^$tt/"; then
+              stuck="$stuck $c"
+            fi
+          done
+          if [ -n "$stuck" ]; then
+            echo "reaping containers holding mounts under $tt:$stuck"
+            docker rm -f $stuck || true
+          fi
+          # The DIRECTORY, not just its contents: an empty but root-owned base
+          # still EACCESes a later mkdtemp. Mounting the PARENT is what lets a root
+          # container unlink the leaf.
+          docker run --rm --user 0:0 -v "$GITHUB_WORKSPACE":/w alpine \
+            sh -c 'rm -rf /w/test-temp' || rm -rf "$tt" || true
+          # Fail HERE if it survived. The checkout fails on it either way, but
+          # reports only an EACCES rmdir with no clue what was holding the path.
+          if [ -e "$tt" ]; then
+            echo "::error::$tt survived the pre-checkout clean"
+            ls -lan "$tt" || true
+            exit 1
+          fi
+
+      - uses: actions/checkout@v5
+        with:
+          clean: true
+
+      - name: Warn that no channels role is configured
+        if: ${{ vars.AWS_PRODUCT_ROLE_ARN == '' }}
+        run: echo "::warning::AWS_PRODUCT_ROLE_ARN is not set, so this publish was not recorded for ctl (norsk-ctl docs/ci/aws-oidc/apply-products.sh)"
+
+      - name: Configure AWS credentials (this product's channels role)
+        if: ${{ vars.AWS_PRODUCT_ROLE_ARN != '' }}
+        uses: aws-actions/configure-aws-credentials@v6
+        with:
+          role-to-assume: ${{ vars.AWS_PRODUCT_ROLE_ARN }}
+          role-session-name: product-channels-${{ github.run_id }}
+          aws-region: eu-west-1
+
+      - name: Record the image in the product's channels object
+        if: ${{ vars.AWS_PRODUCT_ROLE_ARN != '' }}
+        env:
+          LABEL: ${{ needs.label.outputs.label }}
+          CHANNEL: ${{ needs.label.outputs.channel }}
+          GUIDES: ${{ needs.gate-guides.outputs.guides }}
+          SKIP_REASON: ${{ needs.gate-guides.outputs.reason }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          image="${PUBLISH_IMAGE}:${LABEL}"
+          runtime="$(docker buildx imagetools inspect "$image" --format '{{ json (index .Image "linux/amd64") }}' \
+            | jq -r '.config.Labels["norsk-ctl.runtime-images"] // ""')"
+          aws() { nix shell --inputs-from . nixpkgs#awscli2 --command aws "$@"; }
+          nix develop .#build --command bash -c 'bun install --frozen-lockfile >/dev/null'
+          cli="$(nix develop .#build --command bun -e 'console.log(Bun.resolveSync("@norskvideo/ctl-dev-kit/publish/product-channel", process.cwd()))')"
+          product="$(nix develop .#build --command bun "$cli" product --template licenseTemplate.json --image "$PUBLISH_IMAGE")"
+          uri="s3://norsk.video/products/${product}/channels.json"
+          current="$RUNNER_TEMP/channels.current.json"
+          : > "$current"
+          if aws s3api head-object --bucket norsk.video --key "products/${product}/channels.json" >/dev/null 2>&1; then
+            aws s3 cp "$uri" "$current"
+          fi
+          skipped=()
+          if [ "$GUIDES" = "skip" ]; then skipped=(--skipped "$SKIP_REASON"); fi
+          nix develop .#build --command bun "$cli" row --current "$current" \
+            --product "$product" --image-ref "$PUBLISH_IMAGE" --channel "$CHANNEL" \
+            --image "$image" --sha "$GITHUB_SHA" --published-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            --runtime-images "$runtime" --run "$RUN_URL" "${skipped[@]}" > "$RUNNER_TEMP/channels.json"
+          aws s3 cp "$RUNNER_TEMP/channels.json" "$uri" --content-type application/json --cache-control "max-age=60"
+          echo "recorded $image as ${product}'s ${CHANNEL} -> $uri"
+      - name: Reap the containers this job launched
+        # Whatever the tests did. A teardown cut short by a test timeout leaves
+        # its instance running on the shared Docker daemon (see JOB_REAP_STEP in
+        # conventions/workflow-shell.ts); everything this job launched mounts its
+        # own test-temp, so that is what goes.
+        if: always()
+        run: |
+          base="${NORSK_CTL_TEST_TMP:-}"
+          tt="$GITHUB_WORKSPACE/test-temp"
+          s=""
+          for c in $(docker ps -aq); do
+            src="$(docker inspect -f '{{range .Mounts}}{{println .Source}}{{end}}' "$c" 2>/dev/null)" || continue
+            if { [ -n "$base" ] && grep -q "^$base/" <<<"$src"; } || grep -q "^$tt/" <<<"$src"; then s="$s $c"; fi
+          done
+          if [ -n "$s" ]; then
+            echo "::warning::removing containers this job left running:$s"
+            docker rm -f $s
+          fi
+
   # Report this pipeline's result to the aggregated product CI dashboard
   # (id3as/ci-workflows) instead of posting its own pony -- the dashboard renders
   # the pony/emoji from the dispatched result. always() so a red or manual run
   # still reports.
   notify:
-    needs: [build, publish]
+    needs: [build, gate-checks, gate-guides, publish, record]
     if: ${{ !cancelled() }}
     runs-on: x64
     steps:
@@ -456,6 +786,7 @@ jobs:
           product: __PRODUCT__
           pipeline: build-image
           status: ${{ steps.meta.outputs.state }}
+          detail: "${{ needs.gate-guides.outputs.guides == 'skip' && format('guides not gating: {0}', needs.gate-guides.outputs.reason) || '' }}"
       - name: Reap the containers this job launched
         # Whatever the tests did. A teardown cut short by a test timeout leaves
         # its instance running on the shared Docker daemon (see JOB_REAP_STEP in

package/conventions/checks.yml

@@ -22,6 +22,13 @@ on:
   push:
     branches: [main]
   pull_request:
+  # build-image.yml calls this as half of the publish gate, with report off so
+  # the board gets one `checks` cell per push, not two.
+  workflow_call:
+    inputs:
+      report:
+        type: boolean
+        default: true
 
 permissions:
   contents: read
@@ -274,7 +281,7 @@ jobs:
   # superseded run.
   notify:
     needs: [drift, quality]
-    if: ${{ !cancelled() && github.event_name == 'push' }}
+    if: ${{ !cancelled() && github.event_name == 'push' && inputs.report != false }}
     runs-on: x64
     steps:
       # Runs BEFORE checkout, and does two things: points the harness's temp base

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.37",
+  "version": "0.2.38",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",
@@ -18,6 +18,7 @@
     "./licence/check-entitlement": "./licence/check-entitlement.ts",
     "./licence/check-product-name": "./licence/check-product-name.ts",
     "./licence/check-template": "./licence/check-template.ts",
+    "./publish/product-channel": "./publish/product-channel.ts",
     "./package.json": "./package.json",
     "./testing/byte-snapshot": "./testing/byte-snapshot.ts",
     "./testing/invariants": "./testing/invariants.ts",

package/publish/product-channel.ts

@@ -0,0 +1,138 @@
+#!/usr/bin/env bun
+/**
+ * A product's half of the channels object ctl reads to register it
+ * (`@norskvideo/ctl-product-template-schema/product-channels`). Used by
+ * conventions/build-image.yml, which every product repo copies verbatim:
+ *
+ *   guide-gate [<opt-out file>]      -> `run`, or `skip<TAB><reason>`
+ *   product --template <file> --image <ref>
+ *                                    -> the licence product the image is
+ *   row --current <file> --product <p> --image-ref <repo> --channel <ch>
+ *       --image <ref> --sha <sha> --published-at <iso> [--runtime-images <a,b>]
+ *       [--skipped <reason>] [--run <url>]
+ *                                    -> the merged channels object
+ *
+ * The opt-out (`.github/publish-gate.json`) exists for a product whose guides
+ * are not reliable yet: it skips only the guide half of the gate, must give a
+ * reason, and the reason travels into the published row, so nobody reads
+ * "passed" off an image whose guides never ran.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import {
+  type ProductChannelRow,
+  ProductChannelSchema,
+  parseProductChannels,
+  withChannelRow,
+} from "@norskvideo/ctl-product-template-schema/product-channels";
+import { builtImageName } from "../licence/check-template.ts";
+
+export type GuideGate = { run: true } | { run: false; reason: string };
+
+/** Whether the guides gate this product's publish, from its opt-out file. */
+export function guideGate(optOutJson: string | undefined): GuideGate {
+  if (optOutJson === undefined) return { run: true };
+  const parsed = JSON.parse(optOutJson) as { guides?: unknown };
+  const guides = parsed.guides;
+  if (typeof guides !== "object" || guides === null) {
+    throw new Error('publish-gate.json: "guides" must be an object, e.g. {"skip": true, "reason": "..."}');
+  }
+  const { skip, reason } = guides as { skip?: unknown; reason?: unknown };
+  if (skip !== true) return { run: true };
+  if (typeof reason !== "string" || reason.trim() === "") {
+    throw new Error("publish-gate.json: skipping the guides needs a reason");
+  }
+  return { run: false, reason: reason.trim() };
+}
+
+/** The licence product whose imageRef is the published image's repo. */
+export function productForImage(templateJson: string, image: string): string {
+  const repo = builtImageName({ publishImage: image, buildDefault: "" });
+  const entries = (JSON.parse(templateJson) as { products?: { product?: string; imageRef?: string }[] }).products ?? [];
+  const match = entries.find((e) => e.imageRef === repo && typeof e.product === "string");
+  if (!match?.product) throw new Error(`no licence product in licenseTemplate.json names ${repo}`);
+  return match.product;
+}
+
+export function gateRow(opts: {
+  image: string;
+  sha: string;
+  publishedAt: string;
+  runtimeImages: string;
+  guides: GuideGate;
+  run?: string;
+}): ProductChannelRow {
+  return {
+    image: opts.image,
+    sha: opts.sha,
+    publishedAt: opts.publishedAt,
+    runtimeImages: opts.runtimeImages
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+    gate: {
+      checks: "passed",
+      guides: opts.guides.run ? "passed" : { skipped: opts.guides.reason },
+      ...(opts.run ? { run: opts.run } : {}),
+    },
+  };
+}
+
+function readIfPresent(path: string | undefined): string | undefined {
+  if (!path || !existsSync(path)) return undefined;
+  const text = readFileSync(path, "utf8");
+  return text.trim() === "" ? undefined : text;
+}
+
+if (import.meta.main) {
+  const argv = process.argv.slice(2);
+  const [cmd, positional] = argv;
+  const flag = (name: string): string | undefined => {
+    const i = argv.indexOf(`--${name}`);
+    return i === -1 ? undefined : argv[i + 1];
+  };
+  const need = (name: string): string => {
+    const v = flag(name);
+    if (!v) {
+      console.error(`product-channel ${cmd}: --${name} is required`);
+      process.exit(2);
+    }
+    return v;
+  };
+
+  if (cmd === "guide-gate") {
+    const gate = guideGate(readIfPresent(positional ?? ".github/publish-gate.json"));
+    console.log(gate.run ? "run" : `skip\t${gate.reason}`);
+  } else if (cmd === "product") {
+    console.log(productForImage(readFileSync(need("template"), "utf8"), need("image")));
+  } else if (cmd === "row") {
+    const currentText = readIfPresent(flag("current"));
+    let current = null;
+    if (currentText !== undefined) {
+      const parsed = parseProductChannels(JSON.parse(currentText));
+      if (!parsed.ok) {
+        console.error(`product-channel row: the current object does not parse:\n${parsed.error}`);
+        process.exit(1);
+      }
+      current = parsed.value;
+    }
+    const skipped = flag("skipped");
+    const merged = withChannelRow(current, {
+      product: need("product"),
+      imageRef: need("image-ref"),
+      channel: ProductChannelSchema.parse(need("channel")),
+      updated: need("published-at"),
+      row: gateRow({
+        image: need("image"),
+        sha: need("sha"),
+        publishedAt: need("published-at"),
+        runtimeImages: flag("runtime-images") ?? "",
+        guides: skipped ? { run: false, reason: skipped } : { run: true },
+        run: flag("run"),
+      }),
+    });
+    process.stdout.write(`${JSON.stringify(merged, null, 2)}\n`);
+  } else {
+    console.error("usage: product-channel.ts guide-gate [file] | product --template <f> --image <ref> | row ...");
+    process.exit(2);
+  }
+}