brewdoc 0.3.1__tar.gz → 0.3.2__tar.gz

{brewdoc-0.3.1 → brewdoc-0.3.2}/.github/distribution.json

@@ -40,7 +40,6 @@
     "name": "brewdoc",
     "packages": {
       "linux-x64": "brewdoc-linux-x64-glibc",
-      "windows-x64": "brewdoc-win32-x64",
       "macos-arm64": "brewdoc-darwin-arm64"
     },
     "node": "24.21.0",
@@ -52,11 +51,8 @@
     "linux": "Archive SHA-256 checksums; no detached publisher signature"
   },
   "release_features": [
-    "Portable one-folder bundles for Linux x64, Windows x64 and macOS ARM64 with bundled Python and dependencies",
-    "npm and npx launch the same admitted native engine through platform packages",
-    "Offline EPUB 2/3 conversion in declared spine order with Unicode metadata and navigation",
-    "Explicit URL acquisition and optional isolated JavaScript capture on admitted platforms",
-    "PDF, DOCX, PPTX, workbook and static HTML conversion with deterministic receipts"
+    "Dedicated installation guide and concise CLI/API documentation",
+    "npm/npx packaging for Linux x64/glibc and macOS ARM64; Windows via GitHub native or Python"
   ],
   "releases": {
     "0.2.0": {

brewdoc-0.3.2/.github/npm-diagnostic-public.pem

@@ -0,0 +1,11 @@
+-----BEGIN PUBLIC KEY-----
+MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAy74Md75tburqWJtMECMs
+/5OqcyxQNq1rKJtz17HdfE6GJCj/eczuv4HXpf5muq0+hRnjBNxVZ90yiYr7mRdM
+WF+R594Pv5/lR19bH5+PtEka/skYK3LcsVHO2lrQHG3tWAWiddp+k0H5umwkQ7tN
+CoXM9A088t/uZ8EpbRf6GpDKe4tnFLBMU2cPYTnD1x9yXOesXov89TYRUEP7aqhb
+qfWZpxdLXBy8I3K3d5hIlrbuJQ5Mn36K9BtmXHMj3gjJW6tlDJR0Zd2GN13yvwZC
+9YQ7aDB3oiMP6RdCF3HO8zILP5MnvhIrALHUvjrNLBbGTVnmzXsYyAjoOaW9GOng
+KsYmdr/ypjHHmt8iEndNAKXw0XMq+I+EQ8yAxqKe1mMvjAya1Aaq/np0fOiYwm+l
+UwpybGajeOuF5OhKoMJY97WwSzxOt8MORjjYHRXmgYbWNDQwoBexu1pA+OV54Ygt
+5/z+YXjQT/eMh8NCJljUwdABYJKUFI0LTo1wInZFjV7vAgMBAAE=
+-----END PUBLIC KEY-----

{brewdoc-0.3.1 → brewdoc-0.3.2}/.github/workflows/build_npm.py

@@ -31,11 +31,18 @@ ROOT = Path(__file__).resolve().parents[2]
 REGISTRY = "https://registry.npmjs.org"
 NODE_VERSION = "24.21.0"
 NPM_VERSION = "12.2.0"
-PACKAGES = {"linux-x64": "brewdoc-linux-x64-glibc", "windows-x64": "brewdoc-win32-x64",
-            "macos-arm64": "brewdoc-darwin-arm64"}
+PACKAGES = {"linux-x64": "brewdoc-linux-x64-glibc", "macos-arm64": "brewdoc-darwin-arm64"}
 TARGETS = {"linux-x64": {"os": "linux", "cpu": "x64", "libc": "glibc", "executable": "binary/brewdoc"},
-           "windows-x64": {"os": "win32", "cpu": "x64", "executable": "binary/brewdoc.exe"},
            "macos-arm64": {"os": "darwin", "cpu": "arm64", "executable": "binary/brewdoc"}}
+PUBLISH_CAUSES = {"E400": "bad-request", "E401": "authentication-rejected", "E403": "registry-forbidden",
+                  "E404": "registry-not-found", "E409": "version-conflict", "E429": "rate-limit",
+                  "E413": "payload-too-large", "E422": "registry-unprocessable",
+                  "EOTP": "one-time-password-required", "ENEEDAUTH": "authentication-required",
+                  "EPUBLISHCONFLICT": "version-conflict", "EUSAGE": "usage-error",
+                  "ECONNRESET": "transport-error", "ETIMEDOUT": "transport-error",
+                  "ENOTFOUND": "transport-error", "EAI_AGAIN": "transport-error",
+                  "E500": "registry-unavailable", "E502": "registry-unavailable",
+                  "E503": "registry-unavailable", "E504": "registry-unavailable"}
 
 
 def digest(payload: bytes) -> str:
@@ -94,8 +101,10 @@ def release_version() -> str:
 
 def package_metadata(version: str, target: str | None = None) -> dict:
     """Generate exact dependency and platform metadata without lifecycle scripts."""
+    if target is not None and target not in PACKAGES:
+        raise ValueError(f"Unsupported npm target: {target}")
     metadata = {"name": PACKAGES[target] if target else "brewdoc", "version": version,
-                "description": "Convert documents to deterministic Markdown with Brewdoc.",
+                "description": "Fast, deterministic document-to-Markdown conversion for agent systems. Easy to install. No model weights, OCR or external services.",
                 "license": "MIT", "repository": {"type": "git", "url": "git+https://github.com/kochetkov-ma/brewdoc.git"},
                 "homepage": "https://github.com/kochetkov-ma/brewdoc#readme",
                 "publishConfig": {"access": "public", "registry": REGISTRY}}
@@ -230,13 +239,115 @@ def npm_command(arguments: list[str], npx: bool = False) -> list[str]:
     return [str(executable), str(npm), *arguments]
 
 
+def publish_error(payload: bytes) -> dict | None:
+    """Admit one bounded npm error object without exposing its contents."""
+    if len(payload) > 64 * 1024:
+        return None
+
+    def unique_object(pairs):
+        """Reject conflicting JSON keys before classification."""
+        if len({name for name, _ in pairs}) != len(pairs):
+            raise ValueError("Duplicate npm error field")
+        return dict(pairs)
+
+    try:
+        value = json.loads(payload.decode("utf-8"), object_pairs_hook=unique_object)
+    except (ValueError, UnicodeError, RecursionError):
+        return None
+    error = value.get("error") if isinstance(value, dict) else None
+    if (not isinstance(error, dict) or not isinstance(error.get("code"), str)
+            or any(not isinstance(error.get(field, ""), str) for field in ("summary", "detail"))):
+        return None
+    return error
+
+
+def publish_failure(payload: bytes) -> tuple[str, str]:
+    """Return finite diagnostics without exposing authenticated npm output."""
+    unknown = ("UNKNOWN", "unclassified")
+    error = publish_error(payload)
+    if error is None:
+        return unknown
+    code = error["code"] if error["code"] in PUBLISH_CAUSES else "UNKNOWN"
+    cause = PUBLISH_CAUSES.get(code, "unclassified")
+    fields = ("summary",) if code == "E403" else ("summary", "detail")
+    message = " ".join(error.get(field, "") for field in fields).lower()
+    matches = {label for label, phrases in (
+        ("provenance-error", ("provenance generation", "generate provenance", "invalid provenance", "provenance statement")),
+        ("one-time-password-required", ("one-time password", "two-factor authentication")),
+        ("version-conflict", ("cannot publish over", "previously published versions")),
+    ) if any(phrase in message for phrase in phrases)}
+    if code == "E403":
+        matches.update(label for label, phrases in (
+            ("package-name-refused", ("package name too similar", "package name is reserved")),
+            ("email-verification-required", ("verify your email", "email address must be verified")),
+            ("publish-permission-refused", ("do not have permission to publish", "not authorized to publish",
+                                          "you may not perform that action with these credentials")),
+            ("security-policy-refused", ("blocked by security policy", "blocked by a security policy")),
+            ("ip-restriction-mentioned", ("not allowed from your ip address", "ip address is not allowed")),
+        ) if any(phrase in message for phrase in phrases))
+    if len(matches) > 1:
+        return unknown
+    return code, next(iter(matches)) if matches else cause
+
+
+def store_publication_diagnostic(payload: bytes, record: dict | None, environment: dict) -> None:
+    """Keep a bounded error summary only as context-bound public-key ciphertext."""
+    output = environment.get("BREWDOC_NPM_DIAGNOSTIC_DIR")
+    if not output or not isinstance(record, dict):
+        return
+    try:
+        error = publish_error(payload)
+        metadata = record["metadata"]
+        package = metadata["name"]
+        if (error is None or package not in {*PACKAGES.values(), "brewdoc"}
+                or not error.get("summary") or len(error["summary"].encode("utf-8")) > 4096):
+            return
+        run_id, attempt = environment.get("GITHUB_RUN_ID", ""), environment.get("GITHUB_RUN_ATTEMPT", "")
+        if (not isinstance(run_id, str) or not run_id.isdecimal() or int(run_id) <= 0
+                or not isinstance(attempt, str) or not attempt.isdecimal() or int(attempt) <= 0):
+            return
+        code, cause = publish_failure(payload)
+        context = {"schema": 1, "package": package, "version": metadata["version"],
+                   "tarball_sha256": record["sha256"], "source_sha": record["source_sha"],
+                   "controller_sha": environment.get("GITHUB_SHA", ""), "run_id": int(run_id),
+                   "run_attempt": int(attempt), "code": code, "cause": cause, "summary": error["summary"]}
+        plaintext = json.dumps(context, ensure_ascii=False).encode("utf-8")
+        node = shutil.which("node")
+        if not node or len(plaintext) > 8192:
+            return
+        clean = {key: environment[key] for key in ("PATH", "SystemRoot", "SYSTEMROOT") if key in environment}
+        result = subprocess.run([node, str(ROOT / ".github/workflows/npm_diagnostic.cjs")],
+                                input=plaintext, capture_output=True, timeout=10, env=clean)
+        if result.returncode or len(result.stdout) > 16 * 1024:
+            return
+        envelope = json.loads(result.stdout)
+        fields = {"schema", "algorithm", "key_sha256", "encrypted_key", "iv", "tag", "ciphertext"}
+        if (not isinstance(envelope, dict) or set(envelope) != fields or type(envelope["schema"]) is not int
+                or envelope["schema"] != 1 or envelope["algorithm"] != "RSA-OAEP-SHA256+A256GCM"
+                or envelope["key_sha256"] != digest((ROOT / ".github/npm-diagnostic-public.pem").read_bytes())):
+            return
+        lengths = {"encrypted_key": 384, "iv": 12, "tag": 16, "ciphertext": len(plaintext)}
+        if any(len(base64.b64decode(envelope[name], validate=True)) != size for name, size in lengths.items()):
+            return
+        directory = Path(output)
+        if directory.is_symlink():
+            return
+        directory.mkdir(parents=True, exist_ok=True)
+        with (directory / f"{package}.json").open("x", encoding="utf-8") as stream:
+            stream.write(json.dumps(envelope, sort_keys=True) + "\n")
+    except (OSError, ValueError, TypeError, KeyError, UnicodeError, RecursionError, subprocess.SubprocessError):
+        return
+
+
 def run_npm(arguments: list[str], cwd: Path, environment: dict, timeout: int = 180,
-            npx: bool = False) -> subprocess.CompletedProcess:
+            npx: bool = False, publication: dict | None = None) -> subprocess.CompletedProcess:
     """Bound npm tool calls and keep failure output separate from receipt stdout."""
     result = subprocess.run(npm_command(arguments, npx), cwd=cwd, env=environment, capture_output=True, timeout=timeout)
     if result.returncode:
         if arguments[0] == "publish":
-            raise RuntimeError(f"npm publish failed ({result.returncode}); authenticated output was suppressed")
+            code, cause = publish_failure(result.stdout)
+            store_publication_diagnostic(result.stdout, publication, environment)
+            raise RuntimeError(f"npm publish failed ({result.returncode}); code={code}; cause={cause}; authenticated output was suppressed")
         raise RuntimeError(f"npm command failed ({result.returncode}): {arguments[0]}\n"
                            + (result.stdout + result.stderr).decode("utf-8", errors="replace"))
     return result
@@ -365,8 +476,8 @@ def aggregate(input_dir: Path, output: Path) -> None:
     """Admit the complete platform set before creating the main CLI package."""
     paths = sorted(input_dir.rglob("platform-record.json"))
     records = {read_json(path)["target"]: (path, read_json(path)) for path in paths}
-    if len(paths) != 3 or set(records) != set(PACKAGES):
-        raise ValueError("npm aggregation requires exactly three platform records")
+    if len(paths) != 2 or set(records) != set(PACKAGES):
+        raise ValueError("npm aggregation requires exactly two platform records")
     version = release_version()
     identities = {(record["version"], record["source_sha"]) for _, record in records.values()}
     if len(identities) != 1 or next(iter(identities))[0] != version:
@@ -398,7 +509,7 @@ def aggregate(input_dir: Path, output: Path) -> None:
 
 
 def verify_release(input_dir: Path) -> dict:
-    """Admit exactly four npm package archives with one version and source identity."""
+    """Admit exactly three npm package archives with one version and source identity."""
     manifest = read_json(input_dir / "npm-manifest.json")
     version = manifest["version"]
     expected_names = [*PACKAGES.values(), "brewdoc"]
@@ -453,8 +564,8 @@ def publish(input_dir: Path) -> None:
     existing = [public_record(record) for record in manifest["packages"]]
     for record, admitted in zip(manifest["packages"], existing, strict=True):
         if not admitted:
-            run_npm(["publish", str((input_dir / record["filename"]).resolve()), "--ignore-scripts", "--access", "public", "--provenance"],
-                    input_dir, os.environ.copy())
+            run_npm(["publish", str((input_dir / record["filename"]).resolve()), "--ignore-scripts", "--access", "public", "--provenance", "--json"],
+                    input_dir, os.environ.copy(), publication=record)
         if not public_record(record):
             raise ValueError("Published npm version is absent from the registry")
 
@@ -472,7 +583,7 @@ def check_public(input_dir: Path, output: Path | None = None) -> None:
 
 
 def local_registry(input_dir: Path, manifest: dict) -> ThreadingHTTPServer:
-    """Serve only the four admitted packages for real offline npm resolution."""
+    """Serve only the three admitted packages for real offline npm resolution."""
     records = {record["metadata"]["name"]: record for record in manifest["packages"]}
 
     class Handler(BaseHTTPRequestHandler):
@@ -741,14 +852,15 @@ def cancellation_probe(launcher: Path, work: Path, environment: dict, javascript
 def probe(input_dir: Path, target: str, mode: str, output: Path, smoke: bool = False,
           public_evidence: Path | None = None) -> None:
     """Prove npm global/local and actual npx consumers outside the checkout."""
+    if target not in PACKAGES:
+        raise ValueError(f"Unsupported npm target: {target}")
     manifest = verify_release(input_dir)
     scope = "smoke" if smoke else "full"
     if verification_scope(manifest) != scope:
         raise ValueError("npm consumer verification scope differs")
     selected = next(record for record in manifest["packages"] if record.get("target") == target)
     system, machine = platform.system(), platform.machine().lower()
-    expected = {"linux-x64": ("Linux", "x86_64"), "windows-x64": ("Windows", "amd64"),
-                "macos-arm64": ("Darwin", "arm64")}
+    expected = {"linux-x64": ("Linux", "x86_64"), "macos-arm64": ("Darwin", "arm64")}
     if (system, machine) != expected[target]:
         raise ValueError("npm consumer must run on its matching native target")
     if mode == "public":

{brewdoc-0.3.1 → brewdoc-0.3.2}/.github/workflows/ci.yml

@@ -75,14 +75,17 @@ jobs:
       - name: Verify native CLI and accepted outputs outside the checkout
         run: uv run --no-project --python 3.12.14 python .github/workflows/build_standalone.py verify --checkout "${{ github.workspace }}" --bundle "${{ runner.temp }}/ci-dist" --output "${{ runner.temp }}/ci-native-${{ matrix.target }}" --target "${{ matrix.target }}" --smoke
       - uses: actions/setup-node@v7.1.0
+        if: matrix.target != 'windows-x64'
         with:
           node-version: "24.21.0"
           package-manager-cache: false
       - uses: actions/cache@v6.1.0
+        if: matrix.target != 'windows-x64'
         with:
           path: ${{ runner.temp }}/npm-downloads/_cacache
           key: ${{ runner.os }}-${{ runner.arch }}-node24.21.0-npm12.2.0-${{ hashFiles('uv.lock', 'npm/**', '.github/workflows/build_npm.py') }}
       - name: Install pinned npm beside the selected Node runtime
+        if: matrix.target != 'windows-x64'
         shell: bash
         run: |
           BREWDOC_NPM_PREFIX=$(node -p 'const path = require("node:path"); path.resolve(path.dirname(process.execPath), process.platform === "win32" ? "." : "..")')
@@ -90,6 +93,7 @@ jobs:
         env:
           NPM_CONFIG_CACHE: ${{ runner.temp }}/npm-downloads
       - name: Pack the verified platform before native file attributes leave this runner
+        if: matrix.target != 'windows-x64'
         run: uv run --no-project --python 3.12.14 python .github/workflows/build_npm.py pack --native-dir "${{ runner.temp }}/ci-native-${{ matrix.target }}" --output "${{ runner.temp }}/ci-npm-${{ matrix.target }}"
       - name: Preserve native bundle and runtime evidence
         if: always()
@@ -105,7 +109,7 @@ jobs:
           if-no-files-found: warn
           retention-days: 7
       - name: Preserve sealed npm platform tarball and admission record
-        if: always()
+        if: always() && matrix.target != 'windows-x64'
         uses: actions/upload-artifact@v7.0.2
         with:
           overwrite: true
@@ -168,7 +172,7 @@ jobs:
           digest-mismatch: error
       - name: Assemble the main package only after every native platform passes
         run: uv run --no-project --python 3.12.14 python .github/workflows/build_npm.py aggregate --input "${{ runner.temp }}/ci-npm-targets" --output "${{ runner.temp }}/ci-npm-release"
-      - name: Admit the complete four-package npm set
+      - name: Admit the complete three-package npm set
         run: uv run --no-project --python 3.12.14 python .github/workflows/build_npm.py verify --input "${{ runner.temp }}/ci-npm-release"
       - uses: actions/upload-artifact@v7.0.2
         with:
@@ -195,8 +199,6 @@ jobs:
             os: ubuntu-22.04
           - target: macos-arm64
             os: macos-15
-          - target: windows-x64
-            os: windows-2025
     steps:
       - uses: actions/checkout@v7.0.1
         with:

brewdoc-0.3.2/.github/workflows/npm_diagnostic.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+const { createCipheriv, createHash, publicEncrypt, randomBytes, constants } = require('node:crypto');
+const { readFileSync } = require('node:fs');
+const { join } = require('node:path');
+
+/** Encrypt one bounded publication summary without producing plaintext output. */
+function encrypt(payload) {
+  if (payload.length > 8192) throw new Error('Invalid diagnostic');
+  const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(payload));
+  const fields = ['schema', 'package', 'version', 'tarball_sha256', 'source_sha', 'controller_sha',
+    'run_id', 'run_attempt', 'code', 'cause', 'summary'];
+  if (!value || Array.isArray(value) || Object.keys(value).length !== fields.length
+      || fields.some(field => !Object.hasOwn(value, field)) || value.schema !== 1
+      || !['brewdoc-linux-x64-glibc', 'brewdoc-darwin-arm64', 'brewdoc'].includes(value.package)
+      || typeof value.version !== 'string' || !/^\d+\.\d+\.\d+$/.test(value.version)
+      || typeof value.tarball_sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(value.tarball_sha256)
+      || ['source_sha', 'controller_sha'].some(field => typeof value[field] !== 'string' || !/^[a-f0-9]{40}$/.test(value[field]))
+      || ['run_id', 'run_attempt'].some(field => !Number.isSafeInteger(value[field]) || value[field] <= 0)
+      || ['code', 'cause'].some(field => typeof value[field] !== 'string' || value[field].length > 64)
+      || typeof value.summary !== 'string' || !value.summary || Buffer.byteLength(value.summary) > 4096) {
+    throw new Error('Invalid diagnostic');
+  }
+  const publicKey = readFileSync(join(__dirname, '..', 'npm-diagnostic-public.pem'));
+  const key = randomBytes(32);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv, { authTagLength: 16 });
+  cipher.setAAD(Buffer.from('brewdoc-npm-diagnostic-v1'));
+  const ciphertext = Buffer.concat([cipher.update(payload), cipher.final()]);
+  return { schema: 1, algorithm: 'RSA-OAEP-SHA256+A256GCM',
+    key_sha256: createHash('sha256').update(publicKey).digest('hex'),
+    encrypted_key: publicEncrypt({ key: publicKey, padding: constants.RSA_PKCS1_OAEP_PADDING,
+      oaepHash: 'sha256' }, key).toString('base64'),
+    iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), ciphertext: ciphertext.toString('base64') };
+}
+
+/** Bound stdin before encrypting with the fixed tracked public key. */
+async function main() {
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of process.stdin) {
+    bytes += chunk.length;
+    if (bytes > 8192) throw new Error('Invalid diagnostic');
+    chunks.push(chunk);
+  }
+  process.stdout.write(JSON.stringify(encrypt(Buffer.concat(chunks))) + '\n');
+}
+
+module.exports = { encrypt };
+if (require.main === module) main().catch(() => { process.exitCode = 1; });

