putitoutthere 0.2.29 → 0.2.31

package/dist/preflight.js

@@ -21,9 +21,10 @@
  * Issue #14, #280.
  */
 import { readFileSync } from 'node:fs';
-import { dirname, join, parse as parsePath } from 'node:path';
+import { dirname, isAbsolute, join, parse as parsePath, resolve } from 'node:path';
 import { parse as parseToml } from 'smol-toml';
 import { ErrorCodes } from './error-codes.js';
+import { expandDirGlob } from './glob.js';
 // Per-kind accepted env var names, primary first. `checkAuth` scans left
 // to right and reports the first that has a non-empty value. npm takes
 // two names because ecosystems have split on the convention:
@@ -60,8 +61,9 @@ export function checkAuth(packages) {
 }
 export function requireAuth(packages) {
     const status = checkAuth(packages);
-    if (status.ok)
+    if (status.ok) {
         return;
+    }
     const missing = status.results.filter((r) => r.via === 'missing');
     const lines = missing.map((r) => {
         const vars = r.acceptedEnvVars.join(' or ');
@@ -100,8 +102,9 @@ const REPOSITORY_DOC_POINTER = 'https://github.com/thekevinscott/putitoutthere#k
 export function checkProvenanceMetadata(packages) {
     const findings = [];
     for (const p of packages) {
-        if (p.kind !== 'npm')
+        if (p.kind !== 'npm') {
             continue;
+        }
         const pkgJsonPath = join(p.path, 'package.json');
         let raw;
         try {
@@ -128,8 +131,9 @@ export function checkProvenanceMetadata(packages) {
     return findings;
 }
 function hasNonEmptyRepository(value) {
-    if (typeof value === 'string')
+    if (typeof value === 'string') {
         return value.trim().length > 0;
+    }
     if (value !== null && typeof value === 'object') {
         const url = value.url;
         return typeof url === 'string' && url.trim().length > 0;
@@ -149,8 +153,9 @@ function hasNonEmptyRepository(value) {
  */
 export function requireProvenanceMetadata(packages) {
     const findings = checkProvenanceMetadata(packages);
-    if (findings.length === 0)
+    if (findings.length === 0) {
         return;
+    }
     const lines = [
         `[${ErrorCodes.NPM_MISSING_REPOSITORY}] npm publish requires a non-empty \`repository\` field in package.json.`,
         '',
@@ -186,8 +191,9 @@ const CARGO_DOC_POINTER = 'https://doc.rust-lang.org/cargo/reference/manifest.ht
 export function checkCratesMetadata(packages) {
     const findings = [];
     for (const p of packages) {
-        if (p.kind !== 'crates')
+        if (p.kind !== 'crates') {
             continue;
+        }
         const cargoTomlPath = join(p.path, 'Cargo.toml');
         let raw;
         try {
@@ -219,8 +225,9 @@ export function checkCratesMetadata(packages) {
         const license = resolveInherited(pkgTable.license, wsPkgTable, 'license');
         const licenseFile = resolveInherited(pkgTable['license-file'], wsPkgTable, 'license-file');
         const missing = [];
-        if (!nonEmptyString(description))
+        if (!nonEmptyString(description)) {
             missing.push('description');
+        }
         if (!nonEmptyString(license) && !nonEmptyString(licenseFile)) {
             missing.push('license');
         }
@@ -261,8 +268,9 @@ const PYPI_VERSION_DOC_POINTER = 'https://thekevinscott.github.io/putitoutthere/
 export function checkPypiVersionSource(packages) {
     const findings = [];
     for (const p of packages) {
-        if (p.kind !== 'pypi')
+        if (p.kind !== 'pypi') {
             continue;
+        }
         const pyprojectPath = join(p.path, 'pyproject.toml');
         let raw;
         try {
@@ -279,10 +287,12 @@ export function checkPypiVersionSource(packages) {
             continue;
         }
         const project = parsed.project;
-        if (project === undefined)
+        if (project === undefined) {
             continue;
-        if (declaresDynamicVersion(project))
+        }
+        if (declaresDynamicVersion(project)) {
             continue;
+        }
         if (typeof project.version === 'string') {
             findings.push({ package: p.name, pyprojectPath });
         }
@@ -306,8 +316,9 @@ function declaresDynamicVersion(project) {
  */
 export function requirePypiVersionSource(packages) {
     const findings = checkPypiVersionSource(packages);
-    if (findings.length === 0)
+    if (findings.length === 0) {
         return;
+    }
     const lines = [
         `[${ErrorCodes.PYPI_STATIC_VERSION}] pyproject.toml must declare \`[project].dynamic = ["version"]\` instead of a static \`[project].version = "..."\` literal.`,
         '',
@@ -346,31 +357,17 @@ function readWorkspacePackageTable(crateDir) {
     let dir = dirname(crateDir);
     while (dir && dir !== rootMarker) {
         const manifest = join(dir, 'Cargo.toml');
-        let raw;
-        try {
-            raw = readFileSync(manifest, 'utf8');
-        }
-        catch {
-            const parent = dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-            continue;
-        }
         let parsed;
         try {
-            parsed = parseToml(raw);
+            parsed = parseToml(readFileSync(manifest, 'utf8'));
         }
         catch {
-            // Cargo will surface the parser error; just skip this manifest
-            // for workspace lookup so we don't crash on a malformed parent.
-            const parent = dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-            continue;
+            // Missing or malformed Cargo.toml at this level — skip it and keep
+            // walking up. (Cargo surfaces a real parse error itself; we just
+            // don't crash the workspace lookup on an unreadable ancestor.)
+            parsed = undefined;
         }
-        if (parsed.workspace !== undefined) {
+        if (parsed !== undefined && parsed.workspace !== undefined) {
             const ws = parsed.workspace;
             const wsPkg = ws.package;
             if (wsPkg !== undefined && typeof wsPkg === 'object') {
@@ -379,9 +376,13 @@ function readWorkspacePackageTable(crateDir) {
             // Workspace root found, but no shared metadata — stop walking.
             return undefined;
         }
+        // Advance one directory toward the filesystem root. The fixpoint
+        // guard terminates the walk for relative crate paths, where
+        // dirname() settles on '.' rather than reaching rootMarker.
         const parent = dirname(dir);
-        if (parent === dir)
+        if (parent === dir) {
             break;
+        }
         dir = parent;
     }
     return undefined;
@@ -399,8 +400,9 @@ function readWorkspacePackageTable(crateDir) {
  */
 export function requireCratesMetadata(packages) {
     const findings = checkCratesMetadata(packages);
-    if (findings.length === 0)
+    if (findings.length === 0) {
         return;
+    }
     const lines = [
         `[${ErrorCodes.CRATES_MISSING_METADATA}] cargo publish requires the following Cargo.toml [package] fields: description, and license (or license-file).`,
         '',
@@ -412,4 +414,684 @@ export function requireCratesMetadata(packages) {
     lines.push('', 'Why: crates.io rejects publish with `400 Bad Request: missing or empty', 'metadata fields: ...` after cargo publish has compiled the crate and every', 'transitive dep — wasting the full publish job on a precondition checkable', 'in milliseconds.', '', 'Fix: add the missing fields to each Cargo.toml. Example:', '', '  [package]', '  description = "One-line summary of what the crate does."', '  license = "MIT OR Apache-2.0"', '', `See ${CARGO_DOC_POINTER}.`);
     throw new Error(lines.join('\n'));
 }
+// Each PYPI_BUILD mode maps to the prefix(es) the upstream build
+// backend identifier should start with. The check is intentionally
+// loose: maturin / setuptools / hatchling all ship multiple backend
+// identifiers across versions, and the failure mode this gate exists
+// to catch is the *kind* mismatch (e.g. `build = "maturin"` but the
+// pyproject declares hatchling), not a backend-version drift.
+const PYPI_BACKEND_PREFIX = {
+    maturin: ['maturin'],
+    setuptools: ['setuptools'],
+    hatch: ['hatchling', 'hatch'],
+};
+export function checkPyprojectShape(packages) {
+    const findings = [];
+    for (const p of packages) {
+        if (p.kind !== 'pypi') {
+            continue;
+        }
+        const pyprojectPath = join(p.path, 'pyproject.toml');
+        let raw;
+        try {
+            raw = readFileSync(pyprojectPath, 'utf8');
+        }
+        catch {
+            // Missing pyproject.toml is a different failure surface (the
+            // build tool surfaces it with a clear error, and `check.ts`
+            // catches it at PR time). Skip.
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseToml(raw);
+        }
+        catch {
+            // Malformed TOML — let the build tool surface its own diagnostic.
+            continue;
+        }
+        const project = (parsed.project ?? {});
+        const buildSystem = (parsed['build-system'] ?? {});
+        const tool = (parsed.tool ?? {});
+        const expectedName = p.pypi ?? p.name;
+        // PYPI_NAME_MISMATCH
+        if (typeof project.name === 'string' && project.name !== expectedName) {
+            findings.push({
+                package: p.name,
+                pyprojectPath,
+                code: 'PIOT_PYPI_NAME_MISMATCH',
+                detail: `[project].name = "${project.name}" but configured name is "${expectedName}"`,
+            });
+        }
+        // PYPI_BUILD_BACKEND_MISMATCH — only fires when the field is set
+        // *and* disagrees. A missing [build-system] table is technically
+        // allowed (pip falls back to setuptools); flagging it here would
+        // create noise on packages this gate is not meant to police.
+        const backend = buildSystem['build-backend'];
+        if (typeof backend === 'string' && backend.length > 0) {
+            const allowed = PYPI_BACKEND_PREFIX[p.build];
+            const ok = allowed.some((prefix) => backend.startsWith(prefix));
+            if (!ok) {
+                findings.push({
+                    package: p.name,
+                    pyprojectPath,
+                    code: 'PIOT_PYPI_BUILD_BACKEND_MISMATCH',
+                    detail: `[build-system].build-backend = "${backend}" but build = "${p.build}" expects ${allowed.map((a) => `"${a}*"`).join(' or ')}`,
+                });
+            }
+        }
+        // PYPI_DYNAMIC_VERSION_NO_BACKEND — only checks setuptools / hatch.
+        // Maturin sources its version from Cargo.toml's [package].version
+        // when `dynamic = ["version"]`, so requiring a `[tool.hatch.version]`
+        // or `[tool.setuptools_scm]` block would surface false positives on
+        // every maturin pypi package.
+        if (p.build !== 'maturin') {
+            const dynamic = project.dynamic;
+            const dynamicHasVersion = Array.isArray(dynamic) && dynamic.some((v) => v === 'version');
+            if (dynamicHasVersion) {
+                const hatchVersion = (tool.hatch ?? {}).version;
+                const setuptoolsScm = tool.setuptools_scm;
+                const hasHatchSource = typeof hatchVersion === 'object' && hatchVersion !== null;
+                const hasSetuptoolsScm = typeof setuptoolsScm === 'object' && setuptoolsScm !== null;
+                if (!hasHatchSource && !hasSetuptoolsScm) {
+                    findings.push({
+                        package: p.name,
+                        pyprojectPath,
+                        code: 'PIOT_PYPI_DYNAMIC_VERSION_NO_BACKEND',
+                        detail: '[project].dynamic includes "version" but neither [tool.hatch.version] nor [tool.setuptools_scm] is present; the build backend has no way to compute a version',
+                    });
+                }
+            }
+        }
+        // PYPI_MATURIN_INCLUDE_MISSING
+        if (p.bundle_cli !== undefined) {
+            const stageTo = p.bundle_cli.stage_to;
+            const maturin = (tool.maturin ?? {});
+            const include = maturin.include;
+            const includes = Array.isArray(include) ? include : [];
+            if (!maturinIncludeCovers(includes, stageTo)) {
+                findings.push({
+                    package: p.name,
+                    pyprojectPath,
+                    code: 'PIOT_PYPI_MATURIN_INCLUDE_MISSING',
+                    detail: `bundle_cli.stage_to = "${stageTo}" is not covered by any [tool.maturin].include entry; the cross-compiled binary will not be packed into the wheel`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+function maturinIncludeCovers(includes, stageTo) {
+    for (const entry of includes) {
+        const path = extractIncludePath(entry);
+        if (path === undefined) {
+            continue;
+        }
+        // Strip trailing glob segments so `a/bin/*` and `a/bin/**` both
+        // cover `a/bin`.
+        const normalized = path.replace(/\/?\*+$/, '').replace(/\/$/, '');
+        if (normalized === stageTo) {
+            return true;
+        }
+        if (normalized.length > 0 && stageTo.startsWith(normalized + '/')) {
+            return true;
+        }
+        if (path.startsWith(stageTo + '/') || path === stageTo) {
+            return true;
+        }
+    }
+    return false;
+}
+function extractIncludePath(entry) {
+    if (typeof entry === 'string') {
+        return entry;
+    }
+    if (typeof entry === 'object' && entry !== null) {
+        const path = entry.path;
+        if (typeof path === 'string') {
+            return path;
+        }
+    }
+    return undefined;
+}
+export function requirePyprojectShape(packages) {
+    const findings = checkPyprojectShape(packages);
+    if (findings.length === 0) {
+        return;
+    }
+    const lines = [
+        'Pre-flight pyproject.toml shape check failed:',
+        '',
+    ];
+    for (const f of findings) {
+        lines.push(`  [${f.code}] ${f.package}: ${f.pyprojectPath}`);
+        lines.push(`    ${f.detail}`);
+    }
+    lines.push('', 'Why: these mismatches would otherwise surface 10-20 minutes into a release run', 'when the build backend (maturin / setuptools / hatchling) finally tripped on them.', 'Fix the pyproject.toml + putitoutthere.toml fields in this list, then re-run.');
+    throw new Error(lines.join('\n'));
+}
+export function checkCargoShape(packages, options = {}) {
+    const findings = [];
+    const cwd = options.cwd ?? process.cwd();
+    for (const p of packages) {
+        if (p.kind === 'crates') {
+            collectCratesPackageFindings(p, cwd, findings);
+        }
+        else if (p.kind === 'pypi' && p.bundle_cli !== undefined) {
+            collectBundleCliCrateFindings(p, p.bundle_cli, cwd, findings);
+        }
+    }
+    return findings;
+}
+function collectCratesPackageFindings(p, cwd, findings) {
+    const cargoTomlPath = join(p.path, 'Cargo.toml');
+    const parsed = readToml(cargoTomlPath);
+    if (parsed === null) {
+        return;
+    }
+    const pkgTable = (parsed.package ?? {});
+    const expectedName = p.crate ?? p.name;
+    // CRATES_NAME_MISMATCH
+    if (typeof pkgTable.name === 'string' && pkgTable.name !== expectedName) {
+        findings.push({
+            package: p.name,
+            cargoTomlPath,
+            code: 'PIOT_CRATES_NAME_MISMATCH',
+            detail: `[package].name = "${pkgTable.name}" but configured name is "${expectedName}"`,
+        });
+    }
+    // CRATES_FEATURE_NOT_DECLARED — only when features is set on the
+    // configured package.
+    if (p.features !== undefined && p.features.length > 0) {
+        const declared = declaredFeatures(parsed);
+        const missing = p.features.filter((f) => !declared.has(f));
+        if (missing.length > 0) {
+            findings.push({
+                package: p.name,
+                cargoTomlPath,
+                code: 'PIOT_CRATES_FEATURE_NOT_DECLARED',
+                detail: `features = ${JSON.stringify(p.features)} references undeclared feature(s) ${JSON.stringify(missing)}; Cargo.toml [features] declares ${JSON.stringify([...declared])}`,
+            });
+        }
+    }
+    // CRATES_WORKSPACE_VERSION_MISMATCH
+    if (versionInheritsWorkspace(pkgTable.version)) {
+        if (!workspaceVersionDeclared(cargoTomlPath, cwd)) {
+            findings.push({
+                package: p.name,
+                cargoTomlPath,
+                code: 'PIOT_CRATES_WORKSPACE_VERSION_MISMATCH',
+                detail: '[package].version.workspace = true but no ancestor Cargo.toml declares [workspace.package].version',
+            });
+        }
+    }
+}
+function collectBundleCliCrateFindings(p, bundleCli, cwd, findings) {
+    const cratePathAbs = isAbsolute(bundleCli.crate_path)
+        ? bundleCli.crate_path
+        : resolve(cwd, bundleCli.crate_path);
+    const cargoTomlPath = join(cratePathAbs, 'Cargo.toml');
+    const parsed = readToml(cargoTomlPath);
+    if (parsed === null) {
+        return;
+    }
+    // CRATES_MISSING_BIN
+    const declaredBins = readDeclaredBinNames(parsed, cargoTomlPath);
+    if (!declaredBins.includes(bundleCli.bin)) {
+        findings.push({
+            package: p.name,
+            cargoTomlPath,
+            code: 'PIOT_CRATES_MISSING_BIN',
+            detail: `bundle_cli.bin = "${bundleCli.bin}" is not declared as a [[bin]] in ${cargoTomlPath}; declared bins: ${declaredBins.length === 0 ? '(none)' : declaredBins.join(', ')}`,
+        });
+    }
+    // CRATES_FEATURE_NOT_DECLARED — bundle_cli.features path
+    if (bundleCli.features.length > 0) {
+        const declared = declaredFeatures(parsed);
+        const missing = bundleCli.features.filter((f) => !declared.has(f));
+        if (missing.length > 0) {
+            findings.push({
+                package: p.name,
+                cargoTomlPath,
+                code: 'PIOT_CRATES_FEATURE_NOT_DECLARED',
+                detail: `bundle_cli.features = ${JSON.stringify(bundleCli.features)} references undeclared feature(s) ${JSON.stringify(missing)}; Cargo.toml [features] declares ${JSON.stringify([...declared])}`,
+            });
+        }
+    }
+}
+function readToml(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        return parseToml(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function declaredFeatures(cargoToml) {
+    const features = (cargoToml.features ?? {});
+    return new Set(Object.keys(features));
+}
+function readDeclaredBinNames(cargoToml, cargoTomlPath) {
+    const result = collectBinsFromManifest(cargoToml);
+    // Workspace manifests delegate [[bin]] declarations to member crates
+    // (#337). `cargo build --bin X` from anywhere in the workspace
+    // resolves X transparently, so a check that only reads the
+    // workspace-root manifest reports bins as missing even when they
+    // exist in a member.
+    for (const memberManifest of workspaceMemberManifests(cargoToml, cargoTomlPath)) {
+        const memberParsed = readToml(memberManifest);
+        if (memberParsed === null) {
+            continue;
+        }
+        for (const b of collectBinsFromManifest(memberParsed)) {
+            if (!result.includes(b)) {
+                result.push(b);
+            }
+        }
+    }
+    return result;
+}
+function workspaceMemberManifests(cargoToml, cargoTomlPath) {
+    const workspace = cargoToml.workspace;
+    if (typeof workspace !== 'object' || workspace === null) {
+        return [];
+    }
+    const members = workspace.members;
+    if (!Array.isArray(members)) {
+        return [];
+    }
+    const workspaceDir = dirname(cargoTomlPath);
+    const out = [];
+    for (const m of members) {
+        if (typeof m === 'string') {
+            // `members` entries are globs (`packages/*`); expand them against
+            // the filesystem the way cargo does so a member crate's [[bin]] is
+            // found even when the workspace declares its members with a pattern.
+            for (const memberDir of expandDirGlob(workspaceDir, m)) {
+                out.push(join(memberDir, 'Cargo.toml'));
+            }
+        }
+    }
+    return out;
+}
+function collectBinsFromManifest(cargoToml) {
+    const result = [];
+    const bins = cargoToml.bin;
+    if (Array.isArray(bins)) {
+        for (const entry of bins) {
+            if (typeof entry === 'object' && entry !== null) {
+                const name = entry.name;
+                if (typeof name === 'string') {
+                    result.push(name);
+                }
+            }
+        }
+    }
+    // Cargo's implicit-binary rule: a crate without any [[bin]] table
+    // ships a binary named after `[package].name` when `src/main.rs`
+    // exists. We can't observe the filesystem here without extra reads,
+    // but treating the implicit name as a candidate avoids false
+    // positives on the common single-bin shape.
+    if (result.length === 0) {
+        const pkg = cargoToml.package;
+        if (pkg && typeof pkg.name === 'string') {
+            result.push(pkg.name);
+        }
+    }
+    return result;
+}
+function versionInheritsWorkspace(version) {
+    return (typeof version === 'object' &&
+        version !== null &&
+        version.workspace === true);
+}
+function workspaceVersionDeclared(cargoTomlPath, cwd) {
+    // Walk parents until we find a Cargo.toml carrying a [workspace]
+    // table; bound the walk at `cwd` so we never escape the repo.
+    const cwdAbs = resolve(cwd);
+    let cur = dirname(resolve(cargoTomlPath));
+    // Step out of the package's own directory first — the package's own
+    // Cargo.toml never declares its own workspace root.
+    cur = dirname(cur);
+    while (true) {
+        const candidate = join(cur, 'Cargo.toml');
+        const parsed = readToml(candidate);
+        if (parsed !== null) {
+            const workspace = (parsed.workspace ?? null);
+            if (workspace !== null) {
+                const wsPkg = (workspace.package ?? {});
+                return nonEmptyString(wsPkg.version);
+            }
+        }
+        if (cur === cwdAbs || cur === dirname(cur)) {
+            return false;
+        }
+        cur = dirname(cur);
+    }
+}
+// User-facing pointer for the manifest-repository-URL recipe. Surfaced
+// verbatim in the thrown error so the consumer has a copy/paste fix
+// instead of a code-search target.
+const REPO_URL_DOC_POINTER = 'https://thekevinscott.github.io/putitoutthere/guide/repository-url';
+export function checkRepoUrlMatch(packages, options = {}) {
+    const expectedOwnerRepo = normalizeOwnerRepo(options.githubRepository);
+    if (expectedOwnerRepo === null) {
+        return [];
+    }
+    const findings = [];
+    for (const p of packages) {
+        const declared = readDeclaredRepoUrl(p);
+        if (declared === null) {
+            continue;
+        }
+        const declaredOwnerRepo = parseOwnerRepo(declared.url);
+        if (declaredOwnerRepo === null) {
+            continue;
+        }
+        if (declaredOwnerRepo.toLowerCase() === expectedOwnerRepo.toLowerCase()) {
+            continue;
+        }
+        findings.push({
+            package: p.name,
+            manifestPath: declared.manifestPath,
+            declaredOwnerRepo,
+            expectedOwnerRepo,
+            declaredUrl: declared.url,
+        });
+    }
+    return findings;
+}
+export function requireRepoUrlMatch(packages, options = {}) {
+    const findings = checkRepoUrlMatch(packages, options);
+    if (findings.length === 0) {
+        return;
+    }
+    const lines = [
+        `[${ErrorCodes.REPO_URL_MISMATCH}] manifest repository URL does not match GITHUB_REPOSITORY.`,
+        '',
+        'Failing packages:',
+    ];
+    for (const f of findings) {
+        lines.push(`  - ${f.package}: ${f.manifestPath}`, `      declared:  ${f.declaredOwnerRepo}  (${f.declaredUrl})`, `      expected:  ${f.expectedOwnerRepo}  (from GITHUB_REPOSITORY)`);
+    }
+    lines.push('', 'Why: npm verifies `package.json#repository.url` against the OIDC source claim', 'before accepting a `--provenance` publish and rejects mismatches with a 422', 'after the artifact has already been uploaded. crates.io and PyPI carry the same', 'risk on their trusted-publisher paths.', '', 'Fix: either update the manifest URL to match the GitHub repository this workflow', 'is running from, or rename the GitHub repository so the slugs line up. Run the', 'release again once the manifest and the repo agree.', '', `See ${REPO_URL_DOC_POINTER}.`);
+    throw new Error(lines.join('\n'));
+}
+function readDeclaredRepoUrl(p) {
+    switch (p.kind) {
+        case 'npm': {
+            const manifestPath = join(p.path, 'package.json');
+            const parsed = readJson(manifestPath);
+            if (parsed === null) {
+                return null;
+            }
+            const repository = parsed.repository;
+            if (typeof repository === 'string' && repository.trim().length > 0) {
+                return { url: repository.trim(), manifestPath };
+            }
+            if (repository !== null && typeof repository === 'object') {
+                const url = repository.url;
+                if (typeof url === 'string' && url.trim().length > 0) {
+                    return { url: url.trim(), manifestPath };
+                }
+            }
+            return null;
+        }
+        case 'crates': {
+            const manifestPath = join(p.path, 'Cargo.toml');
+            const parsed = readTomlDoc(manifestPath);
+            if (parsed === null) {
+                return null;
+            }
+            const pkgTable = (parsed.package ?? {});
+            const repo = pkgTable.repository;
+            if (typeof repo === 'string' && repo.trim().length > 0) {
+                return { url: repo.trim(), manifestPath };
+            }
+            return null;
+        }
+        case 'pypi': {
+            const manifestPath = join(p.path, 'pyproject.toml');
+            const parsed = readTomlDoc(manifestPath);
+            if (parsed === null) {
+                return null;
+            }
+            const project = (parsed.project ?? {});
+            const urls = (project.urls ?? {});
+            // PEP 621 leaves the key casing to the project, and PyPI normalises
+            // common labels case-insensitively. Accept the canonical "Repository"
+            // first and fall back to common synonyms (source-code repos vs.
+            // homepage links) so a project picking any reasonable label still
+            // gets the check.
+            for (const key of ['Repository', 'repository', 'Source', 'source', 'Homepage', 'homepage']) {
+                const candidate = urls[key];
+                if (typeof candidate === 'string' && candidate.trim().length > 0) {
+                    return { url: candidate.trim(), manifestPath };
+                }
+            }
+            return null;
+        }
+    }
+}
+function readJson(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function readTomlDoc(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        return parseToml(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeOwnerRepo(value) {
+    if (value === undefined) {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    // Tolerate accidental wrapping (e.g. `https://github.com/owner/repo`
+    // landed in the GITHUB_REPOSITORY env var by misconfiguration); the
+    // GHA-provided value is always `owner/repo` so this is defence in
+    // depth, not a documented surface.
+    const slugMatch = trimmed.match(/^([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/);
+    if (slugMatch) {
+        return `${slugMatch[1]}/${slugMatch[2]}`;
+    }
+    return parseOwnerRepo(trimmed);
+}
+// Recognises the canonical GitHub URL shapes the npm / cargo / hatch
+// ecosystems serialise into manifests:
+//   - git+https://github.com/owner/repo(.git)?
+//   - https://github.com/owner/repo(.git)?(/)?
+//   - http://github.com/owner/repo(.git)?(/)?
+//   - git@github.com:owner/repo(.git)?
+//   - ssh://git@github.com/owner/repo(.git)?
+// Non-github hosts return null; the check skips those packages rather
+// than false-positive on legitimately-hosted forks (provenance still
+// catches them at publish time).
+function parseOwnerRepo(url) {
+    const stripped = url.trim().replace(/^git\+/i, '');
+    const match = stripped.match(/github\.com[/:]([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+?)(?:\.git)?\/?$/);
+    if (match === null) {
+        return null;
+    }
+    return `${match[1]}/${match[2]}`;
+}
+const REPO_VISIBILITY_DOC_POINTER = 'https://thekevinscott.github.io/putitoutthere/guide/public-repo';
+export async function checkRepoPublic(options = {}) {
+    const githubRepository = options.githubRepository?.trim();
+    if (githubRepository === undefined || githubRepository.length === 0) {
+        return null;
+    }
+    // Fall back to the raw value if normalization fails; the API call
+    // will 404 and the check will report `not-found-or-private`, which
+    // is the right diagnosis for a malformed slug we can't disambiguate.
+    const apiSlug = normalizeOwnerRepo(githubRepository) ?? githubRepository;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const headers = {
+        accept: 'application/vnd.github+json',
+        'user-agent': 'putitoutthere',
+    };
+    if (options.githubToken !== undefined && options.githubToken.length > 0) {
+        headers.authorization = `Bearer ${options.githubToken}`;
+    }
+    const url = `https://api.github.com/repos/${apiSlug}`;
+    let res;
+    try {
+        res = await fetchImpl(url, { method: 'GET', headers });
+    }
+    catch (err) {
+        // A network failure says nothing about repository visibility.
+        // Treat it as indeterminate rather than blocking the release.
+        warnIndeterminate(apiSlug, `request failed (${err.message})`);
+        return null;
+    }
+    if (res.status === 404) {
+        return { githubRepository: apiSlug, reason: 'not-found-or-private' };
+    }
+    if (res.status === 200) {
+        const body = (await res.json());
+        const isPrivate = body.private === true ||
+            (typeof body.visibility === 'string' && body.visibility !== 'public');
+        if (isPrivate) {
+            return { githubRepository: apiSlug, reason: 'private' };
+        }
+        return null;
+    }
+    // Any other status (most commonly a 403 from an unauthenticated
+    // rate-limited call, or a transient 5xx) tells us nothing about
+    // visibility. Blocking the publish on "we couldn't reach the API"
+    // is the kind of release surprise this engine exists to prevent —
+    // treat it as indeterminate and non-fatal, with a visible warning.
+    warnIndeterminate(apiSlug, `GitHub API returned ${res.status}`);
+    return null;
+}
+function warnIndeterminate(apiSlug, detail) {
+    process.stdout.write(`::warning::repository visibility check skipped for ${apiSlug}: ${detail}\n`);
+}
+export async function requireRepoPublic(options = {}) {
+    const finding = await checkRepoPublic(options);
+    if (finding === null) {
+        return;
+    }
+    const lines = [
+        `[${ErrorCodes.REPO_PRIVATE}] refusing to publish from a private GitHub repository (${finding.githubRepository}).`,
+        '',
+        finding.reason === 'private'
+            ? 'The GitHub API reports this repository as private.'
+            : 'The GitHub API returned 404 for this repository slug — either the repo is private and the configured token lacks access, or the slug does not exist.',
+        '',
+        'Why: npm provenance attestations embed a public source-ref pointer that',
+        'consumers cannot dereference on a private repo, and the same source-visibility',
+        'expectation underpins the trusted-publisher story across the registries we',
+        'publish to. Publishing from a private repo silently degrades every consumer\'s',
+        'ability to verify the artifact.',
+        '',
+        'Fix: make the repository public before publishing, or unset the release',
+        'trigger until visibility flips. See',
+        `  ${REPO_VISIBILITY_DOC_POINTER}`,
+        'for the trusted-publisher rationale and the registry-specific failure modes',
+        'this check exists to prevent.',
+    ];
+    throw new Error(lines.join('\n'));
+}
+export function requireCargoShape(packages, options = {}) {
+    const findings = checkCargoShape(packages, options);
+    if (findings.length === 0) {
+        return;
+    }
+    const lines = [
+        'Pre-flight Cargo.toml shape check failed:',
+        '',
+    ];
+    for (const f of findings) {
+        lines.push(`  [${f.code}] ${f.package}: ${f.cargoTomlPath}`);
+        lines.push(`    ${f.detail}`);
+    }
+    lines.push('', 'Why: these mismatches would otherwise surface mid-`cargo build` or mid-`cargo', 'publish` after the verification build has compiled the crate and every transitive', 'dep — wasting the publish job on a precondition checkable in milliseconds.', 'Fix the Cargo.toml + putitoutthere.toml fields in this list, then re-run.');
+    throw new Error(lines.join('\n'));
+}
+export function checkPackageJsonShape(packages) {
+    const findings = [];
+    for (const p of packages) {
+        if (p.kind !== 'npm') {
+            continue;
+        }
+        const packageJsonPath = join(p.path, 'package.json');
+        let raw;
+        try {
+            raw = readFileSync(packageJsonPath, 'utf8');
+        }
+        catch {
+            // Missing package.json is a different failure surface:
+            // `checkProvenanceMetadata` reports it, and `check.ts` surfaces it
+            // at PR time. Skip.
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // Malformed package.json — let the publish step surface its own
+            // diagnostic. This check only owns the `name` field.
+            continue;
+        }
+        const expectedName = p.npm ?? p.name;
+        if (typeof parsed.name === 'string' && parsed.name !== expectedName) {
+            findings.push({
+                package: p.name,
+                packageJsonPath,
+                code: 'PIOT_NPM_NAME_MISMATCH',
+                detail: `name = "${parsed.name}" but configured name is "${expectedName}"`,
+            });
+        }
+    }
+    return findings;
+}
+export function requirePackageJsonShape(packages) {
+    const findings = checkPackageJsonShape(packages);
+    if (findings.length === 0) {
+        return;
+    }
+    const lines = [
+        'Pre-flight package.json shape check failed:',
+        '',
+    ];
+    for (const f of findings) {
+        lines.push(`  [${f.code}] ${f.package}: ${f.packageJsonPath}`);
+        lines.push(`    ${f.detail}`);
+    }
+    lines.push('', 'Why: `npm publish` packs the `name` from package.json, but the engine\'s', 'idempotency probe (`npm view <name>`) and the tag/URL bookkeeping use the', 'configured [[package]].name (or the `npm` override) — a divergence breaks', 'idempotency and can publish under an unexpected name.', 'Fix the package.json `name` or set the `npm` override in putitoutthere.toml, then re-run.');
+    throw new Error(lines.join('\n'));
+}
 //# sourceMappingURL=preflight.js.map