@vincentt-xr/cli 0.17.0 → 0.18.0

package/dist/publish/copy.js

@@ -12,6 +12,7 @@
 // NEVER PRINTED, at any point, in any state: the project id, the org id, the
 // uploadId, the PAT, any presigned URL or fragment of one, the bucket, any S3
 // key, or a per-file upload log.
+import { escapeControl } from "../lib/terminalText.js";
 /** The only horizontal rules in any f4 output. They exist here and nowhere else. */
 const RULE = "  ─────────────────────────────────────────────────────────────────────";
 const LABELS = {
@@ -84,7 +85,7 @@ export function relativeTime(iso, now) {
  * A FINDING IS NEVER A COUNT. No "2 issues found", no summary line, and no exit
  * code that varies with findings.
  */
-export function findingLines(byFile, withSubtitle) {
+export function findingLines(byFile, withSubtitle, folder = "dist/") {
     const out = [];
     out.push(withSubtitle
         ? "  Link preview  (what Slack, iMessage and WhatsApp will show)"
@@ -99,7 +100,7 @@ export function findingLines(byFile, withSubtitle) {
             out.push("");
         }
         for (const finding of file.findings) {
-            out.push(...findingLine(finding, file.file, multi));
+            out.push(...findingLine(finding, file.file, multi, folder));
         }
         if (multi)
             out.push("");
@@ -108,7 +109,7 @@ export function findingLines(byFile, withSubtitle) {
         out.push("");
     return out;
 }
-function findingLine(f, file, indented) {
+function findingLine(f, file, indented, folder) {
     const pad = indented ? "  " : "";
     const label = LABELS[f.field].padEnd(LABEL_WIDTH);
     // The file · tag sits on a continuation line indented to the VALUE column, so
@@ -128,7 +129,7 @@ function findingLine(f, file, indented) {
         case "likely-default":
             return [`${pad}    !  ${label} looks unset: "${truncate(f.value ?? "")}"`, detail];
         case "dead-image":
-            return [`${pad}    ✗  ${label} ${f.value} is not in dist/`, detail];
+            return [`${pad}    ✗  ${label} ${f.value} is not in ${folder}`, detail];
     }
 }
 /**
@@ -140,13 +141,36 @@ function findingLine(f, file, indented) {
 export function nothingBlocksYou() {
     return [
         "    Scrapers don't run JavaScript, so these have to be in the HTML your",
-        "    build produces. Fix them in your source and publish again — or publish",
+        "    build produces. Fix them in your source and publish again, or publish",
         "    now and fix them later. Nothing here blocks you.",
         "",
     ];
 }
-export function readingLine(fileCount, totalBytes) {
-    return `→ Reading dist/ … ${fileCount} files · ${formatBytes(totalBytes)}`;
+const FINDINGS_SHOWN = 10;
+/**
+ * The `Paths from the root` section: a second section of the checklist, same
+ * geometry as the link preview. Absent when there are no findings, never an
+ * empty heading. One explanation for the whole section.
+ */
+export function pathsFromRootLines(findings, folder = "dist/") {
+    if (!findings || findings.length === 0)
+        return [];
+    const out = ["  Paths from the root", ""];
+    for (const f of findings.slice(0, FINDINGS_SHOWN)) {
+        out.push(`    !  ${f.ref} is not in ${folder}`);
+        out.push(`${" ".repeat(21)}${f.file} · ${f.tag}`);
+    }
+    if (findings.length > FINDINGS_SHOWN) {
+        out.push(`    and ${findings.length - FINDINGS_SHOWN} more`);
+    }
+    out.push("", "    Vincentt serves this app at the root of its address. A missing path that", "    starts with / usually means the build was made for a subpath, such as a", "    GitHub Pages project site. Nothing here blocks you.", "");
+    return out;
+}
+const DEFAULT_OUTPUT = { folder: "dist/", sourceNote: "" };
+export function readingLine(fileCount, totalBytes, output = DEFAULT_OUTPUT) {
+    const note = output.sourceNote ? ` ${output.sourceNote}` : "";
+    // The folder is the creator's build.output or --dist, so it is escaped.
+    return `→ Reading ${escapeControl(output.folder)}${note} … ${fileCount} files · ${formatBytes(totalBytes)}`;
 }
 export function headerLine(projectName, orgName) {
     return orgName ? `→ ${projectName} · ${orgName}` : `→ ${projectName}`;
@@ -165,7 +189,7 @@ export function firstPublishChecklist(i) {
     return [
         "",
         headerLine(i.projectName, i.orgName),
-        readingLine(i.fileCount, i.totalBytes),
+        readingLine(i.fileCount, i.totalBytes, i.output),
         "",
         RULE,
         "  FIRST PUBLISH",
@@ -178,14 +202,15 @@ export function firstPublishChecklist(i) {
         // visible.
         `        ${i.address}`,
         "",
-        "    After this it is yours forever, and can never be changed or reused —",
+        "    After this it is yours forever, and can never be changed or reused,",
         "    not by you, not by anyone else. Publishing again replaces what it",
         "    serves; it never changes the address.",
         "",
         RULE,
         "",
-        ...findingLines(i.findings, true),
+        ...findingLines(i.findings, true, i.output?.folder),
         ...nothingBlocksYou(),
+        ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
         `  Publishing v${i.nextVersion} · ${i.fileCount} files · ${formatBytes(i.totalBytes)}`,
         "",
     ];
@@ -223,12 +248,13 @@ export function republishChecklist(i) {
     return [
         "",
         headerLine(i.projectName, i.orgName),
-        readingLine(i.fileCount, i.totalBytes),
+        readingLine(i.fileCount, i.totalBytes, i.output),
         "",
         `  Live at   ${i.address}   ${context}`,
         `  Publishing v${i.nextVersion} · ${i.fileCount} files · ${formatBytes(i.totalBytes)}`,
         "",
-        ...findingLines(i.findings, false),
+        ...findingLines(i.findings, false, i.output?.folder),
+        ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
     ];
 }
 /** `[Y/n]` — on a republish an accidental Enter does the thing the creator typed the command to do. */
@@ -245,18 +271,74 @@ export function offlineChecklist(i) {
     return [
         "",
         headerLine(i.projectName, i.orgName),
-        readingLine(i.fileCount, i.totalBytes),
+        readingLine(i.fileCount, i.totalBytes, i.output),
         "",
         `!  ${i.address} is currently offline.`,
         "",
         `   Publishing v${i.nextVersion} will put it back online and make v${i.nextVersion} live.`,
         "",
-        ...findingLines(i.findings, false),
+        ...findingLines(i.findings, false, i.output?.folder),
+        ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
     ];
 }
 export function offlinePrompt(version) {
     return `  Publish v${version} and bring the address back online? [y/N] `;
 }
+/**
+ * The address has published before but serves nothing now (`not_serving`), or
+ * the api reports a state this CLI does not know. Neither may say "Live at":
+ * the creator would share an address that answers with nothing.
+ */
+export function notServingChecklist(i, stateKnown) {
+    return [
+        "",
+        headerLine(i.projectName, i.orgName),
+        readingLine(i.fileCount, i.totalBytes, i.output),
+        "",
+        stateKnown
+            ? `!  ${i.address} is not serving anything right now.`
+            : `!  This CLI can't tell whether ${i.address} is serving right now.`,
+        "",
+        `   Publishing v${i.nextVersion} will make v${i.nextVersion} live there.`,
+        "",
+        ...findingLines(i.findings, false, i.output?.folder),
+        ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
+    ];
+}
+/** `[y/N]`: the CLI cannot say what this publish changes, so Enter does nothing. */
+export function unknownStatePrompt(version) {
+    return `  Publish v${version} and make it live? [y/N] `;
+}
+// ---- f10, the held address ----------------------------------------------------
+/**
+ * The project is `held_by_platform`: Vincentt took the org's addresses offline
+ * over its traffic allowance, and the api refuses every publish until they are
+ * restored. Refused BEFORE the upload, because uploading a whole build only to
+ * be refused at commit is the retry loop this copy exists to stop.
+ *
+ * The project read carries no figures, so this names none. It shares
+ * planLimitRefused's voice: the platform is the actor, the remedy is outside
+ * the CLI, and nothing was lost.
+ */
+export function heldByPlatform(address, org = {}) {
+    return [
+        "",
+        `✗ Vincentt has taken ${address} offline.`,
+        "",
+        "  This wasn't you. The organization went over its monthly traffic allowance,",
+        "  and Vincentt took its published addresses offline. Publishing stays refused",
+        "  until they are restored.",
+        "",
+        "  Taking a paid plan restores them automatically, in the console. It cannot be",
+        "  done from the CLI.",
+        "",
+        "  Every version is still stored and the address is still yours.",
+        "",
+        ...remedyLines(org.orgSlug, org.consoleUrl),
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
 // ---- Flow L31, not signed in -------------------------------------------------
 /**
  * f1's line verbatim, with f4's reason. Note what is ABSENT, deliberately: f3's
@@ -350,28 +432,136 @@ function largestBlock(v) {
     return v.largest.map((f) => `    ${f.path.padEnd(width)}  ${formatBytes(f.size).padStart(sizeWidth)}`);
 }
 /** No dist at all, or no index.html at its root. Zero network calls. */
-export function noDist(distDir) {
+/**
+ * The build line. The recorded `build.command` when there is one; the template's
+ * `npm run build` when there is no vincentt.json; never a guess for an app whose
+ * file records no build command.
+ */
+function buildItLine(buildCommand) {
+    if (buildCommand === null)
+        return "  Run your build, then publish again.";
+    return `  Build it, then publish:  ${buildCommand ?? "npm run build"}`;
+}
+// The refusals below carry a creator-chosen path or command, so every line is
+// escaped: none of their fixed copy holds a control character.
+export function noDist(distDir, buildCommand) {
     return [
         "",
         `✗ There's no build to publish at ${distDir}.`,
         "",
-        "  Publishing uploads what your build produced — did the build run?",
+        "  Publishing uploads what your build produced. Did the build run?",
         "",
-        "  Build it, then publish:  npm run build",
+        buildItLine(buildCommand),
         "",
         "  Nothing was uploaded.",
         "",
-    ];
+    ].map(escapeControl);
 }
-export function noIndexHtml(distDir) {
+export function noIndexHtml(distDir, buildCommand) {
     return [
         "",
         "✗ There's no index.html at the root of your build.",
         "",
-        `  ${distDir} exists, but nothing there answers the address's own URL —`,
-        "  did the build run?",
+        `  ${distDir} exists, but nothing there answers the address's own URL.`,
+        "  Did the build run?",
+        "",
+        buildItLine(buildCommand),
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ].map(escapeControl);
+}
+/** Flow U1 — the output is the project folder itself. */
+export function outputIsRoot(o) {
+    const how = o.source === "vincentt.json"
+        ? `  vincentt.json sets build.output to "${o.value}", which would publish your source,`
+        : o.source === "flag"
+            ? `  --dist ${o.value} points at it, which would publish your source,`
+            : `  ${o.value}/ resolves to it, which would publish your source,`;
+    return [
+        "",
+        "✗ The build output is this project's own folder, not a build.",
+        "",
+        how,
+        "  settings and history. Set it to the folder your build writes.",
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ].map(escapeControl);
+}
+/** Flow U1 — the output lies outside the project. `shown` is project-relative. */
+export function outputOutside(shown) {
+    return [
+        "",
+        `✗ The build output ${escapeControl(shown)} is outside this project.`,
+        "",
+        "  Publish uploads a folder inside the project. Set --dist, or build.output in",
+        "  vincentt.json, to the folder your build writes.",
         "",
-        "  Build it, then publish:  npm run build",
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
+/** Flow U1 — the output is, or sits inside, `.git` or `.vincentt`. `shown` is project-relative. */
+export function outputInHidden(shown, hidden) {
+    return [
+        "",
+        `✗ The build output ${escapeControl(shown)} is inside ${hidden}/, not a build.`,
+        "",
+        "  Publishing it would put your repository's history or its Vincentt link at a",
+        "  public address. Set --dist, or build.output in vincentt.json, to the folder",
+        "  your build writes.",
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
+function offenderList(paths, folder) {
+    // File names and the folder prefix come from the build and the creator's
+    // settings, and may carry control characters.
+    folder = escapeControl(folder);
+    const shown = paths.slice(0, FINDINGS_SHOWN).map((p) => ({
+        path: escapeControl(p.path),
+        target: p.target === undefined ? undefined : escapeControl(p.target),
+    }));
+    const width = Math.max(...shown.map((p) => folder.length + p.path.length));
+    const out = shown.map((p) => p.target !== undefined
+        ? `    ${(folder + p.path).padEnd(width)}   links to ${p.target}`
+        : `    ${folder}${p.path}`);
+    if (paths.length > FINDINGS_SHOWN)
+        out.push(`    and ${paths.length - FINDINGS_SHOWN} more`);
+    return out;
+}
+/** Flow U1 — hidden names or symlinks that would leak. After the header and reading line. */
+export function secretFiles(paths, output = DEFAULT_OUTPUT) {
+    return [
+        "",
+        "✗ This build holds files that must never be published.",
+        "",
+        ...offenderList(paths, output.folder),
+        "",
+        `  Everything in ${escapeControl(output.folder)} becomes public at your address. Remove these from the build`,
+        "  output, rebuild, then publish.",
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
+/** Flow U1 — Git LFS pointer files. The recorded build.command, verbatim, when there is one. */
+export function lfsPointers(paths, output = DEFAULT_OUTPUT, buildCommand) {
+    return [
+        "",
+        "✗ This build holds Git LFS pointer files instead of the assets.",
+        "",
+        ...offenderList(paths, output.folder),
+        "",
+        "  The repo keeps these in Git LFS, and they were not downloaded before the build",
+        "  ran. Download them, rebuild, then publish:",
+        "",
+        "    git lfs pull",
+        buildCommand !== undefined
+            ? `    ${escapeControl(buildCommand)}`
+            : "    then run your build again",
         "",
         "  Nothing was uploaded.",
         "",
@@ -391,7 +581,7 @@ export function badPath(reason, offending) {
         "",
         `✗ This build ${why[reason] ?? "has a path we can't publish"}.`,
         "",
-        `    ${offending}`,
+        `    ${escapeControl(offending)}`,
         "",
         "  Rename it in your source, rebuild, then publish again.",
         "",
@@ -436,6 +626,22 @@ export function liveAt(liveUrl, version) {
         "",
     ];
 }
+/** Prints once the commit succeeded and the address is still serving the previous bytes. */
+export function propagating(liveUrl, version) {
+    return `→ Propagating v${version} to ${liveUrl}…`;
+}
+/**
+ * The wait ran out. The publish DID commit, so this is a success, and it says so
+ * plainly: a creator told "not yet" without that will publish again.
+ */
+export function notYetVisible(liveUrl, version) {
+    return [
+        `✓ Published v${version}, not yet visible at ${liveUrl}`,
+        "",
+        "  It usually appears within a minute. There is no need to publish again.",
+        "",
+    ];
+}
 /** Prints only if a retry is needed. It says nothing about a failure, because nothing has failed yet. */
 export function takingLonger() {
     return "!  Taking a moment longer than usual…";
@@ -462,7 +668,10 @@ export function planLimitRefused(i) {
     if (i.orgName || i.orgSlug)
         rows.push(["Organization", orgLabel(i.orgName, i.orgSlug)]);
     if (i.planName) {
-        rows.push(["Plan", `${i.planName} — ${formatBytes(i.allowanceBytes)} traffic per month`]);
+        rows.push([
+            "Plan",
+            `${i.planName}, ${formatBytes(i.allowanceBytes)} traffic per month`,
+        ]);
     }
     else {
         rows.push(["Allowance", `${formatBytes(i.allowanceBytes)} traffic per month`]);
@@ -488,7 +697,7 @@ export function planLimitRefused(i) {
         // minutes, and copy that promises instant is copy that lies on a slow tick.
         `  Published addresses were taken offline${takenOn} because the organization`,
         "  went over its monthly traffic allowance. Taking a paid plan restores them",
-        "  automatically, in the console — it cannot be done from the CLI.",
+        "  automatically, in the console. It cannot be done from the CLI.",
         "",
         "  Every version is still stored and the address is still yours.",
         "",
@@ -519,15 +728,21 @@ function remedyLines(orgSlug, consoleUrl) {
     if (!orgSlug)
         return [`  Email ${SUPPORT_EMAIL}.`, ""];
     const base = (consoleUrl ?? "https://console.vincentt.studio").replace(/\/$/, "");
-    return [
-        `  See ${base}/orgs/${orgSlug}/usage, or email`,
-        `  ${SUPPORT_EMAIL}.`,
-        "",
-    ];
+    return [`  See ${base}/orgs/${orgSlug}/usage, or email`, `  ${SUPPORT_EMAIL}.`, ""];
 }
 const MONTHS = [
-    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
-    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
 ];
 /** `29 Aug` — the date the creator reads, in UTC, matching the marker's own day. */
 function shortDate(iso) {
@@ -568,6 +783,25 @@ export function flipFailed(address, liveVersion) {
         "",
     ];
 }
+/**
+ * The commit's answer never arrived (the connection dropped or the api stopped
+ * answering), so whether the address switched is unknown. It says so, rather than
+ * claiming either outcome, and names the one check that settles it.
+ */
+export function commitOutcomeUnknown(address, liveVersion) {
+    return [
+        "",
+        "✗ Your files uploaded, but Vincentt's answer to the switch-over never arrived.",
+        "",
+        `  It may or may not be live. Open https://${address} to check.`,
+        liveVersion === undefined
+            ? "  If it did not switch, nothing is served there yet."
+            : `  If it did not switch, it is still serving v${liveVersion}.`,
+        "",
+        "  Publishing again is safe:  vincentt publish",
+        "",
+    ];
+}
 /**
  * Two sentences, no explanation of version allocation. The real case is a
  * teammate and an agent publishing in the same second, and "someone else
@@ -599,7 +833,7 @@ export function publishIncomplete(address, counts, liveVersion) {
             : `${missing} file${missing === 1 ? "" : "s"} didn't arrive`;
     return [
         "",
-        `✗ The upload didn't complete — ${what}.`,
+        `✗ The upload didn't complete: ${what}.`,
         "",
         ...unchangedLines(address, liveVersion),
         "",
@@ -611,7 +845,7 @@ export function publishIncomplete(address, counts, liveVersion) {
 export function badDigest(filePath, address, liveVersion) {
     return [
         "",
-        `✗ ${filePath} changed while uploading — rebuild and publish again.`,
+        `✗ ${filePath} changed while uploading. Rebuild and publish again.`,
         "",
         ...unchangedLines(address, liveVersion),
         "",
@@ -625,10 +859,10 @@ export function badDigest(filePath, address, liveVersion) {
  */
 function unchangedLines(address, liveVersion) {
     if (liveVersion === undefined) {
-        return [`  Your live address is unchanged — ${address}.`];
+        return [`  Your live address is unchanged: ${address}.`];
     }
     return [
-        `  Your live address is unchanged — ${address} is still`,
+        `  Your live address is unchanged: ${address} is still`,
         `  serving v${liveVersion}.`,
     ];
 }
@@ -682,7 +916,7 @@ export function consoleVerb(verb, versionsUrl) {
         `✗ There's no \`${verb}\` command.`,
         "",
         "  Rolling back, taking an address offline, and putting it back online are",
-        "  console actions — they change what a permanent address serves, and that",
+        "  console actions: they change what a permanent address serves, and that",
         "  belongs on a screen where you can see every version first.",
         "",
     ];

package/dist/publish/fit.d.ts

@@ -0,0 +1,15 @@
+export interface HtmlFile {
+    /** Output-relative POSIX path, as in the manifest. */
+    file: string;
+    html: string;
+}
+export interface RootAbsoluteFinding {
+    file: string;
+    /** The reference as written, query and fragment included. */
+    ref: string;
+    /** `<script src>`, `<link rel=stylesheet>`, `<img src>`, ... */
+    tag: string;
+}
+/** Does a `/path` reference resolve under the host's index rules? */
+export declare function resolvesInManifest(ref: string, manifest: ReadonlySet<string>): boolean;
+export declare function rootAbsoluteFindings(htmlFiles: readonly HtmlFile[], manifestPaths: ReadonlySet<string>): RootAbsoluteFinding[];

package/dist/publish/fit.js

@@ -0,0 +1,103 @@
+// Root-absolute resource references that do not resolve in the output. The
+// likely cause is a build made for a subpath (a GitHub Pages project site) while
+// Vincentt serves the root. A WARNING only: nothing is rewritten and nothing is
+// blocked, because the creator's build is what fixes it.
+//
+// Resource tags only. `<a href>` is a link to a route, not a missing file, and
+// scanning it would warn on nearly every site's navigation. URLs baked into JS
+// or CSS are not scanned (a stated limit).
+//
+// Regex-based, like classify.ts; every pattern here is linear.
+import { escapeControl } from "../lib/terminalText.js";
+const LINK_RELS = new Set(["stylesheet", "preload", "modulepreload", "icon"]);
+const SRC_TAGS = new Set(["script", "img", "source", "video", "audio"]);
+const TAG_RE = /<(script|link|img|source|video|audio)\b([^>]*)>/gi;
+const ATTR_RE = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+function stripComments(html) {
+    let out = "";
+    let i = 0;
+    for (;;) {
+        const start = html.indexOf("<!--", i);
+        if (start === -1)
+            return out + html.slice(i);
+        out += html.slice(i, start);
+        const end = html.indexOf("-->", start + 4);
+        if (end === -1)
+            return out;
+        i = end + 3;
+    }
+}
+function attributes(attrs) {
+    const out = new Map();
+    for (const m of attrs.matchAll(ATTR_RE)) {
+        const name = m[1].toLowerCase();
+        if (!out.has(name))
+            out.set(name, m[2] ?? m[3] ?? m[4] ?? "");
+    }
+    return out;
+}
+/** Does a `/path` reference resolve under the host's index rules? */
+export function resolvesInManifest(ref, manifest) {
+    const bare = ref.split("#")[0].split("?")[0];
+    let decoded = bare;
+    try {
+        decoded = decodeURI(bare);
+    }
+    catch {
+        // An undecodable reference is judged as written.
+    }
+    const rel = decoded.slice(1);
+    if (manifest.has(rel))
+        return true;
+    if (decoded.endsWith("/"))
+        return manifest.has(`${rel}index.html`);
+    const last = rel.split("/").pop() ?? "";
+    if (!last.includes("."))
+        return manifest.has(`${rel}/index.html`);
+    return false;
+}
+function isRootAbsolute(value) {
+    return value.startsWith("/") && !value.startsWith("//");
+}
+export function rootAbsoluteFindings(htmlFiles, manifestPaths) {
+    const findings = [];
+    for (const { file, html } of htmlFiles) {
+        for (const m of stripComments(html).matchAll(TAG_RE)) {
+            const tag = m[1].toLowerCase();
+            const attrs = attributes(m[2] ?? "");
+            let value;
+            let label;
+            if (tag === "link") {
+                const rel = (attrs.get("rel") ?? "")
+                    .toLowerCase()
+                    .split(/\s+/)
+                    .find((r) => LINK_RELS.has(r));
+                if (rel === undefined)
+                    continue;
+                value = attrs.get("href");
+                label = `<link rel=${rel}>`;
+            }
+            else if (SRC_TAGS.has(tag)) {
+                value = attrs.get("src");
+                label = `<${tag} src>`;
+            }
+            else {
+                continue;
+            }
+            if (value === undefined)
+                continue;
+            const trimmed = value.trim();
+            if (!isRootAbsolute(trimmed))
+                continue;
+            if (resolvesInManifest(trimmed, manifestPaths))
+                continue;
+            // Both come from the creator's build and reach the terminal verbatim.
+            findings.push({
+                file: escapeControl(file),
+                ref: escapeControl(trimmed),
+                tag: label,
+            });
+        }
+    }
+    return findings;
+}

package/dist/publish/manifest.d.ts

@@ -10,11 +10,52 @@ export interface Manifest {
     files: ManifestEntry[];
     totalBytes: number;
 }
+export type ManifestReason = PathRejection | "no_dist" | "output_is_repo_root" | "output_outside_repo" | "output_in_hidden" | "secret_path" | "lfs_pointer";
+/** An output-relative path the leak or LFS check refused. */
+export interface Offender {
+    /** Output-relative, POSIX. A refused folder carries a trailing `/`. */
+    path: string;
+    /** For a symlink: where it resolves, repo-relative inside and absolute outside. */
+    target?: string;
+}
+export interface ManifestErrorDetail {
+    paths?: Offender[];
+    /** What the walk saw, for the reading line above a refusal. */
+    stats?: {
+        files: number;
+        bytes: number;
+    };
+}
 export declare class ManifestError extends Error {
-    readonly reason: PathRejection | "no_dist";
+    readonly reason: ManifestReason;
     readonly offendingPath: string;
-    constructor(reason: PathRejection | "no_dist", offendingPath: string, message: string);
+    readonly paths: Offender[];
+    readonly stats?: {
+        files: number;
+        bytes: number;
+    };
+    constructor(reason: ManifestReason, offendingPath: string, message: string, detail?: ManifestErrorDetail);
+}
+export interface BuildManifestOptions {
+    /**
+     * The directory holding the binding. When given, the output is refused before
+     * any hashing if it is the repo root, lies outside it, holds a dotted name
+     * outside the two allowed ones, holds a symlink that resolves outside the root
+     * or onto a dotted path, or holds a Git LFS pointer. All of it is local.
+     */
+    repoRoot?: string;
 }
+/** A Git LFS pointer file: at most 1 KB, the spec's exact first line, and an oid line. */
+export declare function isLfsPointer(absPath: string, size: number): Promise<boolean>;
+/**
+ * The leak and LFS checks, in that order, before anything is hashed or sent.
+ * Returns the output-relative file list the checks passed, which is exactly the
+ * list the manifest is built from: what is checked is what is uploaded.
+ */
+export declare function checkOutput(distDir: string, repoRoot: string): Promise<{
+    rel: string;
+    size: number;
+}[]>;
 /** Recursively list files under `dir` as dir-relative POSIX paths. Symlinks are not followed. */
 export declare function walkDist(dir: string, base?: string): Promise<string[]>;
 /** sha256 of a file, base64 std — the exact form `x-amz-checksum-sha256` wants. */
@@ -24,4 +65,4 @@ export declare function hashFile(absPath: string): Promise<string>;
  * hashed, so the string this returns is the string the API validates, signs, and
  * later lists — there is no second form anywhere.
  */
-export declare function buildManifest(distDir: string): Promise<Manifest>;
+export declare function buildManifest(distDir: string, opts?: BuildManifestOptions): Promise<Manifest>;