publish-content.ts

import { readFileSync, readdirSync, statSync, existsSync, appendFileSync } from 'node:fs';
import { spawnSync as _spawnSync } from 'node:child_process';
import { join } from 'node:path';
import { createHash } from 'node:crypto';
import { gzipSync } from 'node:zlib';
import { userInfo, hostname } from 'node:os';
import { parse as parseYaml } from 'yaml';
import { parseChannel, type Channel } from './fetch-tutorials.js';
import { beginSession, appendBatch, commitSession, abortSession, fetchRemoteHashes, fetchRemoteSourceHashes, renderConceptsPhase, renderTopicsPhase, renderChannelsPhase } from './lib/publish-client.js';
import { computePipelineToken } from './lib/pipeline-token.js';
import { withRetry, formatErrorChain } from './lib/publish-retry.js';
import { chunk, runConcurrent } from './lib/publish-batcher.js';
import { collectCodeCheckSpecs, publishCodeCheckSpecs } from './lib/publish-codecheck.js';
import { collectAssertSpecs, publishAssertSpecs } from './lib/publish-asserts.js';
import { publishValidateAnswerSpecs } from './lib/publish-validate-answer.js';
import { publishChallengeAnswers } from './lib/publish-challenge-answers.js';
import { publishContributors } from './publish/publish-contributors.js';
import { publishValidationRules } from './publish/publish-validation-rules.js';
import { computeOrphans, enforceCap, formatStepSummary } from './lib/purge-orphans.js';
import { discoverPageFiles, discoverAuthorPages, discoverAdvocatePages } from '../srv/lib/page-key-map.js';

export type { Channel };

/**
 * Coerce arbitrary values to a trimmed non-empty string, or null. Used by
 * frontmatter extractors that may receive missing keys, numbers, or empties.
 */
const trim = (v: unknown): string | null =>
  typeof v === 'string' && v.trim().length > 0 ? v.trim() : null;

export interface PublishConfig {
  baseUrl: string;
  apiKey: string | undefined;
  sourceDir: string;
  force: boolean;
}

export function resolvePublishConfig({ channel }: { channel: Channel }): PublishConfig {
  if (channel === 'qa') {
    return {
      baseUrl: process.env.CAP_QA_BASE_URL ?? 'http://localhost:4005',
      apiKey: process.env.CONTENT_API_KEY_QA,
      sourceDir: 'hugo/public-qa',
      // Delta by default (mirrors prod), so a commit-triggered QA rebuild that
      // sets PUBLISH_SLUG publishes only the changed slug — a sub-second commit
      // instead of a ~35s full-catalog force write that intermittently 502/503s
      // the single srv-qa instance. `force-publish=true` (workflow input → --force)
      // still does a full re-seed. Safe now that QA has Option B fully active
      // (mutable ContentCurrent, O(changed) publish, server carries unchanged slugs).
      force: process.argv.includes('--force'),
    };
  }
  return {
    baseUrl: process.env.CAP_BASE_URL ?? 'http://localhost:4004',
    apiKey: process.env.CONTENT_API_KEY,
    sourceDir: 'hugo/public',
    force: process.argv.includes('--force'),
  };
}

// --- Build validation ---

