@jenga-ai/agent 3.0.0 → 3.1.1

package/scripts/build-pages-site.sh

@@ -0,0 +1,268 @@
+#!/usr/bin/env bash
+# scripts/build-pages-site.sh
+#
+# Deterministically (re)generates the wiki-derived pages of the GitHub Pages
+# documentation site (docs/*.md) from the existing wiki mirror under
+# project/.wiki/. This is the sync mechanism behind E41_S13_T01's
+# source-of-truth decision ("restructure from the wiki, keep both in sync"):
+# project/.wiki/ stays the canonical, doc-sync-maintained content; this
+# script is the deterministic transform from that content into the
+# multi-page, navigable Pages site.
+#
+# WHEN TO RE-RUN: after `j.doc-sync` (or any manual edit) updates
+# project/.wiki/documentation.md, project/.wiki/intro-guide.md, or
+# project/.wiki/concepts/*.md, re-run this script to refresh the Pages site
+# so it doesn't silently drift from the wiki the way README.md and the wiki
+# itself have drifted from each other before (see skills/doc-sync/SKILL.md
+# for the doc-sync side of this convention).
+#
+# WHAT THIS SCRIPT DOES NOT TOUCH:
+#   - docs/_config.yml, docs/index.md — hand-authored site structure/config,
+#     not derived from wiki content. Edit these directly if the page set or
+#     nav changes.
+#   - docs/README.md — maintainer-facing decision record, not a rendered
+#     Jekyll page and not wiki-derived content.
+#
+# WHAT THIS SCRIPT REGENERATES (always overwritten, never hand-edit these):
+#   - docs/getting-started.md   <- project/.wiki/intro-guide.md
+#   - docs/concepts.md          <- project/.wiki/concepts/*.md (concatenated)
+#   - docs/skills.md            <- project/.wiki/documentation.md "## Skills"
+#   - docs/agents.md            <- project/.wiki/documentation.md "## Agents"
+#   - docs/hooks.md             <- project/.wiki/documentation.md "## Hooks"
+#   - docs/mcp-tools.md         <- project/.wiki/documentation.md "## MCP Tools"
+#   - docs/reference.md         <- project/.wiki/documentation.md
+#                                   "## Directory Structure" +
+#                                   "## Agent Communication Contract"
+#                                   (plus a short hand-authored index blurb
+#                                   linking to skills/agents/hooks/mcp-tools)
+#
+# KNOWN LIMITATION: this is a structural transform, not a fact-checker. It
+# ports project/.wiki/documentation.md's content as-is, including whatever
+# is currently stale in that file (e.g. it documents ~30 skills under the
+# old bare `/<name>` invocation form and does not yet list every skill in
+# skills/, including the `j-<name>` twins — a pre-existing wiki staleness
+# gap, not something introduced by this script). Fixing the wiki's own
+# staleness is doc-sync's job, not this script's — this script only keeps
+# the Pages site faithful to whatever the wiki currently says.
+#
+# HEADING-STABILITY ASSUMPTION: section extraction below is keyed to exact
+# top-level ("## ") heading text in documentation.md (Agents, Skills, MCP
+# Tools, Hooks, Directory Structure, Agent Communication Contract). If any
+# of those headings are renamed, update the `case` statement in
+# extract_sections() to match.
+#
+# Usage: scripts/build-pages-site.sh
+# Safe to re-run any number of times — every run fully overwrites its
+# output files from the current wiki content (no partial/incremental state).
+
+set -euo pipefail
+
+# shellcheck source=lib/resolve-project-dir.sh disable=SC1091
+source "$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh"
+
+REPO_ROOT="$JENGA_PROJECT_DIR"
+WIKI_DIR="$REPO_ROOT/project/.wiki"
+DOCS_DIR="$REPO_ROOT/docs"
+DOC_MD="$WIKI_DIR/documentation.md"
+INTRO_MD="$WIKI_DIR/intro-guide.md"
+CONCEPTS_DIR="$WIKI_DIR/concepts"
+
+for f in "$DOC_MD" "$INTRO_MD"; do
+  if [ ! -f "$f" ]; then
+    echo "build-pages-site.sh: required source file not found: $f" >&2
+    exit 1
+  fi
+done
+if [ ! -d "$CONCEPTS_DIR" ]; then
+  echo "build-pages-site.sh: required source directory not found: $CONCEPTS_DIR" >&2
+  exit 1
+fi
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+# --- 1. Split documentation.md into per-section scratch files -------------
+# A line can only belong to one target section at a time; the generic
+# "any other ## heading" rule resets `section` to "" so unrelated top-level
+# sections (e.g. "## Table of Contents") are dropped rather than bleeding
+# into whichever named section preceded them.
+awk -v work="$WORK" '
+  /^## Agents$/                             { section = "agents"; next }
+  /^## Skills$/                             { section = "skills"; next }
+  /^## MCP Tools$/                          { section = "mcp-tools"; next }
+  /^## Hooks$/                              { section = "hooks"; next }
+  /^## Directory Structure$/                { section = "directory-structure"; next }
+  /^## Agent Communication Contract$/       { section = "contract"; next }
+  /^## /                                    { section = "" }
+  {
+    if (section != "") {
+      print >> (work "/section-" section ".md")
+    }
+  }
+' "$DOC_MD"
+
+for s in agents skills mcp-tools hooks directory-structure contract; do
+  [ -f "$WORK/section-$s.md" ] || touch "$WORK/section-$s.md"
+done
+
+write_page() {
+  # write_page <output-path> <title> <permalink> <body-file>
+  local out="$1" title="$2" permalink="$3" body="$4"
+  {
+    printf -- '---\n'
+    printf 'layout: page\n'
+    printf 'title: %s\n' "$title"
+    printf 'permalink: %s\n' "$permalink"
+    printf -- '---\n\n'
+    cat "$body"
+  } > "$out"
+}
+
+# --- 2. docs/agents.md, docs/hooks.md, docs/mcp-tools.md -------------------
+# Straight ports — no internal markdown links were found in these sections
+# of documentation.md, so no link rewriting is needed beyond the front
+# matter wrapper.
+write_page "$DOCS_DIR/agents.md" "Agents" "/agents.html" "$WORK/section-agents.md"
+write_page "$DOCS_DIR/hooks.md" "Hooks" "/hooks.html" "$WORK/section-hooks.md"
+write_page "$DOCS_DIR/mcp-tools.md" "MCP Tools" "/mcp-tools.html" "$WORK/section-mcp-tools.md"
+
+# --- 3. docs/skills.md ------------------------------------------------------
+# Single reference page (matches the story's own suggested top-level
+# category list: Getting Started / Concepts / Skills reference / Agents /
+# Hooks / MCP Tools — "Skills reference" is one page, not one page per
+# skill). Category (### ) and per-skill (#### ) structure is preserved
+# as-is from the source.
+write_page "$DOCS_DIR/skills.md" "Skills Reference" "/skills.html" "$WORK/section-skills.md"
+
+# --- 4. docs/reference.md ---------------------------------------------------
+# Combines the two remaining documentation.md sections (Directory Structure,
+# Agent Communication Contract) behind a short hand-authored index blurb
+# that links out to the pages built above — this replaces documentation.md's
+# original role as the single "full reference" entry point, now that its
+# content is split across multiple pages.
+{
+  cat <<'EOF'
+## Full Reference Index
+
+This page is the entry point into the full reference material, split across
+several pages so nothing requires scrolling through one giant file:
+
+- **[Skills Reference](./skills.md)** — every skill, grouped by Setup &
+  Planning, Execution, Status & Review, and Committing & Maintenance.
+- **[Agents](./agents.md)** — Scrum Master, Developer, Tester: roles,
+  ownership, and responsibilities.
+- **[Hooks](./hooks.md)** — session lifecycle hooks and what they run.
+- **[MCP Tools](./mcp-tools.md)** — Model Context Protocol tools available
+  in a Claude Code session.
+
+The rest of this page covers the repo's directory structure and the
+inter-agent communication contract (the typed "sender object" every agent
+call carries).
+
+---
+
+EOF
+  cat "$WORK/section-directory-structure.md"
+  printf '\n---\n\n'
+  cat "$WORK/section-contract.md"
+} > "$WORK/reference-body.md"
+write_page "$DOCS_DIR/reference.md" "Reference" "/reference.html" "$WORK/reference-body.md"
+
+# --- 5. docs/getting-started.md ---------------------------------------------
+# Port of intro-guide.md verbatim (drop the leading H1 — front matter
+# supplies the page title instead), with its two links into the
+# now-restructured reference/concepts pages rewritten.
+tail -n +2 "$INTRO_MD" > "$WORK/intro-body.md"
+# NOTE on delimiter choice: sed's `s<delim>pattern<delim>replacement<delim>`
+# breaks if the replacement text itself contains the delimiter character.
+# Several replacements below contain a literal "#" (anchor fragments), so
+# "#" cannot be used as the delimiter here — "|" is used instead, since
+# none of these paths/anchors contain a literal "|".
+sed -i.bak \
+  -e 's|\[documentation\.md\](\./documentation\.md)|[reference.md](./reference.md)|g' \
+  -e 's|(\./concepts/role-separation\.md)|(./concepts.md#role-separation)|g' \
+  -e 's|(\./concepts/board-hierarchy\.md)|(./concepts.md#board-hierarchy)|g' \
+  -e 's|(\./concepts/session-continuity\.md)|(./concepts.md#session-continuity)|g' \
+  -e 's|(\./concepts/first-feature\.md)|(./concepts.md#your-first-feature)|g' \
+  -e 's|(\./concepts/multi-session-work\.md)|(./concepts.md#working-across-sessions)|g' \
+  -e 's|(\./concepts/mid-flow-capture\.md)|(./concepts.md#capturing-mid-flow-ideas)|g' \
+  -e 's|(\./concepts/parallel-tasks\.md)|(./concepts.md#parallel-tasks)|g' \
+  "$WORK/intro-body.md"
+rm -f "$WORK/intro-body.md.bak"
+write_page "$DOCS_DIR/getting-started.md" "Getting Started" "/getting-started.html" "$WORK/intro-body.md"
+
+# --- 6. docs/concepts.md -----------------------------------------------------
+# Concatenates all 7 project/.wiki/concepts/*.md files into one page:
+#   - each file's H1 becomes an H2 section heading (slug listed below must
+#     stay in sync with each file's actual title text — GitHub Pages/kramdown
+#     slugifies headings to lowercase-hyphenated automatically)
+#   - all other headings are demoted one level (## -> ###, ### -> ####)
+#   - sibling/parent links are rewritten to point within the merged page
+#     and at the sibling getting-started.md / reference.md pages
+#
+{
+  cat <<'EOF'
+## Concepts
+
+The ideas behind Jenga AI's structure, and the how-tos for using it day to
+day. Jump to any section:
+
+- [Role Separation](#role-separation)
+- [Board Hierarchy](#board-hierarchy)
+- [Session Continuity](#session-continuity)
+- [Your First Feature](#your-first-feature)
+- [Working Across Sessions](#working-across-sessions)
+- [Capturing Mid-Flow Ideas](#capturing-mid-flow-ideas)
+- [Parallel Tasks](#parallel-tasks)
+
+---
+
+EOF
+} > "$WORK/concepts-body.md"
+
+append_concept() {
+  # append_concept <filename-stem> <section-title>
+  local stem="$1"
+  local title="$2"
+  local src="$CONCEPTS_DIR/$stem.md"
+  {
+    printf '## %s\n\n' "$title"
+    # NOTE on delimiter choice: same reasoning as the getting-started block
+    # above — replacements here contain a literal "#" anchor character, so
+    # "|" is used as the sed delimiter instead of "#".
+    #
+    # NOTE on heading demotion: a naive two-pass "## -> ###" then
+    # "### -> ####" sed would double-demote lines that were originally
+    # "## " (they'd match the first rule, becoming "### ", and then ALSO
+    # match the second rule on the same pass, becoming "#### " — wrong).
+    # The single extended-regex rule below captures the existing run of
+    # 2-3 "#" characters and prepends exactly one more, so each line is
+    # demoted exactly once regardless of its original level.
+    tail -n +2 "$src" \
+      | sed \
+        -e 's|\[documentation\.md\](\.\./documentation\.md)|[reference.md](./reference.md)|g' \
+        -e 's|(\.\./intro-guide\.md)|(./getting-started.md)|g' \
+        -e 's|(\.\./documentation\.md)|(./reference.md)|g' \
+        -e 's|(\./role-separation\.md)|(#role-separation)|g' \
+        -e 's|(\./board-hierarchy\.md)|(#board-hierarchy)|g' \
+        -e 's|(\./session-continuity\.md)|(#session-continuity)|g' \
+        -e 's|(\./first-feature\.md)|(#your-first-feature)|g' \
+        -e 's|(\./multi-session-work\.md)|(#working-across-sessions)|g' \
+        -e 's|(\./mid-flow-capture\.md)|(#capturing-mid-flow-ideas)|g' \
+        -e 's|(\./parallel-tasks\.md)|(#parallel-tasks)|g' \
+      | sed -E 's/^(#{2,3}) /#\1 /'
+    printf '\n---\n\n'
+  } >> "$WORK/concepts-body.md"
+}
+
+append_concept "role-separation" "Role Separation"
+append_concept "board-hierarchy" "Board Hierarchy"
+append_concept "session-continuity" "Session Continuity"
+append_concept "first-feature" "Your First Feature"
+append_concept "multi-session-work" "Working Across Sessions"
+append_concept "mid-flow-capture" "Capturing Mid-Flow Ideas"
+append_concept "parallel-tasks" "Parallel Tasks"
+
+write_page "$DOCS_DIR/concepts.md" "Concepts" "/concepts.html" "$WORK/concepts-body.md"
+
+echo "build-pages-site.sh: regenerated docs/{getting-started,concepts,skills,agents,hooks,mcp-tools,reference}.md from project/.wiki/*"

package/scripts/generate-legacy-shipped-paths.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * scripts/generate-legacy-shipped-paths.js — legacy shipped-path list generator (E26_S08_T03)
+ *
+ * Why this exists
+ * ────────────────
+ * `lib/postinstall-manifest.js`'s delete reconciliation (E26_S08_T01) is purely forward-looking:
+ * a consumer already installed before any manifest existed can never have their pre-existing
+ * orphans cleaned up, because the first manifest a fixed version ever writes for them records
+ * only what THAT run mirrored. This script produces the static list this package ships so the
+ * FIRST manifest a consumer ever gets can instead be *seeded* with paths known to have shipped in
+ * some real prior published version — see `seedFromLegacyPaths` in `lib/postinstall-manifest.js`
+ * and `scripts/postinstall.js`'s `no-prior-manifest` branch for how the seed is consumed.
+ *
+ * Why not git tags
+ * ─────────────────
+ * The task's design note allows deriving the list "from git tags" as an alternative to
+ * publish-time derivation. Checked and rejected for this repo specifically: this repo's local
+ * tags (`v0.0.1`, `v55.0.1`, `last-self-sync`) do not correspond to the real npm publish history
+ * at all — `npm view @jenga-ai/agent versions --json` shows the real, disconnected sequence
+ * (1.0.0 through 3.0.0 as of this writing). Reconstructing shipped paths from local git tags in
+ * this repo would silently produce a list bearing no relation to what was actually published.
+ *
+ * Two modes
+ * ─────────
+ *   --bootstrap   Fetches EVERY version `npm view <package> versions --json` currently lists from
+ *                 the real registry, `npm pack`s each one into a throwaway temp dir, and unions
+ *                 the `skills/`+`agents/` entries inside every tarball. Network-dependent. This is
+ *                 how the real historical shipped-path set is captured — including versions whose
+ *                 git history is not reliably reconstructable locally (verified true here). Meant
+ *                 to be run manually / rarely — a one-off backfill, or an occasional resync — NOT
+ *                 wired into the automatic per-publish flow (see incremental mode below for that).
+ *
+ *   (default)     Incremental, no network: reads whatever is already at the output path (if any)
+ *                 and unions it with the paths CURRENTLY on disk under this repo's own `skills/`
+ *                 and `agents/` directories — i.e. "what this release is about to ship" folds into
+ *                 the running cumulative record. This is the mode wired into the publish pipeline
+ *                 (`skills/publish/scripts/npm_pipeline.sh` / `npm_ci_pipeline.sh`, via the
+ *                 `generate:legacy-paths` npm script) so every future publish keeps the list
+ *                 current with zero network dependency and zero publish-time registry flakiness.
+ *
+ *                 IMPORTANT — this mode's first-ever run is NOT a substitute for --bootstrap: if
+ *                 the output file doesn't exist yet, incremental mode unions an EMPTY existing set
+ *                 with whatever's on disk in THIS repo's tree right now. That happens to currently
+ *                 equal the real historical union (this repo's working tree is a superset of every
+ *                 published version's file list, as of the 2026-09-07 verification below) — but
+ *                 that is a coincidence of this repo's current state, not a guarantee the mode
+ *                 itself provides. The very first generation of the shipped artifact MUST use
+ *                 --bootstrap so the baseline is verified against the real registry, not assumed.
+ *
+ * Output
+ * ──────
+ * `lib/legacy-shipped-paths.json` (ships automatically — `lib/` is already in package.json's
+ * `files` allow-list, no change needed there):
+ *
+ *   {
+ *     "generated_at": "<ISO 8601>",
+ *     "package": "@jenga-ai/agent",
+ *     "source": "bootstrap-from-registry+incremental" | "incremental",
+ *     "paths": ["agents/developer.md", "skills/do/SKILL.md", ...]
+ *   }
+ *
+ * `paths` are relative to a mirror root, POSIX-separated, deduped and sorted — matching the same
+ * shape convention `lib/postinstall-manifest.js`'s own manifest uses, for consistency.
+ *
+ * The generation step is regenerated automatically as part of the publish flow (incremental mode),
+ * per this task's AC — it is NOT hand-maintained, so it cannot silently go stale across releases.
+ *
+ * ESM, Node built-ins only — matches lib/postinstall-manifest.js and lib/mirror.js. `npm` itself is
+ * shelled out to (via `execFileSync`) only in `--bootstrap` mode.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.join(__dirname, '..');
+
+export const DEFAULT_OUTPUT_PATH = path.join(REPO_ROOT, 'lib', 'legacy-shipped-paths.json');
+export const DEFAULT_PACKAGE_NAME = '@jenga-ai/agent';
+
+/** Discovery-bound directories mirrored into a consumer's .agents/ and .claude/ (see docs/distribution.md §1). */
+const COPY_SET = ['skills', 'agents'];
+
+// ── walk a real directory tree ──────────────────────────────────────────────
+
+function walkDir(base, dir, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_) {
+    return;
+  }
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkDir(base, abs, out);
+    } else if (entry.isFile()) {
+      out.push(path.relative(base, abs).split(path.sep).join('/'));
+    }
+    // symlinks intentionally ignored — matches lib/mirror.js's own walk behavior.
+  }
+}
+
+/**
+ * Relative POSIX paths this repo's CURRENT `skills/` + `agents/` trees would ship, i.e. exactly
+ * what a fresh install of the version about to be published would mirror.
+ *
+ * @param {string} repoRoot
+ * @returns {string[]} sorted, deduped
+ */
+export function currentShippedPaths(repoRoot = REPO_ROOT) {
+  const out = [];
+  for (const entry of COPY_SET) {
+    const dir = path.join(repoRoot, entry);
+    if (fs.existsSync(dir)) walkDir(repoRoot, dir, out);
+  }
+  return [...new Set(out)].sort();
+}
+
+// ── read existing output (if any) ───────────────────────────────────────────
+
+function readExistingPaths(outputPath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(outputPath, 'utf8'));
+    return Array.isArray(parsed.paths) ? parsed.paths.filter((p) => typeof p === 'string') : [];
+  } catch (_) {
+    return []; // absent, unreadable, or corrupt — start from an empty cumulative set
+  }
+}
+
+// ── bootstrap from the real npm registry ────────────────────────────────────
+
+/**
+ * Fetch every currently-listed published version of `packageName`, `npm pack` each into a
+ * throwaway temp dir, and union the `skills/`+`agents/` entries found inside every tarball.
+ * Network-dependent — intended for manual/rare use (a one-off backfill or occasional resync),
+ * never called by the automatic per-publish (incremental) path.
+ *
+ * @param {string} packageName
+ * @returns {string[]} sorted, deduped relative POSIX paths
+ */
+export function bootstrapFromRegistry(packageName = DEFAULT_PACKAGE_NAME) {
+  const versionsRaw = execFileSync('npm', ['view', packageName, 'versions', '--json'], {
+    encoding: 'utf8',
+  });
+  const versions = JSON.parse(versionsRaw);
+  const all = new Set();
+
+  for (const version of versions) {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'jenga-legacy-bootstrap-'));
+    try {
+      execFileSync('npm', ['pack', `${packageName}@${version}`, '--silent'], { cwd: tmp, stdio: 'ignore' });
+      const tarball = fs.readdirSync(tmp).find((f) => f.endsWith('.tgz'));
+      if (!tarball) continue;
+      const listing = execFileSync('tar', ['-tzf', path.join(tmp, tarball)], { encoding: 'utf8' });
+      for (const line of listing.split('\n')) {
+        const m = line.match(/^package\/(skills|agents)\/(.+)$/);
+        if (m && !line.endsWith('/')) all.add(`${m[1]}/${m[2]}`);
+      }
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+
+  return [...all].sort();
+}
+
+// ── generate ─────────────────────────────────────────────────────────────────
+
+/**
+ * @param {object}  [opts]
+ * @param {string}  [opts.outputPath]   Default: lib/legacy-shipped-paths.json
+ * @param {string}  [opts.packageName]  Default: @jenga-ai/agent
+ * @param {boolean} [opts.bootstrap]    Default: false (incremental, no network)
+ * @param {string}  [opts.repoRoot]     Default: this repo's own root
+ * @returns {{written: boolean, path: string, count: number, source: string}}
+ */
+export function generate({
+  outputPath = DEFAULT_OUTPUT_PATH,
+  packageName = DEFAULT_PACKAGE_NAME,
+  bootstrap = false,
+  repoRoot = REPO_ROOT,
+} = {}) {
+  const existing = readExistingPaths(outputPath);
+  let paths;
+  let source;
+
+  if (bootstrap) {
+    const registryPaths = bootstrapFromRegistry(packageName);
+    paths = [...new Set([...registryPaths, ...existing])].sort();
+    source = 'bootstrap-from-registry+incremental';
+  } else {
+    const current = currentShippedPaths(repoRoot);
+    paths = [...new Set([...existing, ...current])].sort();
+    source = 'incremental';
+  }
+
+  const artifact = {
+    generated_at: new Date().toISOString(),
+    package: packageName,
+    source,
+    paths,
+  };
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, JSON.stringify(artifact, null, 2) + '\n', 'utf8');
+
+  return { written: true, path: outputPath, count: paths.length, source };
+}
+
+/**
+ * Read the shipped legacy-paths artifact's `paths` array. Fail-toward-doing-nothing: any read or
+ * parse failure returns `[]` rather than throwing — a missing/corrupt legacy-paths file must
+ * never abort or degrade an unattended `npm install`, mirroring `readManifest`'s own posture in
+ * `lib/postinstall-manifest.js`.
+ *
+ * @param {string} artifactPath
+ * @returns {string[]}
+ */
+export function readLegacyShippedPaths(artifactPath = DEFAULT_OUTPUT_PATH) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(artifactPath, 'utf8'));
+    if (!Array.isArray(parsed.paths)) return [];
+    return parsed.paths.filter((p) => typeof p === 'string' && p.length > 0);
+  } catch (_) {
+    return [];
+  }
+}
+
+// ── CLI guard ────────────────────────────────────────────────────────────────
+// node scripts/generate-legacy-shipped-paths.js [--bootstrap] [--package <name>] [outputPath]
+
+const invokedPath = process.argv[1] ? fs.realpathSync(process.argv[1]) : null;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  const bootstrap = argv.includes('--bootstrap');
+  const pkgFlagIndex = argv.indexOf('--package');
+  const packageName = pkgFlagIndex !== -1 ? argv[pkgFlagIndex + 1] : DEFAULT_PACKAGE_NAME;
+  const positional = argv.filter((a, i) => a !== '--bootstrap' && i !== pkgFlagIndex && i !== pkgFlagIndex + 1 && !a.startsWith('--'));
+  const outputPath = positional[0] || DEFAULT_OUTPUT_PATH;
+
+  const result = generate({ outputPath, packageName, bootstrap });
+  console.log(`✓ ${result.path} (${result.count} paths, ${result.source})`);
+}