#!/usr/bin/env tsx
// `archilyzer` — the one command line over the publish layer and the bins.
//
//   pnpm --filter yt-dlp-transcript-common exec tsx bin/archilyzer.ts <command>
//   (or `tsx ../common/bin/archilyzer.ts …` from export/, as its scripts do)
//
// Every row imports its implementation LAZILY, so `archilyzer sync tick` never
// loads the AWS SDK and `archilyzer settings example` never opens LMDB. The
// machinery (parser, lookup, usage) is `_cli.ts`; this file is only the table.

import type { Command } from "./_cli";
import { runCli, runIfEntryPoint } from "./_cli";

export const COMMANDS: Command[] = [
  {
    path: ["index"],
    usage: "rebuild the LMDB transcript index",
    run: async () => {
      await (await import("./build-index")).main();
      return 0;
    },
  },
  {
    path: ["build", "stats"],
    usage: "rebuild the stats datasets (reads the index; the data phase's second step)",
    run: async () => {
      await (await import("./build-stats")).main();
      return 0;
    },
  },
  {
    path: ["build", "templates"],
    usage: "bake each site's chart templates into its export staging dir (the data phase's third step)",
    run: async () => {
      await (await import("./build-chart-templates")).main();
      return 0;
    },
  },
  {
    path: ["build", "archives"],
    usage: "warm the shared archive-zip cache for every enabled site's channels, once",
    run: async () => {
      await (await import("./build-archives")).main();
      return 0;
    },
  },
  {
    path: ["compose", "site"],
    usage:
      "<id> [--allow-missing-media]  compose one site's export/public (default: SITE_ID); --allow-missing-media lets a report citation with no prepared media through",
    flags: { "allow-missing-media": "boolean" },
    maxPositionals: 1,
    run: async ({ positionals, flags, env }) => {
      const siteId = siteIdFrom(positionals, env, "compose site");
      if (!siteId) return 2;
      await (await import("./compose-site")).main({
        siteId,
        allowMissingMedia: flags["allow-missing-media"] === true,
      });
      return 0;
    },
  },
  {
    path: ["compose", "hub"],
    usage: "compose the hub's export/public (hub-sites.json, corpus.json, …)",
    run: async () => {
      await (await import("./compose-hub")).main();
      return 0;
    },
  },
  {
    path: ["compose", "homepage"],
    usage: "compose homepage/public (whole-pool stats + landing summary)",
    run: async () => {
      await (await import("./compose-homepage")).main();
      return 0;
    },
  },
  // --- publishing as stages (release 18; bin/publish.ts) ----------------------
  {
    path: ["publish", "index"],
    usage:
      "update the index: the LMDB index, the stats datasets and the chart templates in one child (8 GB heap), then the index stamp every build reads",
    run: async () => (await import("./publish")).publishIndex(),
  },
  {
    path: ["publish", "build"],
    usage:
      "<id|all> [--runner local|docker|auto] [--force] [--skip-archives] [--allow-missing-media] [--out <dir>]  build a site (or every stale one) into its bundle <exportBuildsDir>/<id>/out from the current index; --runner docker builds every site in containers (host only); a fresh site is a no-op without --force; --allow-missing-media lets a report citation with no prepared media through compose; --out <dir> then lays the site's bundle out in <dir> for a server that is not Pages (hard links where it can, else copies; emptied first and guarded as a local deploy's destination; not a deploy, nothing recorded)",
    flags: {
      runner: "string",
      force: "boolean",
      "skip-archives": "boolean",
      "allow-missing-media": "boolean",
      out: "string",
    },
    maxPositionals: 1,
    run: async ({ positionals, flags }) => {
      const [target] = positionals;
      const runner = flags.runner;
      if (!target || (runner !== undefined && runner !== "local" && runner !== "docker" && runner !== "auto")) {
        console.error("publish build: give <id|all> [--runner local|docker|auto]");
        return 2;
      }
      if (flags.out !== undefined && (typeof flags.out !== "string" || !flags.out.trim())) {
        console.error("publish build: --out needs a directory");
        return 2;
      }
      return (await import("./publish")).publishBuild({
        target,
        runner: runner as "local" | "docker" | "auto" | undefined,
        force: flags.force === true,
        skipArchives: flags["skip-archives"] === true,
        allowMissingMedia: flags["allow-missing-media"] === true,
        ...(typeof flags.out === "string" ? { out: flags.out } : {}),
      });
    },
  },
  {
    path: ["publish", "deploy"],
    usage:
      "<id|all> [--preview <branch>] [--to local] [--force]  ship a site's bundle to its Pages project (a preview with --preview), or with --to local into ARCHILYZER_SITE_OUT; a bundle already deployed there is a no-op without --force",
    flags: { preview: "string", to: "string", force: "boolean" },
    maxPositionals: 1,
    run: async ({ positionals, flags }) => {
      const [target] = positionals;
      const to = flags.to;
      if (!target || (to !== undefined && to !== "pages" && to !== "local")) {
        console.error("publish deploy: give <id|all> [--preview <branch>] [--to local]");
        return 2;
      }
      return (await import("./publish")).publishDeploy({
        target,
        preview: typeof flags.preview === "string" ? flags.preview : undefined,
        to: to as "pages" | "local" | undefined,
        force: flags.force === true,
      });
    },
  },
  {
    path: ["publish", "hub"],
    usage:
      "[--deploy | --deploy-only] [--preview <branch>] [--force]  build the hub into its bundle <exportBuildsDir>/_hub/out, then (--deploy) ship it; --deploy-only ships the bundle as built",
    flags: { deploy: "boolean", "deploy-only": "boolean", preview: "string", force: "boolean" },
    run: async ({ flags }) =>
      (await import("./publish")).publishHub({
        deploy: flags.deploy === true,
        deployOnly: flags["deploy-only"] === true,
        preview: typeof flags.preview === "string" ? flags.preview : undefined,
        force: flags.force === true,
      }),
  },
  {
    path: ["publish", "homepage"],
    usage:
      "[--deploy | --deploy-only] [--preview <branch>] [--to local] [--force]  build homepage/out (source mirror included), then (--deploy) ship it; --deploy-only ships it as built",
    flags: { deploy: "boolean", "deploy-only": "boolean", preview: "string", to: "string", force: "boolean" },
    run: async ({ flags }) => {
      const to = flags.to;
      if (to !== undefined && to !== "pages" && to !== "local") {
        console.error("publish homepage: --to is pages or local");
        return 2;
      }
      return (await import("./publish")).publishHomepage({
        deploy: flags.deploy === true,
        deployOnly: flags["deploy-only"] === true,
        preview: typeof flags.preview === "string" ? flags.preview : undefined,
        to: to as "pages" | "local" | undefined,
        force: flags.force === true,
      });
    },
  },
  // `publish status` and `publish now` read the publish state view (release 18
  // S3; bin/publishNow.ts).
  {
    path: ["publish", "status"],
    usage:
      "[--json]  the publish status: the index, the lane, and per site / hub / homepage its policy and its built, deployed and live chips, then the plan Publish now would run",
    flags: { json: "boolean" },
    run: async ({ flags }) => (await import("./publishNow")).publishStatusRow({ json: flags.json === true }),
  },
  {
    path: ["publish", "now"],
    usage:
      "run what Publish now runs — the index update when it is stale, then each policy target's build and deploy (site.json publish.auto; settings.json publish.hub / publish.homepage), never forced — one stage at a time IN THIS PROCESS under the publish lock, as the editor's queue would (the CLI has no queue); exit 0 when every stage ran or was a no-op",
    run: async () => (await import("./publishNow")).publishNow(),
  },
  {
    path: ["stage"],
    usage:
      "<kind> <target> --run-id <id> [--preview <b>] [--to local] [--runner docker] [--force] [--skip-archives] [--allow-missing-media] [--index-after <ms>] [--built-after <ms>]  INTERNAL: one publish stage, as the editor's job runs it (exit 0 ran/no-op, 1 failed, 2 usage, 3 precondition not met, 130 cancelled)",
    // publish/stages.ts STAGE_FLAGS, spelled out so this table stays free of
    // imports (_cli.test.ts holds the two equal).
    flags: {
      "run-id": "string",
      preview: "string",
      to: "string",
      runner: "string",
      force: "boolean",
      "skip-archives": "boolean",
      "allow-missing-media": "boolean",
      "index-after": "string",
      "built-after": "string",
    },
    maxPositionals: 2,
    run: async (ctx) => (await import("./publish")).stageRow(ctx),
  },
  // The rows the stages replaced, kept as printed aliases.
  {
    path: ["build", "site"],
    usage:
      "<id> [--nodata] [--skip-archives] [--allow-missing-media]  alias: publish index (not with --nodata) + publish build <id> --force (default id: SITE_ID)",
    flags: { nodata: "boolean", "skip-archives": "boolean", "allow-missing-media": "boolean" },
    maxPositionals: 1,
    run: async ({ positionals, flags, env }) => {
      const siteId = siteIdFrom(positionals, env, "build site");
      if (!siteId) return 2;
      return (await import("./publish")).buildSiteAlias({
        siteId,
        nodata: flags.nodata === true,
        skipArchives: flags["skip-archives"] === true,
        allowMissingMedia: flags["allow-missing-media"] === true,
      });
    },
  },
  {
    path: ["build", "all"],
    usage:
      "[--skip-archives]  alias: publish index + publish build all --runner auto (containers when an engine answers, else serially on the host)",
    flags: { "skip-archives": "boolean" },
    run: async ({ flags }) =>
      (await import("./publish")).buildAllAlias({ skipArchives: flags["skip-archives"] === true }),
  },
  {
    path: ["build", "hub"],
    // Kept RAW (export's `build:hub`, which e2e:2origin runs — an alias of
    // `publish index` would index whatever corpus is visible). Unstamped:
    // `deploy hub` ships the bundle `publish hub` builds, never this.
    usage:
      "compose:hub + INSTANCE_MODE=hub next build into export/out — a raw build, unstamped; to deploy the hub build it with `publish hub`",
    run: async () => {
      const { buildHub } = await import("../publish/build");
      const code = await buildHub({ signal: interrupted() });
      if (code !== 0) console.error(`build hub: failed (exit ${code})`);
      return code;
    },
  },
  {
    path: ["build", "homepage"],
    usage:
      "[--no-source]  compose + source publish + next build in homepage/ (reads the index as it stands); --no-source removes the published source instead",
    flags: { "no-source": "boolean" },
    run: async ({ flags }) => {
      const { buildHomepage } = await import("../publish/build");
      const code = await buildHomepage({
        signal: interrupted(),
        skipSource: flags["no-source"] === true,
      });
      if (code !== 0) console.error(`build homepage: failed (exit ${code})`);
      return code;
    },
  },
  {
    path: ["reports", "prepare"],
    usage:
      "<id>  cut every clip and copy every post capture the site's published reports cite into its report-media cache, before its build, then export the reports as files (reports export) when nothing is missing (exit 1 when a citation lacks media or an export fails; default id: SITE_ID)",
    maxPositionals: 1,
    run: async ({ positionals, env }) => {
      const siteId = siteIdFrom(positionals, env, "reports prepare");
      if (!siteId) return 2;
      return (await import("./reports-prepare")).main({ siteId, signal: interrupted() });
    },
  },
  {
    path: ["reports", "export"],
    usage:
      "<id> [--report <reportId>] [--formats html,pdf,md,slides,slides-pdf,zip] [--allow-missing-media]  write the site's published reports as files (report.html, report.pdf, report.md, slides.html, slides.pdf, evidence-pack.zip) into its report-exports staging, where compose publishes them from (exit 1 on a problem; a PDF skipped for want of a browser is a note; default id: SITE_ID)",
    flags: { report: "string", formats: "string", "allow-missing-media": "boolean" },
    maxPositionals: 1,
    run: async ({ positionals, flags, env }) => {
      const siteId = siteIdFrom(positionals, env, "reports export");
      if (!siteId) return 2;
      const { parseReportExportFormats } = await import("../publish/reportExports");
      const formats = typeof flags.formats === "string" ? parseReportExportFormats(flags.formats) : undefined;
      if (formats === null) {
        console.error("reports export: --formats is a comma-separated list of html, pdf, md, zip");
        return 2;
      }
      return (await import("./reports-export")).main({
        siteId,
        signal: interrupted(),
        ...(typeof flags.report === "string" ? { reportId: flags.report } : {}),
        ...(formats ? { formats } : {}),
        allowMissingMedia: flags["allow-missing-media"] === true,
      });
    },
  },
  {
    path: ["reports", "check"],
    usage:
      "<id> [--reports <a,b>] [--allow-missing-media]  what compose would say about the site's reports, with no build: each report validated, every cited quote checked against its record, every cited moment's prepared media present and current, the report video under the publish limit (exit 1 with the list; --reports checks those, drafts included; default id: SITE_ID)",
    flags: { reports: "string", "allow-missing-media": "boolean" },
    maxPositionals: 1,
    run: async ({ positionals, flags, env }) => {
      const siteId = siteIdFrom(positionals, env, "reports check");
      if (!siteId) return 2;
      const reports =
        typeof flags.reports === "string"
          ? flags.reports.split(",").map((r) => r.trim()).filter(Boolean)
          : undefined;
      return (await import("./reports-check")).checkMain({
        siteId,
        ...(reports ? { reports } : {}),
        allowMissingMedia: flags["allow-missing-media"] === true,
      });
    },
  },
  {
    path: ["reports", "verify-quotes"],
    usage:
      "<report.json> [--json]  every video, audio and post quote of one report against its record with compose's own check: the best score and track, and the en-orig track's score where the record has one — a quote that matches a served `en` rewrite and not en-orig is reported (exit 1 when any quote drifted)",
    flags: { json: "boolean" },
    maxPositionals: 1,
    run: async ({ positionals, flags }) => {
      const [file] = positionals;
      if (!file) {
        console.error("reports verify-quotes: give <report.json>");
        return 2;
      }
      return (await import("./reports-check")).verifyQuotesMain({ file, json: flags.json === true });
    },
  },
  {
    path: ["reports", "attach-video"],
    usage:
      "<report.json> <video> [--poster <image>] [--caption <line>]  the report's video: remuxed (an H.264 mp4 under the limit) or encoded to fit the 24 MiB publish limit, written beside report.json as video.mp4 with a poster (given, kept, or a frame of the video), and `video` set in report.json",
    flags: { poster: "string", caption: "string" },
    maxPositionals: 2,
    run: async ({ positionals, flags }) => {
      const [reportFile, video] = positionals;
      if (!reportFile || !video) {
        console.error("reports attach-video: give <report.json> <video>");
        return 2;
      }
      return (await import("./reports-attach-video")).attachVideoMain({
        reportFile,
        video,
        ...(typeof flags.poster === "string" ? { poster: flags.poster } : {}),
        ...(typeof flags.caption === "string" ? { caption: flags.caption } : {}),
      });
    },
  },
  {
    path: ["reports", "convert"],
    usage:
      "<sweep|ask|manifest> <in> --out <report.json> [--channels-dir <dir>] [--id <id>] [--title <title>]  a /sweep report (markdown), an /ask answer or a report-to-video manifest as a report.json, written only when it validates (--channels-dir: widen spans from the cues, find posts' channels)",
    flags: { out: "string", "channels-dir": "string", id: "string", title: "string" },
    maxPositionals: 2,
    run: async ({ positionals, flags }) => {
      const [from, input] = positionals;
      const { convertMain, isConvertFrom, CONVERT_FROM } = await import("./reports-convert");
      if (!isConvertFrom(from) || !input || typeof flags.out !== "string") {
        console.error(`reports convert: give <${CONVERT_FROM.join("|")}> <in> --out <report.json>`);
        return 2;
      }
      return convertMain({
        from,
        input,
        out: flags.out,
        ...(typeof flags["channels-dir"] === "string" ? { channelsDir: flags["channels-dir"] } : {}),
        ...(typeof flags.id === "string" ? { id: flags.id } : {}),
        ...(typeof flags.title === "string" ? { title: flags.title } : {}),
      });
    },
  },
  {
    path: ["reports", "to-manifest"],
    usage:
      "<report.json> --out <manifest.json> [--channels-dir <dir>] [--site-origin <url>]  a starter report-to-video manifest from a report (a chapter card per section, a claim's still and clips stamped with its verdict, its posts)",
    flags: { out: "string", "channels-dir": "string", "site-origin": "string" },
    maxPositionals: 1,
    run: async ({ positionals, flags }) => {
      const [input] = positionals;
      if (!input || typeof flags.out !== "string") {
        console.error("reports to-manifest: give <report.json> --out <manifest.json>");
        return 2;
      }
      const { toManifestMain } = await import("./reports-convert");
      return toManifestMain({
        input,
        out: flags.out,
        ...(typeof flags["channels-dir"] === "string" ? { channelsDir: flags["channels-dir"] } : {}),
        ...(typeof flags["site-origin"] === "string" ? { siteOrigin: flags["site-origin"] } : {}),
      });
    },
  },
  {
    path: ["source", "publish"],
    usage:
      "[--force] [--check] [--keep-scratch]  the scrubbed git mirror, raw tree, history pages (stagit, when installed) and tarball into homepage/public, behind the denied-literal gate (--check: audit and count, write nothing)",
    flags: { force: "boolean", check: "boolean", "keep-scratch": "boolean" },
    run: async ({ flags }) => {
      const { publishSource } = await import("../publish/source");
      return publishSource({
        signal: interrupted(),
        force: flags.force === true,
        check: flags.check === true,
        keepScratch: flags["keep-scratch"] === true,
      });
    },
  },
  {
    path: ["source", "audit"],
    usage:
      "[<git dir>]  the denied-literal gate (+ gitleaks) over a git dir; default the published homepage/public/source/archilyzer.git",
    maxPositionals: 1,
    run: async ({ positionals }) => {
      const { auditSource } = await import("../publish/source");
      return auditSource({ signal: interrupted(), gitDir: positionals[0] });
    },
  },
  {
    path: ["deploy", "site"],
    usage:
      "<id> [--preview <branch>]  alias: publish deploy <id> [--preview <branch>] — ship the site's bundle to its Pages project (default id: SITE_ID)",
    flags: { preview: "string" },
    maxPositionals: 1,
    run: async ({ positionals, flags, env }) => {
      const siteId = siteIdFrom(positionals, env, "deploy site");
      if (!siteId) return 2;
      return (await import("./publish")).deploySiteAlias({
        siteId,
        preview: typeof flags.preview === "string" ? flags.preview : undefined,
      });
    },
  },
  {
    path: ["deploy", "hub"],
    usage:
      "[--preview <branch>]  alias: publish hub --deploy-only [--preview <branch>] — ship the hub's bundle to homepage.json's Pages project",
    flags: { preview: "string" },
    run: async ({ flags }) =>
      (await import("./publish")).deployHubAlias({
        preview: typeof flags.preview === "string" ? flags.preview : undefined,
      }),
  },
  {
    path: ["deploy", "homepage"],
    usage:
      "[--preview <branch>]  alias: publish homepage --deploy-only [--preview <branch>] — ship homepage/out to the Pages project archilyzer",
    flags: { preview: "string" },
    run: async ({ flags }) =>
      (await import("./publish")).deployHomepageAlias({
        preview: typeof flags.preview === "string" ? flags.preview : undefined,
      }),
  },
  {
    path: ["run"],
    usage:
      "<operation> <channel> [ids…] [--lane local|remote]  run one catalogued operation over a channel offline, as the editor's job does (sync, downloads and transcription are refused: they run in the editor; it does not see the editor's lanes, so not beside one on the same channel)",
    flags: { lane: "string" },
    maxPositionals: Number.MAX_SAFE_INTEGER,
    run: async ({ positionals, flags }) => {
      const [operation, channel, ...ids] = positionals;
      if (!operation || !channel) {
        console.error("run: which operation, over which channel? `archilyzer run <operation> <channel> [ids…]`");
        return 2;
      }
      const lane = flags.lane;
      if (lane !== undefined && lane !== "local" && lane !== "remote") {
        console.error(`run: --lane is local or remote, not "${String(lane)}"`);
        return 2;
      }
      const { runOperation } = await import("./run-operation");
      return runOperation(
        { operation, channel, ids, lane: lane as "local" | "remote" | undefined },
        { signal: interrupted() },
      );
    },
  },
  {
    path: ["archive-org", "refresh"],
    usage:
      "<slug> [--dry-run]  bring a channel's archive.org file records up to their provenance: a name-only mirror's title (where the item gives the file none) and upload date from its file name; offline, through the metadata history; prints old → new",
    flags: { "dry-run": "boolean" },
    maxPositionals: 1,
    run: async ({ positionals, flags }) => {
      const [slug] = positionals;
      if (!slug) {
        console.error("archive-org refresh: which channel? Pass its slug.");
        return 2;
      }
      return (await import("./archive-org-refresh")).main({
        slug,
        dryRun: flags["dry-run"] === true,
      });
    },
  },
  {
    path: ["wayback", "refresh"],
    usage:
      "<slug> [--titles <json>] [--dry-run]  bring a channel's Wayback Machine copies up to the Wayback rules: wayback.json (original URL, capture time), the dir renamed to its canonical id through the snapshot's reconcile (roster moved with it), and with --titles (a file of id → {title, upload_date}) a raw file's title and date; offline, skips a record a live job holds; prints old → new",
    flags: { titles: "string", "dry-run": "boolean" },
    maxPositionals: 1,
    run: async ({ positionals, flags }) => {
      const [slug] = positionals;
      if (!slug) {
        console.error("wayback refresh: which channel? Pass its slug.");
        return 2;
      }
      return (await import("./wayback-refresh")).main({
        slug,
        dryRun: flags["dry-run"] === true,
        ...(typeof flags.titles === "string" ? { titlesFile: flags.titles } : {}),
      });
    },
  },
  {
    path: ["feeds", "backfill-metadata"],
    usage:
      "<slug> [--feed <url>] [--dry-run]  complete a podcast channel's records (title, date, description, duration) from its RSS feed: one fetch of the feed (default: the channel's url), no media; --dry-run counts matched / unmatched / already complete and writes nothing",
    flags: { feed: "string", "dry-run": "boolean" },
    maxPositionals: 1,
    run: async ({ positionals, flags }) => {
      const [slug] = positionals;
      if (!slug) {
        console.error("feeds backfill-metadata: which channel? Pass its slug.");
        return 2;
      }
      return (await import("./feeds-backfill-metadata")).main({
        slug,
        ...(typeof flags.feed === "string" ? { feedUrl: flags.feed } : {}),
        dryRun: flags["dry-run"] === true,
        signal: interrupted(),
      });
    },
  },
  {
    path: ["media", "attach"],
    usage:
      "<slug> <source> [--items <json|@file>] [--match <regex>] [--create-records] [--replace] [--dry-run]  give a channel's held videos their media from a LOCAL archive (a directory, a .zip read in place, a .7z) into the saved-video store, provenance recorded (archive, entry, sha256); the id from the folder's \"(<id>)\" or the file's yt-dlp suffix; --create-records writes a record for a video not held; --dry-run lists each folder's class and writes nothing; offline, nothing fetched",
    flags: {
      items: "string",
      match: "string",
      "create-records": "boolean",
      replace: "boolean",
      "dry-run": "boolean",
    },
    maxPositionals: 2,
    run: async ({ positionals, flags }) => {
      const [slug, source] = positionals;
      if (!slug || !source) {
        console.error("media attach: which channel, from which archive? Pass <slug> <source>.");
        return 2;
      }
      return (await import("./media-attach")).main({
        slug,
        source,
        ...(typeof flags.items === "string" ? { items: flags.items } : {}),
        ...(typeof flags.match === "string" ? { match: flags.match } : {}),
        createRecords: flags["create-records"] === true,
        replace: flags.replace === true,
        dryRun: flags["dry-run"] === true,
        signal: interrupted(),
      });
    },
  },
  {
    path: ["media", "playable"],
    usage:
      "<slug> [--ids <a,b>] [--trackers <url,url>] [--root <dir>] [--dry-run]  remux a channel's saved containers losslessly (-c copy) into browser-playable mp4 (+faststart) or webm, one single-file torrent each (no web seed; --trackers is the announce list, outside the infohash), under playable/ beside the saved-video store; keyed by the source's sha256, so a re-run is a no-op; offline",
    flags: { ids: "string", trackers: "string", root: "string", "dry-run": "boolean" },
    maxPositionals: 1,
    run: async ({ positionals, flags }) => {
      const [slug] = positionals;
      if (!slug) {
        console.error("media playable: which channel? Pass its slug.");
        return 2;
      }
      return (await import("./media-playable")).main({
        slug,
        ...(typeof flags.ids === "string" ? { ids: flags.ids } : {}),
        ...(typeof flags.trackers === "string" ? { trackers: flags.trackers } : {}),
        ...(typeof flags.root === "string" ? { root: flags.root } : {}),
        dryRun: flags["dry-run"] === true,
        signal: interrupted(),
      });
    },
  },
  {
    path: ["seed"],
    usage:
      "the home seeder of last resort: seed the playable torrents of settings.seeder.sites, each only while no other seeder has it (standby otherwise, with hysteresis), TCP + WebRTC, no DHT; runs until interrupted — behind the VPN (docker compose profile `seeder`, docker-compose.seeder.yml)",
    run: async () => (await import("./seed")).seedMain({ signal: interrupted() }),
  },
  {
    path: ["tracker"],
    usage:
      "[--host 127.0.0.1] [--port 8000]  the self-hosted tracker (HTTP + WebSocket, no UDP) for the seeder's torrents only — any other infohash is refused; runs until interrupted",
    flags: { host: "string", port: "string" },
    run: async ({ flags }) => {
      const port = typeof flags.port === "string" ? Number(flags.port) : 8000;
      if (!Number.isInteger(port) || port < 0 || port > 65535) {
        console.error("tracker: --port must be a port number");
        return 2;
      }
      return (await import("./seed")).trackerMain({
        host: typeof flags.host === "string" ? flags.host : "127.0.0.1",
        port,
        signal: interrupted(),
      });
    },
  },
  // The bins that parse their own flags, run as children with their argv
  // verbatim (_spawnBin.ts says why). Each row is the whole integration.
  script(["duplicates"], "duplicate-shorts.ts",
    "[--threshold N] [--all-durations] [--blocking title|duration|both] [--near F] [--tolerance N] …  on-demand duplicate detection (after index + stats)", 8192),
  script(["posts", "fetch"], "fetch-posts.ts",
    "--slug <channel> [--full | --older [--floor YYYY-MM-DD] [--from YYYY-MM-DD] [--force]] [--limit N] [--pages N]  fetch a social channel's posts into its posts corpus (--older: walk back below the oldest archived post; --pages: a forum thread's latest N pages)"),
  {
    path: ["posts", "import-html"],
    usage:
      "<slug> <file-or-dir>… [--dry-run]  import forum thread pages saved from a browser (\"Save page as\", .html) into a forum-thread channel: new posts appended, edited ones updated, nothing fetched",
    flags: { "dry-run": "boolean" },
    maxPositionals: 1000,
    run: async ({ positionals, flags }) => {
      const [slug, ...inputs] = positionals;
      if (!slug || inputs.length === 0) {
        console.error("posts import-html: pass the channel slug, then one or more saved pages or directories.");
        return 2;
      }
      return (await import("./posts-import-html")).main({
        slug,
        inputs,
        dryRun: flags["dry-run"] === true,
      });
    },
  },
  script(["posts", "check"], "check-post-availability.ts",
    "--slug <channel> [--mode stale|unchecked|all] [--limit N]  which archived posts were deleted at the source"),
  script(["diarize", "backfill"], "diarize-backfill.ts",
    "[--dry-run] [--scope transcribed|channel:<slug>|video:<slug>/<id>] [--limit N] [--force] …  diarize videos whose audio is still on disk"),
  script(["digest", "plan"], "digest-plan.ts",
    "[--lane local|remote] [--channels a,b] [--top N] [--json] [--census] …  price the digest backfill; writes nothing"),
  script(["digest", "validate"], "digest-validate.ts",
    "<channel> [<channel> …]  score digests already on disk"),
  script(["reconcile", "video-dirs"], "reconcile-video-dirs.ts",
    "[--channel <slug>] [--dry-run] [--verbose]  rename video dirs to the canonical id layout"),
  script(["verify", "transcripts"], "verify-transcripts.ts",
    "--channel <slug>  list duplicate and missing transcripts"),
  script(["migrate", "channel-priority"], "migrate-channel-priority.ts",
    "[--dry-run]  the one-shot channel-priority migration (plans/channel-priority.md, S5)"),
  {
    path: ["storage", "report"],
    usage:
      "[<slug>…] [--json]  each channel's media (tierable), text and clip bytes and where its media is — off the reports, no drive touched; totals per place (the corpus disk's is what a move would free)",
    flags: { json: "boolean" },
    maxPositionals: 1000,
    run: async ({ positionals, flags }) =>
      (await import("./storage-report")).main({
        slugs: positionals,
        json: flags.json === true,
      }),
  },
  script(["storage", "migrate-tier"], "migrate-media-tier.ts",
    "<slug>…|--all [--order smallest] [--include-large] [--dry-run] [--reclaim]  bring a channel off the retired whole-directory layout onto the media tier, its text home to the corpus disk (editor stopped; --all stops before the three big-text channels)"),
  {
    path: ["brand", "media"],
    usage: "[--out <dir>] [--video-kit]  render the Archilyzer Media channel's assets",
    passthrough: true,
    run: async ({ argv }) => (await import("./brand-media")).main(argv),
  },
  {
    path: ["mcp"],
    usage:
      "[--local <dir>|--remote <url>|--hub <url>]  start the MCP server on stdio (as `pnpm --filter yt-dlp-transcript-mcp exec tsx src/index.ts`)",
    passthrough: true,
    run: async ({ argv }) => (await import("./mcp")).main(argv),
  },
  {
    path: ["sync", "tick"],
    usage: "POST one scheduler tick to the editor (SYNC_TICK_URL, SYNC_TICK_TOKEN)",
    run: async () => (await import("./sync-tick")).tick(),
  },
  {
    path: ["docs", "env"],
    usage: "[--check]  write ENVIRONMENT.md from the declared env-var list (lib/envVars.ts)",
    flags: { check: "boolean" },
    run: async ({ flags }) =>
      (await import("./env-docs")).main({ check: flags.check === true }),
  },
  {
    path: ["docs", "files"],
    usage: "[--check]  write SITE.md + CHANNEL.md + REPORT.md + CITATIONS.md from the file schemas",
    flags: { check: "boolean" },
    run: async ({ flags }) =>
      (await import("./file-schemas-docs")).main({ check: flags.check === true }),
  },
  {
    path: ["docs", "cli"],
    usage: "[--check]  write COMMANDS.md from this command table and `pnpm ops --help`",
    flags: { check: "boolean" },
    run: async ({ flags }) =>
      (await import("./cli-docs")).main({ check: flags.check === true }),
  },
  {
    path: ["settings", "example"],
    usage: "[--check]  write settings.json.example + SETTINGS.md from the schema",
    flags: { check: "boolean" },
    run: async ({ flags }) =>
      (await import("./settings-example")).main({ check: flags.check === true }),
  },
  {
    path: ["doctor"],
    usage:
      "[--json]  read-only report: node, the checkout, the corpus, settings, every tool, the port block; exit 1 on a failure",
    flags: { json: "boolean" },
    run: async ({ flags }) => (await import("./doctor")).main({ json: flags.json === true }),
  },
  // Release notes, cut locally: the same writer as the /sites and /changelog
  // form and POST /api/ops/cut-release, with no editor running (release.ts).
  {
    path: ["release", "show"],
    usage:
      "[editor|export]  latest release, its date, how many bullets wait under [Unreleased]",
    maxPositionals: 1,
    run: async (ctx) => (await import("./release")).showMain(ctx),
  },
  {
    path: ["release", "cut"],
    usage:
      "<editor|export|all> <X.Y.Z|next|next-minor> [--commit] [--date YYYY-MM-DD]  [Unreleased] -> a dated heading; all = both, one version, two commits",
    flags: { commit: "boolean", date: "string" },
    maxPositionals: 2,
    run: async (ctx) => (await import("./release")).cutMain(ctx),
  },
];

// A row for a bin that parses its own argv: a passthrough command that runs
// `common/bin/<file>` as a child with the words after its path.
function script(path: string[], file: string, usage: string, heapMb?: number): Command {
  return {
    path,
    usage,
    passthrough: true,
    run: async ({ argv }) => (await import("./_spawnBin")).runBinScript(file, argv, heapMb),
  };
}

// The site a site command names: its argument, else SITE_ID (which is how
// export's `build` / `deploy` scripts are called). Prints and returns null when
// there is neither.
function siteIdFrom(
  positionals: string[],
  env: NodeJS.ProcessEnv,
  name: string,
): string | null {
  const id = (positionals[0] ?? env.SITE_ID ?? "").trim();
  if (!id) {
    console.error(`${name}: which site? Pass its id, or set SITE_ID.`);
    return null;
  }
  return id;
}

// Ctrl-C cancels the step in flight the way the editor's Cancel does: the
// signal reaches the child, and the entry point stops before its next step.
function interrupted(): AbortSignal {
  const ac = new AbortController();
  process.once("SIGINT", () => ac.abort());
  process.once("SIGTERM", () => ac.abort());
  return ac.signal;
}

runIfEntryPoint(import.meta.url, () => runCli(COMMANDS, process.argv.slice(2)));