{brewdoc-0.3.1 → brewdoc-0.3.2}/.github/workflows/release.yml

@@ -38,6 +38,7 @@ jobs:
       GH_TOKEN: ${{ github.token }}
       BREWDOC_RELEASE_TAG: ${{ github.ref_name }}
       BREWDOC_SOURCE_SHA: ${{ github.sha }}
+      BREWDOC_PACKAGE_CHECKOUT: ${{ github.workspace }}
     steps:
       - uses: actions/checkout@v7.0.1
         with:
@@ -48,12 +49,12 @@ jobs:
           python-version: "3.12.14"
           cache-suffix: ${{ runner.os }}-${{ runner.arch }}-uv0.12.21-py3.12.14-${{ hashFiles('uv.lock') }}
       - name: Admit and download one exact-source successful main CI producer
-        run: uv run --no-project --python 3.12.14 python .github/workflows/release_assets.py reuse-ci --checkout "${{ github.workspace }}" --tag "$BREWDOC_RELEASE_TAG" --source-sha "$BREWDOC_SOURCE_SHA" --output "${{ runner.temp }}/producer"
+        run: uv run --no-project --python 3.12.14 python .github/workflows/release_assets.py reuse-ci --checkout "$BREWDOC_PACKAGE_CHECKOUT" --tag "$BREWDOC_RELEASE_TAG" --source-sha "$BREWDOC_SOURCE_SHA" --output "${{ runner.temp }}/producer"
       - name: Generate staged instructions from unchanged admitted bytes