const DEV_ARTIFACT_PATTERNS = [
  { pattern: /data-cap-base="http:\/\/localhost/, label: 'data-cap-base pointing to localhost' },
  { pattern: /livereload\.js/, label: 'Hugo livereload script injection' },
  { pattern: /<script>document\.write.*livereload/s, label: 'Hugo dev server livereload' },
];

export function validateProductionBuild(tutorials: Map<string, string>, sampleSize = 5): string[] {
  const slugs = [...tutorials.keys()];
  const sample = slugs.slice(0, Math.min(sampleSize, slugs.length));
  const violations: string[] = [];

  for (const slug of sample) {
    const content = readFileSync(tutorials.get(slug)!, 'utf-8');
    for (const { pattern, label } of DEV_ARTIFACT_PATTERNS) {
      if (pattern.test(content)) {
        violations.push(`${slug}: ${label}`);
      }
    }
  }
  return violations;
}

// --- Pure functions (exported for testing) ---

export function discoverTutorials(hugoDir: string): Map<string, string> {
  const tutorialsDir = join(hugoDir, 'tutorials');
  const result = new Map<string, string>();

  let entries: string[];
  try {
    entries = readdirSync(tutorialsDir);
  } catch {
    return result;
  }

  for (const entry of entries) {
    const indexPath = join(tutorialsDir, entry, 'index.html');
    try {
      const stat = statSync(indexPath);
      if (stat.isFile()) {
        // Normalize the slug KEY to lowercase (issue #2714): some source folders
        // ship mixed-case (e.g. "...-RAP-App"), but Hugo serves lowercase URLs and
        // the server stores/serves lowercase slugs. Lowercasing here — the single
        // upstream chokepoint feeding every downstream payload — prevents a
        // mixed-case Tutorials.slug row from ever being minted again. The PATH
        // keeps the real on-disk (mixed-case) directory so the file read works.
        result.set(entry.toLowerCase(), indexPath);
      }
    } catch {
      // not a tutorial directory
    }
  }

  return result;
}

// Concept slug predicate — used to skip Tutorials-only metadata extraction
// for concept landing pages (metadata, bodyText, branchSpecs, source markdown
// are all keyed off Tutorials.slug; concept-* keys would orphan in those
// tables).
export function isConceptSlug(slug: string): boolean {
  return typeof slug === 'string' && slug.startsWith('concept-');
}

// #1659 Phase C — author page predicate. Author pages (`author-<login>`) are
// pre-rendered Hugo HTML like concept/page BLOBs; they must be excluded from
// Tutorials-only metadata/bodyText/branchSpec/source extraction (same reason as
// concept slugs) so they never orphan rows in those tutorial-keyed tables.
export function isAuthorSlug(slug: string): boolean {
  return typeof slug === 'string' && slug.startsWith('author-');
}

// #1659 Phase C.2a — per-advocate detail page predicate (same rationale as
// concept/author slugs: exclude from Tutorials-only extraction).
export function isAdvocateSlug(slug: string): boolean {
  return typeof slug === 'string' && slug.startsWith('advocate-');
}

// A slug points at a runtime-SSR'd catalog page (groups/missions) since PR
// #115 (#91). Such slugs must NEVER reach the publish endpoint; the server
// rejects them too, but we strip locally as well so payload size and CI
// logs stay clean. See issue #114.
export function isCatalogSlug(slug: string): boolean {
  return slug.startsWith('group-') || slug.startsWith('mission-');
}

// Strips catalog slugs from the discovery map in place, returning the
// removed slugs in deterministic (sorted) order so callers can log them.
export function stripCatalogSlugs(tutorials: Map<string, string>): string[] {
  const dropped: string[] = [];
  for (const slug of tutorials.keys()) {
    if (isCatalogSlug(slug)) {
      dropped.push(slug);
      tutorials.delete(slug);
    }
  }
  return dropped.sort();
}

export function computeLocalHashes(tutorials: Map<string, string>): Map<string, string> {
  const hashes = new Map<string, string>();
  for (const [slug, filePath] of tutorials) {
    const content = readFileSync(filePath);
    const hash = createHash('sha256').update(content).digest('hex');
    hashes.set(slug, hash);
  }
  return hashes;
}


export function computeDiff(
  local: Map<string, string>,
  remote: Record<string, string>
): string[] {
  const changed: string[] = [];
  for (const [slug, localHash] of local) {
    if (remote[slug] !== localHash) {
      changed.push(slug);
    }
  }
  return changed;
}

export function buildPayload(
  slugs: string[],
  tutorials: Map<string, string>
): Record<string, string> {
  const payload: Record<string, string> = {};
  for (const slug of slugs) {
    // Tripwire (issue #2714): slugs are lowercased at discoverTutorials, the
    // upstream chokepoint. If a mixed-case slug reaches here, some code path
    // reintroduced case — fail loud rather than silently publish a mixed-case
    // key that mints a non-canonical Tutorials.slug row. Belt-and-suspenders
    // behind the discovery-time normalization.
    if (slug !== slug.toLowerCase()) {
      throw new Error(
        `buildPayload: non-canonical (mixed-case) slug "${slug}" — slugs must be lowercase before publish (issue #2714)`
      );
    }
    const filePath = tutorials.get(slug);
    if (!filePath) continue;
    const content = readFileSync(filePath);
    const compressed = gzipSync(content);
    payload[slug] = compressed.toString('base64');
  }
  return payload;
}

/**
 * Build the source-markdown side of the publish payload (PR #591). For each
 * slug, reads `<cacheDir>/<slug>.md` (the raw upstream tutorial markdown that
 * `fetch-tutorials.ts` populated), gzips it, base64-encodes, and stores under
 * the same slug key. Slugs whose source file is missing are silently skipped
 * — the server stores null sourceContent/sourceHash for those rows, and
 * `/content/source-hashes` simply omits them. This is the right behavior for
 * special slugs (`__shell__`, `__nav__`, `__404__`) that have no upstream
 * markdown.
 *
 * Returns the gzipped-base64 map AND a parallel map of pre-gzip SHA-256
 * hashes; the server independently re-hashes after gunzip and rejects on
 * mismatch (defense against in-flight corruption), but exposing the hash
 * locally lets the CLI auto-verify against `/content/source-hashes`
 * without round-tripping through gzip.
 */
/**
 * #672 short-circuit support: compute pre-gzip SHA-256 of each slug's source
 * markdown WITHOUT building the gzip payload. Used in delta mode to drop slugs
 * whose source bytes already match the server, before paying for buildPayload's
 * Hugo-output re-read + gzip.
 *
 * Slugs whose source file is missing (special slugs: __shell__, __nav__, __404__)
 * are silently skipped.
 */
export function computeLocalSourceHashes(
  slugs: string[],
  cacheDir: string
): Map<string, string> {
  const sourceHashes = new Map<string, string>();
  for (const slug of slugs) {
    const mdPath = join(cacheDir, `${slug}.md`);
    if (!existsSync(mdPath)) continue;
    const content = readFileSync(mdPath);
    const hash = createHash('sha256').update(content).digest('hex');
    sourceHashes.set(slug, hash);
  }
  return sourceHashes;
}

export function buildSourcePayload(
  slugs: string[],
  cacheDir: string
): { sources: Record<string, string>; sourceHashes: Map<string, string> } {
  const sources: Record<string, string> = {};
  const sourceHashes = computeLocalSourceHashes(slugs, cacheDir);
  for (const slug of slugs) {
    const mdPath = join(cacheDir, `${slug}.md`);
    if (!existsSync(mdPath)) continue;
    const content = readFileSync(mdPath);
    const compressed = gzipSync(content);
    sources[slug] = compressed.toString('base64');
  }
  return { sources, sourceHashes };
}

/**
 * #2245: Build the per-slug git commit SHA map for the append payload.
 * For each slug, reads `<cacheDir>/<slug-lowercase>.commit-sha` (written by
 * fetch-tutorials.ts alongside the main .md cache file). Slugs with no sidecar
 * are silently skipped — the server stores null sourceCommit for those rows.
 *
 * The key in the returned map is the ORIGINAL-CASE slug (matching how `sources`
 * and `files` are keyed), so the server's `sourceCommits[slug]` lookup lands on
 * the correct entry. The file lookup uses `slug.toLowerCase()` to match the
 * lowercase-canonical filename written by fetch-tutorials.
 */
export function buildSourceCommitsPayload(
  slugs: string[],
  cacheDir: string,
): Record<string, string> {
  const result: Record<string, string> = {};
  for (const slug of slugs) {
    const shaPath = join(cacheDir, `${slug.toLowerCase()}.commit-sha`);
    if (!existsSync(shaPath)) continue;
    const sha = readFileSync(shaPath, 'utf-8').trim();
    if (sha) result[slug] = sha;
  }
  return result;
}

/**
 * Parallel to buildSourceCommitsPayload: reads `<slug>.source-repo` sidecars
 * (owner/name of the GitHub repo the source came from) written by
 * fetch-tutorials. Keyed by ORIGINAL-CASE slug so the server's
 * sourceRepos[slug] lookup lands on the correct entry; the file lookup uses
 * slug.toLowerCase() to match the lowercase-canonical sidecar filename.
 * Feeds the public-namespace -Contribution publish guard.
 */
export function buildSourceReposPayload(
  slugs: string[],
  cacheDir: string,
): Record<string, string> {
  const result: Record<string, string> = {};
  for (const slug of slugs) {
    const repoPath = join(cacheDir, `${slug.toLowerCase()}.source-repo`);
    if (!existsSync(repoPath)) continue;
    const repo = readFileSync(repoPath, 'utf-8').trim();
    if (repo) result[slug] = repo;
  }
  return result;
}

const TUTORIAL_MAIN_RE = /<main\b[^>]*class\s*=\s*["']?[^"'>]*\btutorial-main\b[^"'>]*["']?[^>]*>([\s\S]*?)<\/main>/i;
const BODY_RE = /<body\b[^>]*>([\s\S]*?)<\/body>/i;
const STRIP_BLOCKS_RE = /<(script|style|nav|footer|aside)\b[^>]*>[\s\S]*?<\/\1>/gi;
const TAG_RE = /<[^>]+>/g;
const WHITESPACE_RE = /\s+/g;

const ENTITY_MAP: Record<string, string> = {
  '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"',
  '&#39;': "'", '&apos;': "'", '&nbsp;': ' ',
};

export function extractBodyText(html: string): string {
  const mainMatch = html.match(TUTORIAL_MAIN_RE);
  let zone = mainMatch ? mainMatch[1] : (html.match(BODY_RE)?.[1] ?? html);

  zone = zone.replace(STRIP_BLOCKS_RE, ' ');
  zone = zone.replace(TAG_RE, ' ');
  zone = zone.replace(/&[a-z#0-9]+;/gi, m => ENTITY_MAP[m.toLowerCase()] ?? ' ');
  zone = zone.replace(WHITESPACE_RE, ' ').trim();

  return zone;
}

export function extractAllBodyTexts(
  tutorials: Map<string, string>,
  slugs: string[]
): Record<string, string> {
  const result: Record<string, string> = {};
  for (const slug of slugs) {
    const filePath = tutorials.get(slug);
    if (!filePath) continue;
    const html = readFileSync(filePath, 'utf-8');
    const text = extractBodyText(html);
    if (text) result[slug] = text;
  }
  return result;
}

// --- Branch spec extraction (issue #172 PR 3) ---
// Reads branchPoints / skipPoints out of each tutorial's parsed Hugo
// frontmatter so they ride along in the publish payload and land in the
// BranchSpecs sidecar entity. Tutorials with no branches/skips are skipped
// entirely (no row written) — the decide handler treats absence as "linear".

export interface BranchSpec {
  branchPoints: Array<{
    id: string;
    parentStepNumber: number;
    groupKey: string;
    branches: Array<{
      key: string;
      label: string;
      condition: string | null;
      embeddingHint: string | null;
    }>;
  }>;
  skipPoints: Array<{
    stepNumber: number;
    skipIf: string;
    skipLabel?: string;
    skipReason?: string;
  }>;
}

export function extractAllBranchSpecs(
  contentDir: string,
  slugs: string[]
): Record<string, BranchSpec> {
  const out: Record<string, BranchSpec> = {};
  for (const slug of slugs) {
    const fmPath = join(contentDir, `${slug}.md`);
    if (!existsSync(fmPath)) continue;
    const raw = readFileSync(fmPath, 'utf-8');
    const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
    if (!fmMatch) continue;
    let fm: any;
    try { fm = parseYaml(fmMatch[1]); } catch { continue; }

    const branchPoints: BranchSpec['branchPoints'] = [];
    const skipPoints: BranchSpec['skipPoints'] = [];

    for (const step of (fm.steps ?? [])) {
      if (step.branchPointId && Array.isArray(step.branches)) {
        branchPoints.push({
          id: step.branchPointId,
          parentStepNumber: step.number,
          groupKey: step.branchGroup,
          branches: step.branches.map((b: any) => ({
            key: b.key,
            label: b.label,
            condition: b.condition ?? null,
            embeddingHint: b.embeddingHint ?? null,
          })),
        });
      }
      if (step.skipIf) {
        skipPoints.push({
          stepNumber: step.number,
          skipIf: step.skipIf,
          skipLabel: step.skipLabel,
          skipReason: step.skipReason,
        });
      }
    }

    if (branchPoints.length || skipPoints.length) {
      out[slug] = { branchPoints, skipPoints };
    }
  }
  return out;
}

// --- Metadata extraction ---

export interface StepMeta {
  number: number;
  title: string;
}

export interface TutorialMeta {
  slug: string;
  title: string;
  description: string;
  time: number | null;
  level: string | null;
  primaryTag: string | null;
  stepCount: number;
  steps: StepMeta[];
  lastUpdated: string | null;
  primaryContributorEmail: string | null;
  primaryContributorLogin: string | null;
  frontmatterGithubLogin: string | null;
  frontmatterAuthorName: string | null;
}

export function extractMetadata(
  contentDir: string,
  slugs: string[]
): Record<string, TutorialMeta> {
  const result: Record<string, TutorialMeta> = {};

  for (const slug of slugs) {
    const mdPath = join(contentDir, `${slug}.md`);
    if (!existsSync(mdPath)) continue;

    const raw = readFileSync(mdPath, 'utf-8');
    const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
    if (!fmMatch) continue;

    let fm: any;
    try {
      fm = parseYaml(fmMatch[1]);
    } catch {
      continue;
    }

    const steps: StepMeta[] = Array.isArray(fm.steps)
      ? fm.steps.map((s: any) => ({ number: s.number ?? 0, title: s.title ?? '' }))
      : [];

    const contributors = Array.isArray(fm.contributors) ? fm.contributors : [];
    const primary = contributors.length > 0 ? contributors[0] : null;
    const primaryContributorEmail = primary ? trim((primary as any).email) : null;
    const primaryContributorLogin = primary ? trim((primary as any).login) : null;

    const frontmatterGithubLogin = trim(fm.githubLogin);
    const frontmatterAuthorName = trim(fm.author);

    result[slug] = {
      slug,
      title: fm.title ?? slug,
      description: fm.description ?? '',
      time: typeof fm.time === 'number' ? fm.time : null,
      level: fm.level ?? null,
      primaryTag: fm.primaryTag ?? null,
      stepCount: fm.stepCount ?? steps.length,
      steps,
      lastUpdated: trim(fm.lastUpdated),
      primaryContributorEmail,
      primaryContributorLogin,
      frontmatterGithubLogin,
      frontmatterAuthorName,
    };
  }

  return result;
}

// --- CLI ---

/** Append a markdown block to $GITHUB_STEP_SUMMARY if set. No-op locally. */
function writeStepSummary(markdown: string) {
  const target = process.env.GITHUB_STEP_SUMMARY;
  if (!target) return;
  try {
    appendFileSync(target, markdown + '\n');
  } catch (err) {
    console.error(`[purge-orphans] Failed to append $GITHUB_STEP_SUMMARY: ${formatErrorChain(err)}`);
  }
}

export function validateFlagCombo(flags: { force: boolean; heal: boolean; verifyOnly: boolean; purgeOrphans?: boolean; unpublishSlugs?: boolean }) {
  const modes = [
    flags.force && 'force',
    flags.heal && 'heal',
    flags.verifyOnly && 'verify-only',
    flags.purgeOrphans && 'purge-orphans',
    flags.unpublishSlugs && 'unpublish-slugs'
  ].filter(Boolean);
  if (modes.length > 1) {
    throw new Error(`Flags ${modes.join(', ')} are mutually exclusive`);
  }
}

/**
 * #2349 — parse + validate the `--unpublish-slugs <csv>` argument into a clean
 * slug list. Unlike `--purge-orphans` (which COMPUTES the orphan set by diffing
 * a full local cache against the server), this mode is handed an EXPLICIT list
 * of slugs already known to be deleted upstream — the source-repo dispatch
 * computed them from `git diff --diff-filter=D`. So there is no cache to read
 * and no discovery to trust; the list IS the input.
 *
 * Validation mirrors the dispatch/receiver slug charset contract (lowercase
 * canonical [a-z0-9-]): split on comma, trim, drop empties, lowercase, and
 * reject any token with a non-slug character so a malformed dispatch payload
 * can never reach the soft-delete endpoint. De-dupes while preserving order.
 *
 * Pure: no I/O. Throws on an empty result (an unpublish call with zero valid
 * slugs is a caller bug — fail loud rather than POST an empty batch).
 */
export function parseUnpublishSlugs(csv: string): string[] {
  const seen = new Set<string>();
  const out: string[] = [];
  for (const raw of (csv ?? '').split(',')) {
    const s = raw.trim().toLowerCase();
    if (!s) continue;
    if (!/^[a-z0-9-]+$/.test(s)) {
      throw new Error(`--unpublish-slugs: invalid slug "${raw.trim()}" (must be lowercase [a-z0-9-])`);
    }
    if (seen.has(s)) continue;
    seen.add(s);
    out.push(s);
  }
  if (out.length === 0) {
    throw new Error('--unpublish-slugs: no valid slugs after parsing');
  }
  return out;
}

export type PublishMode = 'force' | 'heal' | 'delta';

/**
 * #672 operator override. Resolve the set of slugs the operator has explicitly
 * approved to commit even if the server's no-revert guard flags them as reverts
 * (source-byte churn re-reads current upstream as an abandoned-history match).
 *
 * Intentionally per-slug: `--allow-revert` MUST be paired with `--slug` so an
 * operator can only override the single tutorial they named — never blanket-
 * override every revert in a full-catalog publish. Returns [] when the flag is
 * off (guard fully active, default behavior).
 */
export function resolveAllowRevertSlugs(opts: { allowRevert: boolean; slug: string }): string[] {
  if (!opts.allowRevert) return [];
  const s = (opts.slug ?? '').trim();
  if (!s) {
    throw new Error('--allow-revert requires --slug (per-slug override only; refusing a blanket revert override)');
  }
  return [s];
}

export function computePublishPlan(opts: {
  local: Map<string, string>;
  remote: Record<string, string>;
  mode: PublishMode;
  /**
   * #2727 render-pipeline token. When provided and the local token differs from
   * the server's active token (or the server has none yet), the render pipeline
   * (parsers / Hugo templates / CSS) changed since the active publish, so a
   * delta plan treats EVERY local slug as changed — a parser/template/CSS-only
   * fix produces identical source markdown and (until `hugo/public` is rebuilt)
   * cannot be distinguished per-slug, so the pipeline token forces the republish.
   * Omit both to preserve pre-#2727 HTML-diff behavior. Ignored in force/heal
   * mode, which already select every slug.
   */
  localToken?: string;
  serverToken?: string;
}): { targetSlugs: string[]; pipelineChanged?: boolean } {
  if (opts.mode === 'force') return { targetSlugs: [...opts.local.keys()] };

  // Pipeline-token override: a changed render pipeline invalidates all renders.
  const pipelineChanged =
    opts.localToken !== undefined && opts.localToken !== opts.serverToken;
  if (pipelineChanged) {
    return { targetSlugs: [...opts.local.keys()], pipelineChanged: true };
  }

  return { targetSlugs: computeDiff(opts.local, opts.remote), pipelineChanged: false };
}

/**
 * #1668 — split the post-commit verify diff into genuine store/verify
 * mismatches vs. slugs that differ ONLY because the #672 no-revert guard
 * deliberately kept prior content (so the local revert bytes never landed).
 *
 * The auto-verify step compares local hashes against the server AFTER commit.
 * A slug the guard rejected still carries its prior (non-revert) content on the
 * server, so its local hash won't match — it lands in `verifyDiff`. Lumping it
 * into "Verify FAILED" turns a benign, expected outcome into an alarming one
 * (cost real triage time — see the issue). This partition lets the caller
 * report rejected reverts as expected and reserve "Verify FAILED" (exit 2) for
 * true mismatches.
 *
 * Pure function: order-preserving over `verifyDiff`. Rejected-revert slugs that
 * don't appear in `verifyDiff` (their bytes happened to match) are ignored, not
 * invented into either list.
 */
export function partitionVerifyMismatches(opts: {
  verifyDiff: string[];
  rejectedReverts?: string[];
}): { genuine: string[]; expectedReverts: string[] } {
  const rejected = new Set(opts.rejectedReverts ?? []);
  const genuine: string[] = [];
  const expectedReverts: string[] = [];
  for (const slug of opts.verifyDiff) {
    (rejected.has(slug) ? expectedReverts : genuine).push(slug);
  }
  return { genuine, expectedReverts };
}

/**
 * #672 short-circuit: drop slugs from `targetSlugs` whose state is already in
 * sync with the server. A slug is in sync when BOTH:
 *   - source-markdown hash matches the server's stored sourceHash, AND
 *   - rendered-HTML hash matches the server's stored contentHash.
 *
 * The double-hash check is critical. The original #672 design (PR #675) only
 * compared source-markdown — which works for the regression mode it was built
 * to catch (stale workstation cache re-uploads old bytes) but silently hides
 * the much more common case where Hugo's templates change without any source-
 * markdown change. In that case every rendered HTML differs from the server
 * but every source-md matches, so a source-only short-circuit drops every
 * slug from the publish payload, the server carries forward stale HTML, and
 * post-publish auto-verify fails (rebuild-content workflow run 28304515829,
 * the first run after #675 merged, hit exactly this).
 *
 * Pure function: no I/O. The caller is responsible for fetching the server
 * source-hash map and computing the local source-hash map.
 *
 * @param targetSlugs   slugs that `computePublishPlan` selected for upload
 * @param localSource   slug → SHA-256 of source markdown (from cache)
 * @param serverSource  slug → SHA-256 of source markdown (from /content/source-hashes)
 * @param localHtml     slug → SHA-256 of rendered HTML (from hugo/public)
 * @param serverHtml    slug → SHA-256 of rendered HTML (from /content/hashes)
 * @returns the filtered target slug list (a slug is kept unless BOTH hashes match)
 */
export function applySourceHashShortCircuit(opts: {
  targetSlugs: string[];
  localSource: Map<string, string>;
  serverSource: Record<string, string>;
  localHtml: Map<string, string>;
  serverHtml: Record<string, string>;
}): string[] {
  return opts.targetSlugs.filter((slug) => {
    const localSrc = opts.localSource.get(slug);
    const serverSrc = opts.serverSource[slug];
    const localHtml = opts.localHtml.get(slug);
    const serverHtml = opts.serverHtml[slug];
    // Drop only when BOTH source-md AND rendered-HTML match the server.
    // Missing local hash (special slug) or missing server hash (new slug) → keep.
    const sourceInSync = !!(localSrc && serverSrc && localSrc === serverSrc);
    const htmlInSync = !!(localHtml && serverHtml && localHtml === serverHtml);
    return !(sourceInSync && htmlInSync);
  });
}

interface PublishOptions {
  hugoDir: string;
  baseUrl: string;
  apiKey: string;
  trigger: string;
  hugoVersion: string;
  initiator: string;
  dryRun: boolean;
  force: boolean;
  heal: boolean;
  verifyOnly: boolean;
  verbose: boolean;
  concurrency: number;
  batchSize: number;
  purgeOrphans: boolean;
  purgeCapAbs: number;
  unpublishSlugs: string;
  slug: string;
}

function parseArgs(argv: string[]): PublishOptions {
  const get = (flag: string, fallback: string): string => {
    const idx = argv.indexOf(flag);
    return idx !== -1 && idx + 1 < argv.length ? argv[idx + 1] : fallback;
  };
  const has = (flag: string): boolean => argv.includes(flag);

  return {
    hugoDir: get('--hugo-dir', 'hugo/public'),
    baseUrl: get('--base-url', process.env.CAP_BASE_URL || 'http://localhost:4004'),
    apiKey:  get('--api-key',  process.env.CONTENT_API_KEY || ''),
    trigger: get('--trigger',  `manual@${process.env.GITHUB_SHA?.slice(0, 7) || 'local'}`),
    hugoVersion: get('--hugo-version', ''),
    initiator: get(
      '--initiator',
      process.env.INITIATOR
        || `${userInfo().username || 'unknown'}@${hostname()}`
    ),
    dryRun:    has('--dry-run'),
    force:     has('--force'),
    heal:      has('--heal'),
    verifyOnly: has('--verify-only'),
    verbose:   has('--verbose'),
    allowRevert: has('--allow-revert'),
    concurrency: parseInt(get('--concurrency', '6'), 10),
    batchSize:   parseInt(get('--batch-size', '50'), 10),
    purgeOrphans: has('--purge-orphans'),
    purgeCapAbs:  parseInt(get('--purge-cap-abs', process.env.PURGE_CAP_ABS ?? '50'), 10),
    // #2349 — targeted unpublish. Comma-separated slugs known-deleted upstream
    // (source-repo dispatch computed them via `git diff --diff-filter=D`). POSTs
    // them straight to /content/orphan-purge (soft-delete) — no cache read, no
    // orphan computation. Env fallback so the workflow can pass the dispatch's
    // deleted_slugs through without an extra flag. Empty = mode off.
    unpublishSlugs: get('--unpublish-slugs', process.env.UNPUBLISH_SLUGS ?? ''),
    // #1278 — single-tutorial fast path. When set, only this slug is hashed +
    // published; the server carries forward all other slugs from the prior
    // ACTIVE version (normal delta behavior), so the catalog stays complete.
    // Empty string = whole-catalog delta (default). Also accepts env fallback
    // so the workflow can pass TUTORIAL_SLUG through without an extra flag.
    slug: get('--slug', process.env.PUBLISH_SLUG ?? ''),
    // Multi-slug variant of --slug for the N-tutorial repository_dispatch path.
    // Comma-separated; scopes the publish to exactly these slugs (O(N), not
    // O(catalog)). Empty = fall back to --slug / whole-catalog delta. Env
    // fallback (PUBLISH_SLUGS) lets the workflow pass dispatch_slugs through.
    slugs: get('--slugs', process.env.PUBLISH_SLUGS ?? ''),
  };
}

function pickEntries<T>(src: Record<string, T>, keys: string[]): Record<string, T> {
  const out: Record<string, T> = {};
  for (const k of keys) if (k in src) out[k] = src[k];
  return out;
}

/**
 * #1278 — single-tutorial fast path. Reduce the discovered tutorials map to
 * the one requested slug (in place), so downstream hashing/payload only
 * touches that slug. Throws (caller exits non-zero) if the slug isn't present
 * in the Hugo output — a typo'd/deleted slug must fail loudly, not silently
 * publish nothing. No-op when `slug` is empty (whole-catalog delta, default).
 * Returns true if a filter was applied.
 *
 * Pure over the Map + a throwing contract, so it's unit-testable without the
 * filesystem/network.
 */
export function filterToSlug(tutorials: Map<string, string>, slug: string): boolean {
  if (!slug) return false;
  if (!tutorials.has(slug)) {
    throw new Error(
      `--slug "${slug}" not found (available count=${tutorials.size}). ` +
      `Check the slug is lowercase-canonical and its page exists.`
    );
  }
  const only = tutorials.get(slug)!;
  tutorials.clear();
  tutorials.set(slug, only);
  return true;
}

/**
 * Multi-slug variant of filterToSlug: reduce the discovered map to exactly the
 * requested slugs. Used by the N-tutorial repository_dispatch path (a push that
 * changed several tutorials) so the publish stays O(changed slugs) instead of
 * demoting to a whole-catalog delta. The server carries forward every other
 * slug at commit (same as any delta), so the catalog stays complete.
 *
 * Blank/whitespace entries are ignored and the list is de-duplicated. If ANY
 * requested slug is absent it throws (loud fail) rather than silently
 * publishing a subset — a typo in one of N slugs must not quietly drop it.
 * Pure over the Map + a throwing contract, so it's unit-testable without the
 * filesystem/network. Returns false (no-op) on an empty list.
 */
export function filterToSlugs(tutorials: Map<string, string>, slugs: string[]): boolean {
  const wanted = [...new Set((slugs ?? []).map((s) => (s ?? '').trim()).filter(Boolean))];
  if (wanted.length === 0) return false;
  const missing = wanted.filter((s) => !tutorials.has(s));
  if (missing.length) {
    throw new Error(
      `--slugs not found: ${missing.join(', ')} (available count=${tutorials.size}). ` +
      `Check each slug is lowercase-canonical and its page exists.`
    );
  }
  const kept = new Map(wanted.map((s) => [s, tutorials.get(s)!] as const));
  tutorials.clear();
  for (const [k, v] of kept) tutorials.set(k, v);
  return true;
}

// [#2885] Approuter asset gate — mirrors the check-approuter-assets.cjs step
// that rebuild-content.yml already runs. Reuses the .cjs as a subprocess to
// avoid re-implementing probe/inconclusive logic.

/** Decide whether to run the approuter asset gate based on env vars. */
export function approuterGateDecision(env: { APPROUTER_URL?: string; SKIP_APPROUTER_GATE?: string }): { run: boolean; reason: string } {
  if (!env.APPROUTER_URL) return { run: false, reason: 'no-approuter' };
  if (env.SKIP_APPROUTER_GATE) return { run: false, reason: 'skip-flag' };
  return { run: true, reason: 'ok' };
}

/** Build the argv array for the check-approuter-assets.cjs subprocess. */
export function buildApprouterGateArgs(opts: { hugoDir: string; slugs: string }, approuterUrl: string): string[] {
  const args = [
    'scripts/check-approuter-assets.cjs',
    '--approuter-url', approuterUrl,
    '--hugo-dir', opts.hugoDir,
    '--check-islands',
  ];
  if (opts.slugs.trim()) args.push('--slugs', opts.slugs.trim());
  return args;
}

/** Run the approuter asset gate. Returns 0 when skipped or passed; non-zero on gate failure. */
export function runApprouterGate(
  opts: { hugoDir: string; slug: string; slugs: string },
  env: NodeJS.ProcessEnv,
  spawn: typeof _spawnSync = _spawnSync,
): number {
  const decision = approuterGateDecision(env);
  if (!decision.run) {
    if (decision.reason === 'skip-flag') {
      console.warn('[publish-content] SKIP_APPROUTER_GATE=1 — skipping approuter asset gate (bypass mode).');
    } else {
      console.warn('[publish-content] APPROUTER_URL not set — skipping approuter asset gate (local dev mode).');
    }
    return 0;
  }
  const args = buildApprouterGateArgs(opts, env.APPROUTER_URL!);
  const result = spawn('node', args, {
    stdio: 'inherit',
    env: { ...env, PUBLISH_SLUG: opts.slug },
  });
  return result.status ?? 0;
}

async function collectSidecars(hugoDir: string, payload: Record<string, string>, log: (s: string) => void, channel: Channel = "prod"): Promise<string[]> {
  const keys: string[] = [];
  const navJsonPath = join(hugoDir, 'tutorials', '_nav.json');
  if (existsSync(navJsonPath)) {
    const navContent = readFileSync(navJsonPath);
    const navData = JSON.parse(navContent.toString('utf-8'));
    const allNavTutorials = navData.tutorials ?? navData;
    payload['__nav__'] = gzipSync(Buffer.from(JSON.stringify({ tutorials: allNavTutorials }))).toString('base64');
    keys.push('__nav__');
    log(`Included nav metadata for ${allNavTutorials.length} tutorials`);
  }
  const notFoundPath = join(hugoDir, '404.html');
  if (existsSync(notFoundPath)) {
    const notFoundContent = readFileSync(notFoundPath);
    payload['__404__'] = gzipSync(notFoundContent).toString('base64');
    keys.push('__404__');
  }
  // The chrome shell wraps tutorial content with site-wide UI (header, nav,
  // footer, Joule FAB, etc.). On the QA channel, hugo.qa.toml strips all that
  // chrome AND the QA srv at /tutorials-qa/ stands alone for author preview —
  // the __shell__ slug is unused server-side for QA reads. Skipping avoids
  // a hard failure when the QA Hugo build legitimately doesn't emit
  // _shell/index.html. Issue: rebuild-content-qa.yml run #27885050471.
  if (channel === 'qa') {
    log('Skipping __shell__ sidecar (QA channel — no chrome wrapping)');
    return keys;
  }
  const shellPath = join(hugoDir, '_shell', 'index.html');
  if (!existsSync(shellPath)) {
    throw new Error(`[publish-content] _shell/index.html missing — Hugo build did not emit chrome shell. Path: ${shellPath}`);
  }
  const shellRaw = readFileSync(shellPath, 'utf-8');
  const mainMatch = shellRaw.match(/<main\b[^>]*>[\s\S]*?<\/main>/);
  if (!mainMatch) throw new Error('[publish-content] _shell/index.html does not contain <main>...</main>');
  const shellHtml = shellRaw.replace(mainMatch[0], '<!-- MAIN -->');
  if (shellHtml.length < 1000) throw new Error(`[publish-content] chrome shell suspiciously small (${shellHtml.length} bytes)`);
  payload['__shell__'] = gzipSync(Buffer.from(shellHtml, 'utf-8')).toString('base64');
  keys.push('__shell__');
  return keys;
}


async function main() {
  const channel = parseChannel(process.argv);
  const opts = parseArgs(process.argv.slice(2));

  if (channel === 'qa') {
    const cfg = resolvePublishConfig({ channel });
    opts.hugoDir = cfg.sourceDir;
    opts.baseUrl = cfg.baseUrl;
    opts.apiKey = cfg.apiKey ?? '';
    opts.force = cfg.force;
  }

  // --verify-only is a read-only call against the public /content/source-hashes
  // endpoint (PR #591; pre-PR #591 it used /content/hashes — also public-read).
  // No auth needed, so the API key check is skipped. Without this exemption,
  // the daily content-drift-check workflow could never succeed (it sets
  // CONTENT_API_KEY="" deliberately).
  if (!opts.apiKey && !opts.verifyOnly) {
    const envHint = channel === 'qa' ? 'CONTENT_API_KEY_QA' : 'CONTENT_API_KEY';
    console.error(`Error: No API key. Set ${envHint} env var or pass --api-key`);
    process.exit(1);
  }

  const log = opts.verbose ? console.log : () => {};

  // --- verify-only short-circuit ---
  //
  // PR #591 design: --verify-only compares source-markdown hashes, NOT
  // rendered-HTML hashes. The rendered HTML is volatile-by-design relative to
  // upstream (recs rail + CAP-fed breadcrumbs + Shiki vs Chroma + ...), and
  // every previous attempt to normalize those volatile regions out of the hash
  // (#589, #590) failed to scale because there are too many. The source
  // markdown changes only when an author edits the upstream tutorial — a
  // monotonic, meaningful signal.
  //
  // The drift workflow now runs ONLY `npm run fetch-tutorials` before
  // --verify-only — no Hugo build, no Shiki, no Vue. Fast (~1-2 min) and
  // accurate.
  //
  // Runs BEFORE `discoverTutorials(opts.hugoDir)` so the drift workflow
  // doesn't need to build Hugo at all. Pre-PR #591 the verify-only path
  // ran AFTER the Hugo-discovery step and would error out with 'No
  // tutorials found. Did you run the Hugo build?' on a workflow that
  // skipped Hugo — caught the morning of 2026-06-24 by run 28104752827.
  if (opts.verifyOnly) {
    const cacheDir = channel === 'qa'
      ? join(process.cwd(), '.tutorial-cache-qa')
      : join(process.cwd(), '.tutorial-cache');

    // 1) Discover slugs from the cache by listing *.md files (NOT from Hugo
    //    output, which the workflow no longer builds).
    let mdFiles: string[];
    try { mdFiles = readdirSync(cacheDir).filter(f => f.endsWith('.md') && !f.startsWith('_')); }
    catch (err) {
      console.error(`Verify failed: cannot read tutorial-cache dir ${cacheDir}: ${formatErrorChain(err)}`);
      process.exit(1);
    }
    const localHashes = new Map<string, string>();
    for (const f of mdFiles) {
      const slug = f.replace(/\.md$/, '');
      const buf = readFileSync(join(cacheDir, f));
      localHashes.set(slug, createHash('sha256').update(buf).digest('hex'));
    }
    log(`Hashed ${localHashes.size} source markdown files in ${cacheDir}`);

    // 2) Fetch server's source-hash map.
    let remote: Record<string, string>;
    try {
      remote = await fetchRemoteSourceHashes({ baseUrl: opts.baseUrl, apiKey: opts.apiKey });
    } catch (err) {
      console.error('Verify failed: cannot reach /content/source-hashes:', formatErrorChain(err));
      process.exit(1);
    }
    const serverSlugCount = Object.keys(remote).length;
    log(`Fetched ${serverSlugCount} source hashes from ${opts.baseUrl}/content/source-hashes`);

    // 3) Diff. Only count slugs the server actually KNOWS about — if the
    //    server returned an empty/partial map (e.g. server pre-dates PR
    //    #591 and never wrote source hashes), warn and exit 0. Otherwise
    //    a fresh deploy would always look like 1400 slugs of "drift".
    if (serverSlugCount === 0) {
      console.warn('');
      console.warn('Verify SKIPPED: server returned 0 source hashes.');
      console.warn('  This is expected immediately after PR #591 deploys, before');
      console.warn('  a new publish-content run has populated sourceHash. Re-run');
      console.warn('  this verify after `npm run publish-content` completes.');
      process.exit(0);
    }

    const drifted: string[] = [];
    const missingLocal: string[] = []; // present on server, missing in local cache
    const missingServer: string[] = []; // present locally, no hash on server
    for (const [slug, localHash] of localHashes) {
      const serverHash = remote[slug];
      if (!serverHash) {
        missingServer.push(slug);
        continue;
      }
      if (serverHash !== localHash) drifted.push(slug);
    }
    for (const slug of Object.keys(remote)) {
      if (!localHashes.has(slug)) missingLocal.push(slug);
    }

    console.log('');
    console.log('Verify summary (source-markdown hash compare):');
    console.log(`  Total local source files:        ${localHashes.size}`);
    console.log(`  Total server source hashes:      ${serverSlugCount}`);
    console.log(`  Drifted (content differs):       ${drifted.length}`);
    console.log(`  Missing on server (not yet published / pre-#591): ${missingServer.length}`);
    console.log(`  Missing locally (server has, local doesn't): ${missingLocal.length}`);

    if (drifted.length === 0) {
      console.log('');
      console.log('Verify OK: no source-markdown drift detected.');
      process.exit(0);
    }
    console.error('');
    console.error(`Verify FAILED: ${drifted.length} slug(s) have source-markdown drift:`);
    for (const s of drifted.slice(0, 50).sort()) console.error(`  - ${s}`);
    if (drifted.length > 50) console.error(`  ... (+${drifted.length - 50} more)`);
    process.exit(2);
  }

  // --- --unpublish-slugs short-circuit (#2349) ---
  // Targeted soft-delete of an EXPLICIT list of tutorials deleted upstream.
  // Unlike --purge-orphans (which diffs a full local cache to DISCOVER orphans),
  // the slug list here is already known — the source-repo dispatch computed it
  // via `git diff --diff-filter=D` and passed it as deleted_slugs. So this mode
  // reads no cache and fetches no catalog; it just POSTs the list to the same
  // /content/orphan-purge endpoint (soft-delete, redirectTo-honoring, bucketed).
  // Reuses the purge endpoint, the cap, and the bucket-report shape.
  if (opts.unpublishSlugs) {
    // CI-only guard — same posture as --purge-orphans; a destructive soft-delete
    // must never run from a workstation against whatever env CAP_BASE_URL points at.
    if (!process.env.GITHUB_ACTIONS) {
      console.error('unpublish-slugs is CI-only; it is driven by the rebuild-content deletion lane.');
      process.exit(1);
    }
    if (!Number.isFinite(opts.purgeCapAbs) || opts.purgeCapAbs <= 0) {
      console.error(`Invalid --purge-cap-abs / PURGE_CAP_ABS: "${process.env.PURGE_CAP_ABS ?? '(unset)'}" — must be a positive integer`);
      process.exit(1);
    }

    let slugs: string[];
    try {
      slugs = parseUnpublishSlugs(opts.unpublishSlugs);
    } catch (err) {
      console.error(`[unpublish-slugs] ${err instanceof Error ? err.message : String(err)}`);
      process.exit(1);
    }

    // Same 50-slug default cap as --purge-orphans: a commit deleting >50
    // tutorials is exactly the "did the author really mean this?" case. Fail
    // loud; operator re-runs deliberately (or splits the batch).
    const capErr = enforceCap(slugs.length, opts.purgeCapAbs);
    if (capErr) {
      console.error(`[unpublish-slugs] ${capErr}`);
      for (const s of slugs.slice(0, 20)) console.error(`  - ${s}`);
      process.exit(1);
    }

    console.log(`[unpublish-slugs] ${slugs.length} slug(s) to unpublish: ${slugs.slice(0, 10).join(', ')}${slugs.length > 10 ? ` ... (+${slugs.length - 10} more)` : ''}`);

    if (opts.dryRun) {
      console.log(`[unpublish-slugs] --dry-run: would have unpublished ${slugs.length} slug(s); exiting`);
      process.exit(0);
    }

    const purgeUrl = `${opts.baseUrl.replace(/\/$/, '')}/content/orphan-purge`;
    const initiator = opts.initiator;
    console.log(`[unpublish-slugs] POST ${purgeUrl} (${slugs.length} slugs, initiator=${initiator})`);

    let resp: Response;
    try {
      resp = await fetch(purgeUrl, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${opts.apiKey}`,
          'Content-Type':  'application/json',
          'x-initiator':   initiator
        },
        body: JSON.stringify({ slugs })
      });
    } catch (err) {
      console.error(`[unpublish-slugs] Connectivity error — verify CAP_BASE_URL: ${formatErrorChain(err)}`);
      process.exit(1);
    }

    if (!resp.ok) {
      const bodyText = await resp.text();
      let msg: string;
      if (resp.status === 401 || resp.status === 403) {
        msg = 'Auth failure — check CONTENT_API_KEY secret for this environment';
      } else if (resp.status === 400) {
        msg = `Server rejected payload — ${bodyText}`;
      } else if (resp.status >= 500) {
        msg = `Server error — retry once with same INITIATOR; endpoint is idempotent. Body: ${bodyText}`;
      } else {
        msg = `Unexpected status ${resp.status}: ${bodyText}`;
      }
      console.error(`[unpublish-slugs] ${msg}`);
      process.exit(1);
    }

    const result = await resp.json() as {
      purged: string[]; alreadyInactive: string[]; notFound: string[]; redirected: string[];
      totalAttempted: number; totalPurged: number; version: number;
    };
    const bucketSum = result.purged.length + result.alreadyInactive.length + result.notFound.length + result.redirected.length;
    if (bucketSum !== result.totalAttempted) {
      console.error(`[unpublish-slugs] Server returned malformed response: bucket sum ${bucketSum} != totalAttempted ${result.totalAttempted}`);
      process.exit(1);
    }

    console.log('[unpublish-slugs] Response:');
    console.log(`  purged:          ${result.purged.length}`);
    console.log(`  alreadyInactive: ${result.alreadyInactive.length}`);
    console.log(`  notFound:        ${result.notFound.length}${result.notFound.length ? ` (no Tutorials row — never published, or already hard-gone: ${result.notFound.join(', ')})` : ''}`);
    console.log(`  redirected:      ${result.redirected.length}${result.redirected.length ? ` (preserved: ${result.redirected.slice(0, 5).join(', ')})` : ''}`);
    console.log(`  manifest version: ${result.version}`);
    writeStepSummary(formatStepSummary({
      mode: 'committed',
      serverCount: result.totalAttempted,
      orphanCount: slugs.length,
      purged: result.purged.length,
      alreadyInactive: result.alreadyInactive.length,
      notFound: result.notFound.length,
      redirected: result.redirected.length,
      redirectedSamples: result.redirected,
      version: result.version
    }));
    console.log(`[unpublish-slugs] Done — ${result.purged.length} slug(s) soft-deleted`);
    process.exit(0);
  }

  // --- --purge-orphans short-circuit ---
  // CI-only batched soft-delete of tutorials whose source markdown is no
  // longer in any upstream repo. Spec:
  //   docs/superpowers/specs/2026-06-30-orphan-purge-design.md
  if (opts.purgeOrphans) {
    // 1. CI-only guard
    if (!process.env.GITHUB_ACTIONS) {
      console.error('purge-orphans is CI-only; run via:');
      console.error('  gh workflow run rebuild-content.yml -f mode=full -f purge-orphans=true');
      process.exit(1);
    }

    // 1b. Validate cap is a positive finite integer — guards against
    //     PURGE_CAP_ABS=fifty or --purge-cap-abs=-1, both of which would
    //     otherwise produce an unhelpful "exceeds cap (N > NaN abs)" later.
    if (!Number.isFinite(opts.purgeCapAbs) || opts.purgeCapAbs <= 0) {
      console.error(`Invalid --purge-cap-abs / PURGE_CAP_ABS: "${process.env.PURGE_CAP_ABS ?? '(unset)'}" — must be a positive integer`);
      process.exit(1);
    }

    // 2. Load local hashes (same readdir as --verify-only)
    const cacheDir = channel === 'qa'
      ? join(process.cwd(), '.tutorial-cache-qa')
      : join(process.cwd(), '.tutorial-cache');
    let mdFiles: string[];
    try { mdFiles = readdirSync(cacheDir).filter(f => f.endsWith('.md') && !f.startsWith('_')); }
    catch (err) {
      console.error(`purge-orphans: cannot read tutorial-cache dir ${cacheDir}: ${formatErrorChain(err)}`);
      process.exit(1);
    }
    const localSlugs = new Set(mdFiles.map(f => f.replace(/\.md$/, '')));
    log(`[purge-orphans] Hashed ${localSlugs.size} local source markdown files in ${cacheDir}`);

    // 3. Fetch /content/source-hashes
    let remote: Record<string, string>;
    try { remote = await fetchRemoteSourceHashes({ baseUrl: opts.baseUrl, apiKey: opts.apiKey }); }
    catch (err) {
      console.error('purge-orphans: cannot reach /content/source-hashes:', formatErrorChain(err));
      process.exit(1);
    }
    const serverSlugs = Object.keys(remote);
    log(`[purge-orphans] Fetched ${serverSlugs.length} server slugs`);

    // 4. Compute orphans
    const orphans = computeOrphans(serverSlugs, localSlugs);
    const pctInfo = serverSlugs.length ? ((orphans.length / serverSlugs.length) * 100).toFixed(1) : '0.0';
    log(`[purge-orphans] Computed ${orphans.length} orphans (${pctInfo}% of server — informational)`);

    // 5. Cap check
    const capErr = enforceCap(orphans.length, opts.purgeCapAbs);
    if (capErr) {
      console.error(`[purge-orphans] ${capErr}`);
      console.error(`[purge-orphans] First 20 orphans:`);
      for (const s of orphans.slice(0, 20)) console.error(`  - ${s}`);
      writeStepSummary(formatStepSummary({
        mode: 'failed', serverCount: serverSlugs.length, orphanCount: orphans.length, errorMessage: capErr
      }));
      process.exit(1);
    }
    log(`[purge-orphans] Cap check: ${orphans.length} <= ${opts.purgeCapAbs} abs → passes`);

    // 6. Sample
    const sample = orphans.slice(0, 10).join(', ');
    log(`[purge-orphans] Sample orphans: ${sample}${orphans.length > 10 ? ` ... (+${orphans.length - 10} more)` : ''}`);

    // 7. Dry-run short-circuit
    if (opts.dryRun) {
      log(`[purge-orphans] --dry-run: would have purged ${orphans.length} slug(s); exiting`);
      writeStepSummary(formatStepSummary({
        mode: 'dry-run', serverCount: serverSlugs.length, orphanCount: orphans.length
      }));
      process.exit(0);
    }

    // 8. POST /content/orphan-purge
    const initiator = opts.initiator;
    const purgeUrl = `${opts.baseUrl.replace(/\/$/, '')}/content/orphan-purge`;
    log(`[purge-orphans] POST ${purgeUrl} (${orphans.length} slugs, initiator=${initiator})`);

    let resp: Response;
    try {
      resp = await fetch(purgeUrl, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.CONTENT_API_KEY ?? ''}`,
          'Content-Type':  'application/json',
          'x-initiator':   initiator
        },
        body: JSON.stringify({ slugs: orphans })
      });
    } catch (err) {
      const msg = `Connectivity error — verify CAP_BASE_URL: ${formatErrorChain(err)}`;
      console.error(`[purge-orphans] ${msg}`);
      writeStepSummary(formatStepSummary({
        mode: 'failed', serverCount: serverSlugs.length, orphanCount: orphans.length, errorMessage: msg
      }));
      process.exit(1);
    }

    // 9. Error handling
    if (!resp.ok) {
      const bodyText = await resp.text();
      let msg: string;
      if (resp.status === 401 || resp.status === 403) {
        msg = `Auth failure — check CONTENT_API_KEY secret for this environment`;
      } else if (resp.status === 400) {
        msg = `Server rejected payload — ${bodyText}`;
      } else if (resp.status >= 500) {
        msg = `Server error — retry once with same INITIATOR; endpoint is idempotent. Body: ${bodyText}`;
      } else {
        msg = `Unexpected status ${resp.status}: ${bodyText}`;
      }
      console.error(`[purge-orphans] ${msg}`);
      writeStepSummary(formatStepSummary({
        mode: 'failed', serverCount: serverSlugs.length, orphanCount: orphans.length, errorMessage: msg
      }));
      process.exit(1);
    }

    // 10. Parse + sanity check
    const result = await resp.json() as {
      purged: string[]; alreadyInactive: string[]; notFound: string[]; redirected: string[];
      totalAttempted: number; totalPurged: number; version: number;
    };
    const bucketSum = result.purged.length + result.alreadyInactive.length + result.notFound.length + result.redirected.length;
    if (bucketSum !== result.totalAttempted) {
      const msg = `Server returned malformed response: bucket sum ${bucketSum} != totalAttempted ${result.totalAttempted}`;
      console.error(`[purge-orphans] ${msg}`);
      writeStepSummary(formatStepSummary({
        mode: 'failed', serverCount: serverSlugs.length, orphanCount: orphans.length, errorMessage: msg
      }));
      process.exit(1);
    }

    // 11. Print summary to stdout
    console.log(`[purge-orphans] Response:`);
    console.log(`  purged:          ${result.purged.length}`);
    console.log(`  alreadyInactive: ${result.alreadyInactive.length}`);
    console.log(`  notFound:        ${result.notFound.length}`);
    if (result.notFound.length > 0) {
      console.log(`    ⚠️  These slugs have no Tutorials parent row (phantom). Operator action required — file one issue per slug:`);
      for (const s of result.notFound) console.log(`      - ${s}`);
    }
    console.log(`  redirected:      ${result.redirected.length}${result.redirected.length ? ` (preserved: ${result.redirected.slice(0, 5).join(', ')})` : ''}`);
    console.log(`  manifest version: ${result.version}`);

    // 12. Step summary
    writeStepSummary(formatStepSummary({
      mode: 'committed',
      serverCount: serverSlugs.length,
      orphanCount: orphans.length,
      purged: result.purged.length,
      alreadyInactive: result.alreadyInactive.length,
      notFound: result.notFound.length,
      redirected: result.redirected.length,
      redirectedSamples: result.redirected,
      version: result.version
    }));

    log(`[purge-orphans] Done — ${result.purged.length} slugs soft-deleted`);
    process.exit(0);
  }

  log(`Discovering tutorials in ${opts.hugoDir}...`);
  const tutorials = discoverTutorials(opts.hugoDir);

  // Drop any stale group-*/mission-* directories left in hugo/public/tutorials
  // by older builds. Catalog pages have been runtime-SSR'd from the DB since
  // PR #115 (#91); shipping them would create phantom Tutorials rows in HANA
  // and leak into the Admin UI Tutorials list (#114). The server enforces the
  // same filter, this is just a nicety so we don't waste a few KB of payload.
  const droppedCatalogSlugs = stripCatalogSlugs(tutorials);
  if (droppedCatalogSlugs.length) {
    console.warn(
      `[publish-content] dropping ${droppedCatalogSlugs.length} stale catalog ` +
      `slug(s) from Hugo output (these are SSR'd from DB, not published): ` +
      droppedCatalogSlugs.slice(0, 10).join(', ') +
      (droppedCatalogSlugs.length > 10 ? ` (+${droppedCatalogSlugs.length - 10} more)` : '')
    );
  }

  // #446 Track 3-A / #1327 Thread B — concept detail pages are rendered
  // server-side by CAP via the render-concepts publish phase (below), NOT
  // walked from hugo/public/concepts here. The legacy Hugo concept pipeline
  // (fetch-concepts.ts + hugo/layouts/concepts + the LEGACY_CONCEPT_RENDER
  // escape hatch) was retired in #1327 Task 6 once the CAP path was stable on
  // DEV + PROD. The `concept-<slug>` key convention, serve path, and delta
  // machinery are unchanged — only the source of the BLOBs moved to CAP.

  // #1278 — single-tutorial fast path, generalized to N slugs for the
  // multi-tutorial repository_dispatch path. Filter the discovered map down to
  // the requested slug(s) BEFORE hashing (computeLocalHashes reads N files
  // instead of ~1372). filterToSlug/filterToSlugs throw on an unknown slug;
  // exit 2 (loud, distinct from the generic exit 1) so a typo doesn't silently
  // publish nothing. The server carries forward all other slugs at commit
  // (same as any delta). `--slug` and `--slugs` are unioned; `isScoped` below
  // gates the page/author/concept full-catalog merges off any scoped publish.
  const requestedSlugs = [
    ...(opts.slug ? [opts.slug] : []),
    ...(opts.slugs ? opts.slugs.split(',') : []),
  ];
  const isScoped = requestedSlugs.some((s) => (s ?? '').trim());
  if (isScoped) {
    try {
      filterToSlugs(tutorials, requestedSlugs);
      log(`[--slug(s)] scoped publish to ${tutorials.size} tutorial(s): ${[...tutorials.keys()].join(', ')}`);
    } catch (err) {
      console.error(`Error: ${err instanceof Error ? err.message : err} (hugoDir=${opts.hugoDir})`);
      process.exit(2);
    }
  }

  if (tutorials.size === 0) {
    console.error('Error: No tutorials found. Did you run the Hugo build?');
    process.exit(1);
  }

  log(`Found ${tutorials.size} tutorials`);

  // [#2885] Pre-flight approuter asset gate — block before any BLOB write if
  // the deployed approuter doesn't serve the CSS/JS hashes baked into the HTML.
  // Skips loudly when APPROUTER_URL is unset (local dev / cds watch has no
  // approuter). Set SKIP_APPROUTER_GATE=1 to bypass in a genuine emergency.
  const gateCode = runApprouterGate(
    { hugoDir: opts.hugoDir, slug: opts.slug ?? '', slugs: opts.slugs ?? '' },
    process.env,
  );
  if (gateCode !== 0) {
    console.error('[publish-content] approuter asset gate failed — aborting before any BLOB write.');
    process.exit(gateCode);
  }

  const violations = validateProductionBuild(tutorials);
  if (violations.length > 0) {
    console.error('Error: Hugo output contains dev-build artifacts. Refusing to publish.');
    console.error('Run `hugo --environment production` before publishing.\n');
    for (const v of violations) {
      console.error(`  ✗ ${v}`);
    }
    process.exit(1);
  }
  log('Production build validation passed');

  validateFlagCombo({ force: opts.force, heal: opts.heal, verifyOnly: opts.verifyOnly, purgeOrphans: opts.purgeOrphans, unpublishSlugs: !!opts.unpublishSlugs });

  // #672 — resolve the per-slug operator override up front so a misused
  // `--allow-revert` (without `--slug`) fails loudly BEFORE any publish work.
  const allowRevertSlugs = resolveAllowRevertSlugs({ allowRevert: opts.allowRevert, slug: opts.slug });
  if (allowRevertSlugs.length) {
    log(`[--allow-revert] #672 no-revert guard will be overridden for: ${allowRevertSlugs.join(', ')}`);
  }

  // #1659 — content pages ride the same delta pipeline as tutorials under the
  // page- key namespace. Merge AFTER tutorial-only validation so page files are
  // not subject to tutorial production checks, and BEFORE hashing so the whole
  // begin/append/commit + carry-forward path handles them transparently.
  // Skipped on scoped hotfixes (--slug / --slugs), like concepts.
  if (!isScoped) {
    const pages = discoverPageFiles(opts.hugoDir);
    for (const [key, absPath] of pages) tutorials.set(key, absPath);
    log(`[pages] merged ${pages.size} content page(s) into publish set`);

    // #1659 Phase C — author pages (author-<login>) ride the same delta
    // pipeline as pages/tutorials. Unbounded dynamic slugs, published as BLOBs.
    const authors = discoverAuthorPages(opts.hugoDir);
    for (const [key, absPath] of authors) tutorials.set(key, absPath);
    log(`[authors] merged ${authors.size} author page(s) into publish set`);

    // #1659 Phase C.2a — per-advocate detail pages (advocate-<slug>), same path.
    const advocates = discoverAdvocatePages(opts.hugoDir);
    for (const [key, absPath] of advocates) tutorials.set(key, absPath);
    log(`[advocates] merged ${advocates.size} advocate detail page(s) into publish set`);
  }

  log('Computing local hashes...');
  const localHashes = computeLocalHashes(tutorials);

  // --- decide what to publish ---
  let mode: PublishMode = 'delta';
  if (opts.force) mode = 'force';
  else if (opts.heal) mode = 'heal';

  let remoteHashes: Record<string, string> = {};
  // #2727 — render-pipeline token. Hash the inputs that determine how every
  // slug renders (parsers, Hugo templates, CSS). If it differs from the server's
  // active token, the pipeline changed and every slug must re-publish even when
  // per-slug source+HTML hashes match. Computed once; sent on commit so the next
  // publish can compare. Server token lives on the X-Pipeline-Token header of
  // /content/hashes; null (legacy server / no ACTIVE manifest) → full publish.
  const localPipelineToken = computePipelineToken();
  let serverPipelineToken: string | null = null;
  if (mode !== 'force') {
    log(`Fetching remote hashes from ${opts.baseUrl}/content/hashes...`);
    // #2286 — retry transient 500s (HANA pool-acquire timeout) so a momentary
    // load spike during delta detection doesn't fatally abort the rebuild
    // before a session is even opened. 503 already returns {} inside the client.
    // pipelineToken (#2727) is read from the same response header — no second GET.
    let fetchResult: { hashes: Record<string, string>; pipelineToken: string | null };
    try {
      fetchResult = await withRetry(
        () => fetchRemoteHashes({ baseUrl: opts.baseUrl, apiKey: opts.apiKey }),
        {
          attempts: 4, backoffMs: [1000, 3000, 6000], jitterRatio: 0.2,
          onAttemptFail: (attempt, err, willRetry) => {
            console.error(`[publish-content] /content/hashes fetch failed (attempt ${attempt}/4): ${formatErrorChain(err)}${willRetry ? ' — retrying' : ''}`);
          },
        }
      );
    }
    catch (err) {
      console.error(`Cannot reach ${opts.baseUrl}/content/hashes: ${formatErrorChain(err)}`);
      process.exit(1);
    }
    remoteHashes = fetchResult!.hashes;
    if (mode === 'delta') {
      serverPipelineToken = fetchResult!.pipelineToken;
    }
  }

  const planResult = computePublishPlan({
    local: localHashes,
    remote: remoteHashes,
    mode,
    localToken: mode === 'delta' ? localPipelineToken : undefined,
    serverToken: mode === 'delta' ? serverPipelineToken ?? undefined : undefined,
  });
  let targetSlugs = planResult.targetSlugs;
  if (planResult.pipelineChanged) {
    log(`#2727 render-pipeline token changed (local=${localPipelineToken.slice(0, 9)} server=${serverPipelineToken ? serverPipelineToken.slice(0, 9) : 'none'}) — forcing re-publish of all ${targetSlugs.length} slugs`);
  }

  // #672 — client-side short-circuit. In delta mode only, drop slugs whose
  // upstream state is already in sync with the server's stored state.
  // Detailed rationale + the source-md-only-was-buggy story lives on
  // `applySourceHashShortCircuit`.
  //
  // --force and --heal explicitly skip this layer:
  //   --force: "upload everything regardless of server state"
  //   --heal : "fix slugs the client thinks are in sync"
  //
  // #2727 — ALSO skipped when the pipeline token changed. A parser/template/CSS
  // fix leaves source markdown AND (pre-rebuild) rendered HTML matching the
  // server, so the short-circuit would re-drop exactly the slugs the token just
  // forced in, re-opening the bug. The token mismatch IS the signal to publish.
  if (mode === 'delta' && !planResult.pipelineChanged && targetSlugs.length > 0) {
    // `channel` is defined earlier in main() as `const channel = parseChannel(process.argv)`
    // (around line 478) — same value used by the existing verify-only path.
    const cacheDirForHashes = channel === 'qa'
      ? join(process.cwd(), '.tutorial-cache-qa')
      : join(process.cwd(), '.tutorial-cache');
    const localSourceHashes = computeLocalSourceHashes(targetSlugs, cacheDirForHashes);
    let serverSourceHashes: Record<string, string> = {};
    try {
      serverSourceHashes = await fetchRemoteSourceHashes({ baseUrl: opts.baseUrl, apiKey: opts.apiKey });
    } catch (err) {
      console.warn(`[publish-content] #672 short-circuit disengaged: cannot reach /content/source-hashes: ${formatErrorChain(err)}`);
    }
    const beforeCount = targetSlugs.length;
    targetSlugs = applySourceHashShortCircuit({
      targetSlugs,
      localSource: localSourceHashes,
      serverSource: serverSourceHashes,
      localHtml: localHashes,
      serverHtml: remoteHashes,
    });
    const dropped = beforeCount - targetSlugs.length;
    if (dropped > 0) log(`#672 short-circuit: dropped ${dropped} of ${beforeCount} slugs (source + html hash both match server)`);
  }
  if (targetSlugs.length === 0) {
    console.log('No changes detected. Nothing to publish.');
    process.exit(0);
  }
  console.log(`${targetSlugs.length} of ${tutorials.size} tutorials to publish (${mode} mode)`);

  if (opts.dryRun) {
    console.log('Dry run — would publish:');
    for (const slug of targetSlugs.slice().sort()) console.log(`  ${slug}`);
    process.exit(0);
  }

  // --- begin / append / commit ---
  log('Building payload + extracting metadata...');
  const startTime = Date.now();
  const payload    = buildPayload(targetSlugs, tutorials);
  const hugoContentDir = join(opts.hugoDir, '..', 'content', 'tutorials');
  // Tutorials-only extractions: metadata, bodyText, branchSpecs, and source
  // markdown all key off Tutorials.slug (or files that only exist for
  // tutorials). Concept slugs (concept-<name>) would silently produce no
  // metadata entries (no .md in hugo/content/tutorials/) but extractAllBodyTexts
  // would happily emit a body-text row keyed `concept-<name>`, orphaning it in
  // TutorialBodyText. Filter them out explicitly so the contract is clear.
  const tutorialOnlySlugs = targetSlugs.filter(s => !isConceptSlug(s) && !isAuthorSlug(s) && !isAdvocateSlug(s));
  const metadataAll = extractMetadata(hugoContentDir, tutorialOnlySlugs);
  const bodyTextsAll = extractAllBodyTexts(tutorials, tutorialOnlySlugs);
  const branchSpecsAll = extractAllBranchSpecs(hugoContentDir, tutorialOnlySlugs);

  // PR #591: capture raw upstream markdown alongside rendered HTML. Each
  // tutorial's source lives at `.tutorial-cache/<slug>.md` (or
  // `.tutorial-cache-qa/<slug>.md` for QA), populated by fetch-tutorials.
  // Special slugs (__shell__, __nav__, __404__) have no upstream source —
  // buildSourcePayload silently skips them, and the server stores null
  // sourceContent/sourceHash for those rows. The drift workflow uses these
  // sourceHashes instead of contentHashes for clean drift detection.
  // Concept slugs are likewise tutorial-only — no upstream .md exists.
  const cacheDir = channel === 'qa'
    ? join(process.cwd(), '.tutorial-cache-qa')
    : join(process.cwd(), '.tutorial-cache');
  const { sources: sourcesAll, sourceHashes: localSourceHashes } =
    buildSourcePayload(tutorialOnlySlugs, cacheDir);
  log(`Source markdown payload: ${Object.keys(sourcesAll).length}/${tutorialOnlySlugs.length} slugs have upstream .md files`);

  // #2245: build per-slug git commit SHA map (keyed by original-case slug,
  // matching `files`). Reads .commit-sha sidecars written by fetch-tutorials.
  // Silently empty when sidecars are absent (e.g. first run or cached path).
  const sourceCommitsAll = buildSourceCommitsPayload(tutorialOnlySlugs, cacheDir);
  log(`Source commit SHA payload: ${Object.keys(sourceCommitsAll).length}/${tutorialOnlySlugs.length} slugs have commit SHAs`);

  const sourceReposAll = buildSourceReposPayload(tutorialOnlySlugs, cacheDir);
  log(`Source repo payload: ${Object.keys(sourceReposAll).length}/${tutorialOnlySlugs.length} slugs have source repos`);

  // __nav__ / __404__ / __shell__ ride along on the first batch (these are
  // small and the server happily accepts them mixed with regular slugs).
  const sidecarKeys = await collectSidecars(opts.hugoDir, payload, log, channel);

  // #2286 — begin was the ONE publish HTTP call in the happy path with neither
  // withRetry nor a try/catch, so a transient HANA pool-acquire 500 ("Pool
  // resource could not be acquired within 1s") aborted the whole rebuild via
  // the top-level Fatal catch. Wrap it like commit: 500/502/503/504 are already
  // classified transient in publish-retry.ts; jitter de-syncs the three DevRel
  // projects so a briefly-saturated pool isn't re-hit in lockstep.
  const begin = await withRetry(
    () => beginSession({
      baseUrl: opts.baseUrl, apiKey: opts.apiKey,
      trigger: opts.trigger, hugoVersion: opts.hugoVersion, expectedSlugCount: targetSlugs.length,
      initiator: opts.initiator,
    }),
    {
      attempts: 5, backoffMs: [2000, 5000, 10000, 20000], jitterRatio: 0.2,
      onAttemptFail: (attempt, err, willRetry) => {
        console.error(`[publish-content] begin failed (attempt ${attempt}/5): ${formatErrorChain(err)}${willRetry ? ' — retrying' : ''}`);
      },
    }
  );
  log(`Session ${begin.sessionId} version ${begin.version} (expires ${begin.expiresAt})`);

  const allKeys = [...targetSlugs, ...sidecarKeys];
  const batches = chunk(allKeys, opts.batchSize);
  log(`${batches.length} batches × up to ${opts.batchSize} slugs, concurrency=${opts.concurrency}`);

  try {
    await runConcurrent(
      batches.map((batch, idx) => () => withRetry(
        () => appendBatch({
          baseUrl: opts.baseUrl, apiKey: opts.apiKey,
          sessionId: begin.sessionId,
          files:     pickEntries(payload,        batch),
          metadata:  pickEntries(metadataAll,    batch),
          bodyTexts: pickEntries(bodyTextsAll,   batch),
          branchSpecs: pickEntries(branchSpecsAll, batch),
          // Sidecar keys (__shell__ etc.) won't appear in sourcesAll —
          // pickEntries returns {} for them, which the server treats as
          // "no source for this batch" and skips the source-side INSERT.
          sources:   pickEntries(sourcesAll,     batch),
          // #2245: thread per-slug git commit SHA so the server stamps
          // sourceCommit on each ContentCurrent row. Sidecar keys produce {}
          // (no .commit-sha sidecar exists for __shell__ etc.) which is fine
          // — the server stores null for missing entries.
          sourceCommits: pickEntries(sourceCommitsAll, batch),
          sourceRepos: pickEntries(sourceReposAll, batch),
        }),
        {
          attempts: 3, backoffMs: [1000, 3000, 9000],
          onAttemptFail: (attempt, err, willRetry) => {
            console.error(
              `[publish-content] append batch ${idx + 1}/${batches.length} failed (attempt ${attempt}/3)\n  ${formatErrorChain(err)}\n  ${willRetry ? 'retrying...' : 'giving up'}`
            );
          },
        }
      )),
      opts.concurrency
    );
  } catch (err) {
    console.error(`[publish-content] append failed permanently: ${formatErrorChain(err)}`);
    await abortSession({ baseUrl: opts.baseUrl, apiKey: opts.apiKey, sessionId: begin.sessionId, reason: 'append failed' });
    process.exit(1);
  }

  // #1327 Thread B — render concept detail pages server-side into the open
  // session, AFTER all tutorial batches (so __shell__ is present) and BEFORE
  // commit. Skipped on a single-tutorial slug hotfix (concepts aren't part of
  // that scope; the server carries them forward unchanged at commit). A phase
  // failure aborts the session — same posture as an append failure.
  //
  // QA channel skip: concept detail pages are a prod-only public content
  // surface — POST /content/publish/render-concepts is intentionally NOT
  // registered on srv-qa (see ALLOWLIST_ONLY_ON_SRV in
  // scripts/check-srv-qa-route-drift.ts: "the QA channel has no concept
  // publish flow"). Without this guard a full QA rebuild (no slug) hits the
  // absent route → 404 → abortSession → exit 1, which is exactly what silently
  // broke every QA merge-to-main publish. Gating here keeps the caller
  // consistent with the server's route surface.
  // #2802: mirror pipelineToken — capture conceptPhaseToken from the render result
  // so commitSession can persist it on ContentManifest for Level-1 phase-skip.
  let localConceptPhaseToken: string | null = null;
  if (!isScoped && channel === 'prod') {
    try {
      const rc = await withRetry(
        () => renderConceptsPhase({ baseUrl: opts.baseUrl, apiKey: opts.apiKey, sessionId: begin.sessionId }),
        {
          attempts: 3, backoffMs: [1000, 3000, 9000],
          onAttemptFail: (attempt, err, willRetry) => {
            console.error(`[publish-content] render-concepts failed (attempt ${attempt}/3): ${formatErrorChain(err)}${willRetry ? ' — retrying' : ''}`);
          },
        }
      );
      localConceptPhaseToken = rc.conceptPhaseToken ?? null;
      log(`render-concepts: ${rc.conceptsChanged} changed, ${rc.conceptsSkipped} skipped, ${rc.conceptsErrored} errored of ${rc.conceptsSeen} (${rc.durationMs} ms)`);
    } catch (err) {
      console.error(`[publish-content] render-concepts failed permanently: ${formatErrorChain(err)}`);
      await abortSession({ baseUrl: opts.baseUrl, apiKey: opts.apiKey, sessionId: begin.sessionId, reason: 'render-concepts failed' });
      process.exit(1);
    }
    // tag-tree-topics Task 7 — render topic detail pages alongside concepts.
    // Same guard (prod-only, full-publish): POST /content/publish/render-topics
    // is not registered on srv-qa (topics are a prod-only content surface).
    try {
      const rt = await withRetry(
        () => renderTopicsPhase({ baseUrl: opts.baseUrl, apiKey: opts.apiKey, sessionId: begin.sessionId }),
        {
          attempts: 3, backoffMs: [1000, 3000, 9000],
          onAttemptFail: (attempt, err, willRetry) => {
            console.error(`[publish-content] render-topics failed (attempt ${attempt}/3): ${formatErrorChain(err)}${willRetry ? ' — retrying' : ''}`);
          },
        }
      );
      log(`render-topics: ${rt.topicsChanged} changed, ${rt.topicsSkipped} skipped, ${rt.topicsErrored} errored of ${rt.topicsSeen} (${rt.durationMs} ms)`);
    } catch (err) {
      console.error(`[publish-content] render-topics failed permanently: ${formatErrorChain(err)}`);
      await abortSession({ baseUrl: opts.baseUrl, apiKey: opts.apiKey, sessionId: begin.sessionId, reason: 'render-topics failed' });
      process.exit(1);
    }
    // channels-hub Phase 2 — render per-channel detail pages alongside topics.
    // Same guard (prod-only, full-publish): POST /content/publish/render-channels
    // is not registered on srv-qa. Sequenced after render-topics, before commit.
    try {
      const rc = await withRetry(
        () => renderChannelsPhase({ baseUrl: opts.baseUrl, apiKey: opts.apiKey, sessionId: begin.sessionId }),
        {
          attempts: 3, backoffMs: [1000, 3000, 9000],
          onAttemptFail: (attempt, err, willRetry) => {
            console.error(`[publish-content] render-channels failed (attempt ${attempt}/3): ${formatErrorChain(err)}${willRetry ? ' — retrying' : ''}`);
          },
        }
      );
      log(`render-channels: ${rc.channelsChanged} changed, ${rc.channelsSkipped} skipped, ${rc.channelsErrored} errored of ${rc.channelsSeen} (${rc.durationMs} ms)`);
    } catch (err) {
      console.error(`[publish-content] render-channels failed permanently: ${formatErrorChain(err)}`);
      await abortSession({ baseUrl: opts.baseUrl, apiKey: opts.apiKey, sessionId: begin.sessionId, reason: 'render-channels failed' });
      process.exit(1);
    }
  }

  let commit;
  try {
    commit = await withRetry(
      () => commitSession({ baseUrl: opts.baseUrl, apiKey: opts.apiKey, sessionId: begin.sessionId, allowRevertSlugs, pipelineToken: localPipelineToken, conceptPhaseToken: localConceptPhaseToken }),
      {
        // Widened from [1000,3000,9000]/3 attempts: the old schedule only ever
        // waited 1s then 3s (~4s total window) — too short to ride out a transient
        // gorouter 502/503 blip on the single srv-qa instance (the commit is the
        // longest single request in the publish). ±20% jitter de-syncs retries
        // across the three DevRel projects. 502/503/504 are already classified
        // transient in publish-retry.ts.
        attempts: 5, backoffMs: [2000, 5000, 10000, 20000], jitterRatio: 0.2,
        onAttemptFail: (attempt, err, willRetry) => {
          console.error(`[publish-content] commit failed (attempt ${attempt}/5): ${formatErrorChain(err)}${willRetry ? ' — retrying' : ''}`);
        },
      }
    );
  } catch (err) {
    console.error(`[publish-content] commit failed permanently: ${formatErrorChain(err)}`);
    // Release the server-side publish lock + mark the manifest FAILED instead of
    // stranding it for the 30-min TTL (which 409s every QA rebuild in that window).
    // Mirrors the append-failure path; abort gets its own transient retry since the
    // 502/503 that killed the commit is usually a brief blip that has cleared by now.
    // If abort still can't reach the server, the stuck-manifest reaper is the backstop.
    try {
      await withRetry(
        () => abortSession({ baseUrl: opts.baseUrl, apiKey: opts.apiKey, sessionId: begin.sessionId, reason: 'commit failed' }),
        { attempts: 4, backoffMs: [1000, 3000, 6000], jitterRatio: 0.2 }
      );
      console.error('[publish-content] session aborted — publish lock released');
    } catch (abortErr) {
      console.error(`[publish-content] abort after commit failure also failed — manifest left for GC reaper: ${formatErrorChain(abortErr)}`);
    }
    process.exit(1);
  }

  const totalMs = Date.now() - startTime;
  console.log(`Published successfully:
  Version:    ${commit.version}
  Files:      ${commit.fileCount}
  Size:       ${(commit.totalSizeBytes / 1024 / 1024).toFixed(1)} MB
  Server:     ${commit.durationMs} ms
  Total:      ${totalMs} ms
  Idempotent retry hit?  ${commit.alreadyActive}`);

  // #672 — surface the guard outcome explicitly so a "Verify FAILED" isn't
  // mistaken for a store failure when it's actually a deliberate revert-block.
  if (commit.rejectedReverts?.length) {
    console.warn(`  ⚠ ${commit.rejectedReverts.length} slug(s) rejected by the #672 no-revert guard (prior content kept): ${commit.rejectedReverts.join(', ')}`);
    console.warn(`    Not updated. If reverting to this content is intentional, re-run: npm run publish-content -- --slug <slug> --allow-revert`);
  }
  if (commit.allowedReverts?.length) {
    console.log(`  ✓ ${commit.allowedReverts.length} operator-approved revert(s) committed via --allow-revert: ${commit.allowedReverts.join(', ')}`);
  }

  // --- code-check spec publish (non-fatal auxiliary step) ---
  try {
    const cacheDir = channel === 'qa'
      ? join(process.cwd(), '.tutorial-cache-qa')
      : join(process.cwd(), '.tutorial-cache');
    const specs = collectCodeCheckSpecs(cacheDir);
    if (specs.length) {
      log(`Publishing ${specs.length} code-check spec(s) to /content/code-check-specs`);
      const result = await withRetry(
        () => publishCodeCheckSpecs(opts.baseUrl, opts.apiKey, specs),
        {
          attempts: 3, backoffMs: [1000, 3000],
          onAttemptFail: (attempt, err, willRetry) => {
            console.error(`[publish-content] code-check spec publish failed (attempt ${attempt}/3): ${formatErrorChain(err)}${willRetry ? ' — retrying' : ''}`);
          },
        }
      );
      log(`code-check specs upserted=${result.upserted} skipped=${result.skipped.length}`);
    }
  } catch (err) {
    console.error('[publish-content] code-check spec publish failed (non-fatal):', formatErrorChain(err));
    // Do NOT exit non-zero — content publish is the critical path; specs are auxiliary.
  }

  // --- assert spec publish (non-fatal auxiliary step, issue #2245) ---
  try {
    const cacheDir = channel === 'qa'
      ? join(process.cwd(), '.tutorial-cache-qa')
      : join(process.cwd(), '.tutorial-cache');
    const specs = collectAssertSpecs(cacheDir);
    if (specs.length) {
      log(`Publishing ${specs.length} assert spec(s) to /content/assert-specs`);
      const result = await withRetry(
        () => publishAssertSpecs(opts.baseUrl, opts.apiKey, specs),
        {
          attempts: 3, backoffMs: [1000, 3000],
          onAttemptFail: (attempt, err, willRetry) => {
            console.error(`[publish-content] assert spec publish failed (attempt ${attempt}/3): ${formatErrorChain(err)}${willRetry ? ' — retrying' : ''}`);
          },
        }
      );
      log(`assert specs upserted=${result.upserted} skipped=${result.skipped.length}`);
    }
  } catch (err) {
    console.error('[publish-content] assert spec publish failed (non-fatal):', formatErrorChain(err));
    // Do NOT exit non-zero — content publish is the critical path; specs are auxiliary.
  }

  // --- validate-answer spec publish (non-fatal auxiliary step, issue #209 Task 9) ---
  // QA channel skips this entirely (#1375): srv-qa has NO runtime reader of
  // ValidateAnswerSpecs — the author-preview renderer re-parses rules.vr live
  // from the POSTed markdown, and there is no /api/validate-answer route on
  // srv-qa. The QA CDS model (com.sap.developers.ims.qa) doesn't even define
  // the entity, so every POST 500'd. Persisting these specs on QA was
  // write-only dead weight; publishing them only makes sense on prod.
  if (channel === 'qa') {
    log('[validate-answer] skipped (channel=qa — no runtime reader on srv-qa, #1375)');
  } else {
    try {
      const cacheDir = join(process.cwd(), '.tutorial-cache');
      const veResult = await publishValidateAnswerSpecs({
        cacheDir,
        baseUrl: opts.baseUrl,
        apiKey: opts.apiKey,
      });
      log(`[validate-answer] published ${veResult.published} specs, ${veResult.failures.length} failures`);
      for (const f of veResult.failures) {
        console.warn(`[validate-answer]   - ${f.slug}: ${f.status} ${f.body.slice(0, 200)}`);
      }
      // Don't process.exit(1) on failures — non-fatal per spec.
    } catch (err) {
      console.error('[publish-content] validate-answer spec publish failed (non-fatal):', formatErrorChain(err));
    }
  }

  // --- challenge-answers sidecar publish (non-fatal auxiliary step, #2441) ---
  // Uploads challenge-widget freeText reference answers. QA channel skips for
  // the same reason as validate-answer (#1375): srv-qa has no ChallengeAnswers
  // entity or /api/challenge-grade route, so every POST would 500.
  if (channel === 'qa') {
    log('[challenge-answers] skipped (channel=qa — no runtime reader on srv-qa)');
  } else {
    try {
      const cacheDir = join(process.cwd(), '.tutorial-cache');
      const chResult = await publishChallengeAnswers({
        cacheDir,
        baseUrl: opts.baseUrl,
        apiKey: opts.apiKey,
      });
      log(`[challenge-answers] published ${chResult.published} sidecars, ${chResult.failures.length} failures`);
      for (const f of chResult.failures) {
        console.warn(`[challenge-answers]   - ${f.slug}: ${f.status} ${f.body.slice(0, 200)}`);
      }
      // Don't process.exit(1) on failures — non-fatal.
    } catch (err) {
      console.error('[publish-content] challenge-answers publish failed (non-fatal):', formatErrorChain(err));
    }
  }

  // --- contributors sidecar publish (non-fatal auxiliary step, issue #WS2) ---
  // QA channel skips: srv-qa has no ContributorCache entity, POST would 404/500.
  if (channel === 'qa') {
    log('[publish-contributors] skipped (channel=qa)');
  } else {
    try {
      const cacheDir = join(process.cwd(), '.tutorial-cache');
      // #2462 — in delta (slug-targeted) mode, publish only the changed slugs'
      // sidecars instead of walking the whole cache (~O(catalog) sequential
      // POSTs). force/heal keep the full-cache walk (slugs omitted).
      const r = await publishContributors({
        cacheDir, baseUrl: opts.baseUrl, apiKey: opts.apiKey,
        ...(mode === 'delta' ? { slugs: targetSlugs } : {}),
      });
      log(`[publish-contributors] published ${r.published}/${r.total} (${r.skipped} unchanged)`);
    } catch (err) {
      console.error('[publish-content] contributors publish failed (non-fatal):', formatErrorChain(err));
    }
  }

  // --- validation-rules sidecar publish (non-fatal auxiliary step, issue #WS3) ---
  // QA channel skips: srv-qa has no ValidationRules entity, POST would 404/500.
  if (channel === 'qa') {
    log('[publish-validation-rules] skipped (channel=qa)');
  } else {
    try {
      const cacheDir = join(process.cwd(), '.tutorial-cache');
      // #2462 — same slug-targeted filter as contributors. Most changed slugs
      // have no rules sidecar, so a delta publish is typically zero POSTs here.
      const r = await publishValidationRules({
        cacheDir, baseUrl: opts.baseUrl, apiKey: opts.apiKey,
        ...(mode === 'delta' ? { slugs: targetSlugs } : {}),
      });
      log(`[publish-validation-rules] published ${r.published}/${r.total} (${r.skipped} unchanged)`);
    } catch (err) {
      console.error('[publish-content] validation-rules publish failed (non-fatal):', formatErrorChain(err));
    }
  }

  // --- auto-verify ---
  log('Verifying server state matches local...');
  let postRemote: Record<string, string>;
  try { postRemote = await fetchRemoteHashes({ baseUrl: opts.baseUrl, apiKey: opts.apiKey }).then(r => r.hashes); }
  catch (err) {
    console.error(`Auto-verify warning: cannot reach /content/hashes after commit: ${formatErrorChain(err)}`);
    process.exit(0); // commit was successful; don't punish for a transient verify-fetch error
  }
  const verifyDiff = computeDiff(localHashes, postRemote);
  // #1668 — a slug the #672 no-revert guard rejected still carries its prior
  // content on the server, so its local (revert) hash won't match here. That's
  // the guard doing its job, NOT a store failure. Split those out so we don't
  // fold them into an alarming "Verify FAILED" (they were already surfaced
  // above as a warning), and reserve exit 2 for genuine mismatches.
  const { genuine: verifyGenuine, expectedReverts: verifyExpectedReverts } =
    partitionVerifyMismatches({ verifyDiff, rejectedReverts: commit.rejectedReverts });
  if (verifyExpectedReverts.length) {
    console.warn(
      `Verify: ${verifyExpectedReverts.length} slug(s) still differ because the #672 no-revert guard ` +
      `kept prior content (expected, not a failure): ${verifyExpectedReverts.slice(0, 50).sort().join(', ')}`
    );
  }
  if (verifyGenuine.length === 0) {
    const matched = localHashes.size - verifyExpectedReverts.length;
    console.log(
      `Verify OK: ${matched} slugs match server` +
      (verifyExpectedReverts.length ? ` (${verifyExpectedReverts.length} intentionally kept by the no-revert guard)` : '') +
      '.'
    );
    process.exit(0);
  }
  console.error(`Verify FAILED: commit reported success but ${verifyGenuine.length} slugs still differ:`);
  for (const s of verifyGenuine.slice(0, 50).sort()) console.error(`  - ${s}`);
  process.exit(2);
}

// Run CLI when executed directly
const isMain = process.argv[1]?.includes('publish-content');
if (isMain) {
  main().catch(err => {
    console.error('Fatal:', err instanceof Error ? err.message : String(err));
    process.exit(1);
  });
}