-        run: uv run --no-project --python 3.12.14 python .github/workflows/release_guide.py render --checkout "${{ github.workspace }}" --phase staged --native-manifest "${{ runner.temp }}/producer/ci-native-assets/binaries.json" --npm-manifest "${{ runner.temp }}/producer/ci-npm-release/npm-manifest.json" --output "${{ runner.temp }}/staged-body.md"
+        run: uv run --no-project --python 3.12.14 python .github/workflows/release_guide.py render --checkout "$BREWDOC_PACKAGE_CHECKOUT" --phase staged --native-manifest "${{ runner.temp }}/producer/ci-native-assets/binaries.json" --npm-manifest "${{ runner.temp }}/producer/ci-npm-release/npm-manifest.json" --output "${{ runner.temp }}/staged-body.md"
       - name: Seal the release inventory and producer provenance
         id: identity
-        run: uv run --no-project --python 3.12.14 python .github/workflows/release_assets.py prepare --checkout "${{ github.workspace }}" --bundle "${{ runner.temp }}/producer/ci-dist" --native "${{ runner.temp }}/producer/ci-native-assets" --npm "${{ runner.temp }}/producer/ci-npm-release" --producer "${{ runner.temp }}/producer/producer.json" --body "${{ runner.temp }}/staged-body.md" --output "${{ runner.temp }}/release-assets" --github-output "$GITHUB_OUTPUT"
+        run: uv run --no-project --python 3.12.14 python .github/workflows/release_assets.py prepare --checkout "$BREWDOC_PACKAGE_CHECKOUT" --bundle "${{ runner.temp }}/producer/ci-dist" --native "${{ runner.temp }}/producer/ci-native-assets" --npm "${{ runner.temp }}/producer/ci-npm-release" --producer "${{ runner.temp }}/producer/producer.json" --body "${{ runner.temp }}/staged-body.md" --output "${{ runner.temp }}/release-assets" --github-output "$GITHUB_OUTPUT"
       - uses: actions/upload-artifact@v7.0.2
         with:
           name: dist
@@ -92,8 +93,8 @@ jobs:
       - uses: pypa/gh-action-pypi-publish@v1.14.2
 
   npm-publish:
-    if: github.event_name == 'push'
-    needs: publish
+    if: "!cancelled() && github.event_name == 'push' && needs.distribution-admit.result == 'success' && needs.pypi-consumer.result == 'success'"
+    needs: [distribution-admit, pypi-consumer]
     runs-on: ubuntu-22.04
     timeout-minutes: 15
     permissions:
@@ -130,10 +131,21 @@ jobs:
           path: ${{ runner.temp }}/release-npm
           digest-mismatch: error
       - name: Publish matching platform packages before the main package
+        id: npm_publish
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          BREWDOC_NPM_DIAGNOSTIC_DIR: ${{ runner.temp }}/npm-diagnostics
         run: uv run --no-project --python 3.12.14 python .github/workflows/build_npm.py publish --input "${{ runner.temp }}/release-npm"
-      - name: Verify all four public npm package bytes and integrity values
+      - name: Preserve encrypted publication diagnostics after a failed publish
+        if: failure() && steps.npm_publish.outcome == 'failure'
+        uses: actions/upload-artifact@v7.0.2
+        with:
+          name: npm-publish-diagnostic
+          overwrite: true
+          path: ${{ runner.temp }}/npm-diagnostics/*.json
+          if-no-files-found: warn
+          retention-days: 1
+      - name: Verify all three public npm package bytes and integrity values
         run: uv run --no-project --python 3.12.14 python .github/workflows/build_npm.py check-public --input "${{ runner.temp }}/release-npm" --output "${{ runner.temp }}/npm-public-registry.json"
       - uses: actions/upload-artifact@v7.0.2
         with:
@@ -142,8 +154,8 @@ jobs:
           if-no-files-found: error
 
   github-release:
-    if: github.event_name == 'push'
-    needs: npm-publish
+    if: "!cancelled() && github.event_name == 'push' && needs.distribution-admit.result == 'success' && needs.npm-publish.result == 'success' && needs.pypi-consumer.result == 'success'"
+    needs: [npm-publish, distribution-admit, pypi-consumer]
     runs-on: ubuntu-26.04
     permissions:
       contents: write
@@ -164,15 +176,15 @@ jobs:
       - name: Complete and admit the draft before making it public
         env:
           GH_TOKEN: ${{ github.token }}
-          BREWDOC_RELEASE_TAG: ${{ github.ref_name }}
-          BREWDOC_SOURCE_SHA: ${{ github.sha }}
+          BREWDOC_RELEASE_TAG: ${{ needs.distribution-admit.outputs.tag }}
+          BREWDOC_SOURCE_SHA: ${{ needs.distribution-admit.outputs.source_sha }}
         run: |
           uv run --no-project --python 3.12.14 python .github/workflows/release_assets.py stage --input "${{ runner.temp }}/release-assets" --tag "$BREWDOC_RELEASE_TAG" --source-sha "$BREWDOC_SOURCE_SHA"
           uv run --no-project --python 3.12.14 python .github/workflows/release_assets.py publish --input "${{ runner.temp }}/release-assets" --tag "$BREWDOC_RELEASE_TAG" --source-sha "$BREWDOC_SOURCE_SHA"
           uv run --no-project --python 3.12.14 python .github/workflows/release_assets.py verify-public --input "${{ runner.temp }}/release-assets" --tag "$BREWDOC_RELEASE_TAG" --source-sha "$BREWDOC_SOURCE_SHA"
 
   pypi-consumer:
-    if: github.event_name == 'push'
+    if: "!cancelled() && github.event_name == 'push' && needs.distribution-admit.result == 'success' && needs.publish.result == 'success'"
     needs: [publish, distribution-admit]
     runs-on: ubuntu-22.04
     timeout-minutes: 15
@@ -200,7 +212,7 @@ jobs:
           done
 
   public-consumer:
-    if: github.event_name == 'push'
+    if: "!cancelled() && github.event_name == 'push' && needs.github-release.result == 'success' && needs.pypi-consumer.result == 'success' && needs.distribution-admit.result == 'success'"
     needs: [github-release, pypi-consumer, distribution-admit]
     runs-on: ${{ matrix.os }}
     timeout-minutes: 20
@@ -223,8 +235,9 @@ jobs:
             archive: zip
     env:
       GH_TOKEN: ${{ github.token }}
-      BREWDOC_RELEASE_TAG: ${{ github.ref_name }}
-      BREWDOC_SOURCE_SHA: ${{ github.sha }}
+      BREWDOC_RELEASE_TAG: ${{ needs.distribution-admit.outputs.tag }}
+      BREWDOC_SOURCE_SHA: ${{ needs.distribution-admit.outputs.source_sha }}
+      BREWDOC_PACKAGE_CHECKOUT: ${{ github.workspace }}
       BREWDOC_ARCHIVE: brewdoc-${{ needs.distribution-admit.outputs.version }}-${{ matrix.target }}.${{ matrix.archive }}
     steps:
       - uses: actions/checkout@v7.0.1
@@ -236,14 +249,17 @@ jobs:
           python-version: "3.12.14"
           cache-suffix: ${{ runner.os }}-${{ runner.arch }}-uv0.12.21-py3.12.14-${{ hashFiles('uv.lock') }}
       - uses: actions/setup-node@v7.1.0
+        if: matrix.target != 'windows-x64'
         with:
           node-version: "24.21.0"
           package-manager-cache: false
       - uses: actions/cache@v6.1.0
+        if: matrix.target != 'windows-x64'
         with:
           path: ${{ runner.temp }}/npm-downloads/_cacache
           key: ${{ runner.os }}-${{ runner.arch }}-node24.21.0-npm12.2.0-${{ hashFiles('uv.lock', 'npm/**', '.github/workflows/build_npm.py') }}
       - name: Install pinned npm beside the selected Node runtime
+        if: matrix.target != 'windows-x64'
         shell: bash
         run: |
           BREWDOC_NPM_PREFIX=$(node -p 'const path = require("node:path"); path.resolve(path.dirname(process.execPath), process.platform === "win32" ? "." : "..")')
@@ -261,6 +277,7 @@ jobs:
           path: ${{ runner.temp }}/release-assets
           digest-mismatch: error
       - uses: actions/download-artifact@v8.0.2
+        if: matrix.target != 'windows-x64'
         with:
           name: release-npm
           path: ${{ runner.temp }}/release-npm
@@ -277,14 +294,16 @@ jobs:
         run: |
           mkdir -p "${{ runner.temp }}/public-downloads/${{ matrix.target }}"
           uv run --no-project --python 3.12.14 python .github/workflows/release_assets.py download-target --input "${{ runner.temp }}/release-assets" --tag "$BREWDOC_RELEASE_TAG" --source-sha "$BREWDOC_SOURCE_SHA" --target "${{ matrix.target }}" --output "${{ runner.temp }}/public-downloads/${{ matrix.target }}/$BREWDOC_ARCHIVE"
-          uv run --no-project --python 3.12.14 python .github/workflows/build_standalone.py verify --checkout "${{ github.workspace }}" --bundle "${{ runner.temp }}/release-package" --output "${{ runner.temp }}/public-evidence/${{ matrix.target }}" --target "${{ matrix.target }}" --archive "${{ runner.temp }}/public-downloads/${{ matrix.target }}/$BREWDOC_ARCHIVE" --smoke
+          uv run --no-project --python 3.12.14 python .github/workflows/build_standalone.py verify --checkout "$BREWDOC_PACKAGE_CHECKOUT" --bundle "${{ runner.temp }}/release-package" --output "${{ runner.temp }}/public-evidence/${{ matrix.target }}" --target "${{ matrix.target }}" --archive "${{ runner.temp }}/public-downloads/${{ matrix.target }}/$BREWDOC_ARCHIVE" --smoke
           cp "${{ runner.temp }}/public-downloads/${{ matrix.target }}/$BREWDOC_ARCHIVE.download.json" "${{ runner.temp }}/public-evidence/${{ matrix.target }}/"
       - uses: actions/download-artifact@v8.0.2
+        if: matrix.target != 'windows-x64'
         with:
           name: npm-public-registry
           path: ${{ runner.temp }}
           digest-mismatch: error
       - name: Verify normal public npm installation and npx execution
+        if: matrix.target != 'windows-x64'
         run: uv run --no-project --python 3.12.14 python .github/workflows/build_npm.py probe --input "${{ runner.temp }}/release-npm" --target "${{ matrix.target }}" --mode public --smoke --public-evidence "${{ runner.temp }}/npm-public-registry.json" --output "${{ runner.temp }}/public-evidence/${{ matrix.target }}/npm-public.json"
       - name: Preserve public download and consumer evidence
         if: always()
@@ -298,7 +317,7 @@ jobs:
           if-no-files-found: warn
 
   release-complete:
-    if: github.event_name == 'push'
+    if: "!cancelled() && github.event_name == 'push' && needs.public-consumer.result == 'success' && needs.pypi-consumer.result == 'success' && needs.distribution-admit.result == 'success'"
     needs: [public-consumer, pypi-consumer, distribution-admit]
     runs-on: ubuntu-22.04
     timeout-minutes: 15
@@ -306,8 +325,9 @@ jobs:
       contents: write
     env:
       GH_TOKEN: ${{ github.token }}
-      BREWDOC_RELEASE_TAG: ${{ github.ref_name }}
-      BREWDOC_SOURCE_SHA: ${{ github.sha }}
+      BREWDOC_RELEASE_TAG: ${{ needs.distribution-admit.outputs.tag }}
+      BREWDOC_SOURCE_SHA: ${{ needs.distribution-admit.outputs.source_sha }}
+      BREWDOC_PACKAGE_CHECKOUT: ${{ github.workspace }}
     steps:
       - uses: actions/checkout@v7.0.1
         with:
@@ -345,8 +365,9 @@ jobs:
       - name: Admit public channels before generating final installation instructions
         run: |
           uv run --no-project --python 3.12.14 python .github/workflows/release_assets.py admit-public --input "${{ runner.temp }}/release-assets" --tag "$BREWDOC_RELEASE_TAG" --source-sha "$BREWDOC_SOURCE_SHA" --evidence "${{ runner.temp }}/public-evidence" --output "${{ runner.temp }}/public-acceptance.json"
-          uv run --no-project --python 3.12.14 python .github/workflows/release_guide.py render --checkout "${{ github.workspace }}" --phase public --native-manifest "${{ runner.temp }}/release-assets/binaries.json" --npm-manifest "${{ runner.temp }}/release-assets/npm-manifest.json" --availability "${{ runner.temp }}/public-acceptance.json" --output "${{ runner.temp }}/public-body.md"
-          uv run --no-project --python 3.12.14 python .github/workflows/release_assets.py finalize --input "${{ runner.temp }}/release-assets" --tag "$BREWDOC_RELEASE_TAG" --source-sha "$BREWDOC_SOURCE_SHA" --evidence "${{ runner.temp }}/public-evidence" --body "${{ runner.temp }}/public-body.md"
+          uv run --no-project --python 3.12.14 python .github/workflows/release_guide.py render --checkout "$BREWDOC_PACKAGE_CHECKOUT" --phase public --native-manifest "${{ runner.temp }}/release-assets/binaries.json" --npm-manifest "${{ runner.temp }}/release-assets/npm-manifest.json" --availability "${{ runner.temp }}/public-acceptance.json" --output "${{ runner.temp }}/public-body.md"
+      - name: Finalize normal tag-release instructions after public admission
+        run: uv run --no-project --python 3.12.14 python .github/workflows/release_assets.py finalize --input "${{ runner.temp }}/release-assets" --tag "$BREWDOC_RELEASE_TAG" --source-sha "$BREWDOC_SOURCE_SHA" --evidence "${{ runner.temp }}/public-evidence" --body "${{ runner.temp }}/public-body.md"
       - uses: actions/upload-artifact@v7.0.2
         with:
           name: release-public-acceptance