@vincentt-xr/cli 0.20.0 → 0.22.0

package/dist/publish/copy.js

@@ -12,7 +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";
+import { escapeTerminal } from "../lib/terminalText.js";
 /** The only horizontal rules in any f4 output. They exist here and nowhere else. */
 const RULE = "  ─────────────────────────────────────────────────────────────────────";
 const LABELS = {
@@ -166,11 +166,33 @@ export function pathsFromRootLines(findings, folder = "dist/") {
     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;
 }
+/** The `Heavy files` section: warning-only, absent when there are no findings. */
+export function heavyFileLines(findings) {
+    if (!findings || findings.length === 0)
+        return [];
+    const out = ["  Heavy files  (each one downloads to the phone before it can show)", ""];
+    for (const f of findings.slice(0, FINDINGS_SHOWN)) {
+        const name = escapeTerminal(f.path);
+        if (f.kind === "model") {
+            out.push(`    !  ${name} is ${formatBytes(f.bytes)}`);
+            out.push(`${" ".repeat(21)}a model over 10 MB`);
+        }
+        else {
+            out.push(`    !  ${name} is ${f.width} x ${f.height} px`);
+            out.push(`${" ".repeat(21)}an image over 2048 px on its long side`);
+        }
+    }
+    if (findings.length > FINDINGS_SHOWN) {
+        out.push(`    and ${findings.length - FINDINGS_SHOWN} more`);
+    }
+    out.push("", "    Every phone that opens this app downloads these files over its own", "    connection. Compress the model or shrink the image, then build again.", "    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)}`;
+    return `→ Reading ${escapeTerminal(output.folder)}${note} … ${fileCount} files · ${formatBytes(totalBytes)}`;
 }
 export function headerLine(projectName, orgName) {
     return orgName ? `→ ${projectName} · ${orgName}` : `→ ${projectName}`;
@@ -211,6 +233,7 @@ export function firstPublishChecklist(i) {
         ...findingLines(i.findings, true, i.output?.folder),
         ...nothingBlocksYou(),
         ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
+        ...heavyFileLines(i.heavy),
         `  Publishing v${i.nextVersion} · ${i.fileCount} files · ${formatBytes(i.totalBytes)}`,
         "",
     ];
@@ -255,6 +278,7 @@ export function republishChecklist(i) {
         "",
         ...findingLines(i.findings, false, i.output?.folder),
         ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
+        ...heavyFileLines(i.heavy),
     ];
 }
 /** `[Y/n]` — on a republish an accidental Enter does the thing the creator typed the command to do. */
@@ -279,6 +303,7 @@ export function offlineChecklist(i) {
         "",
         ...findingLines(i.findings, false, i.output?.folder),
         ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
+        ...heavyFileLines(i.heavy),
     ];
 }
 export function offlinePrompt(version) {
@@ -303,6 +328,7 @@ export function notServingChecklist(i, stateKnown) {
         "",
         ...findingLines(i.findings, false, i.output?.folder),
         ...pathsFromRootLines(i.rootAbsolute, i.output?.folder),
+        ...heavyFileLines(i.heavy),
     ];
 }
 /** `[y/N]`: the CLI cannot say what this publish changes, so Enter does nothing. */
@@ -378,7 +404,7 @@ export function tooLarge(v) {
             "",
             "✗ One file is too large to publish.",
             "",
-            ...alignedPair([v.path ?? "", formatBytes(v.observed)], ["the per-file limit", formatLimit(v.limit)]),
+            ...alignedPair([escapeTerminal(v.path ?? ""), formatBytes(v.observed)], ["the per-file limit", formatLimit(v.limit)]),
             "",
             "  Compress or externalise it, rebuild, then publish again.",
             "",
@@ -427,9 +453,10 @@ function alignedPair(a, b) {
     ];
 }
 function largestBlock(v) {
-    const width = Math.max(0, ...v.largest.map((f) => f.path.length));
-    const sizeWidth = Math.max(0, ...v.largest.map((f) => formatBytes(f.size).length));
-    return v.largest.map((f) => `    ${f.path.padEnd(width)}  ${formatBytes(f.size).padStart(sizeWidth)}`);
+    const largest = v.largest.map((f) => ({ path: escapeTerminal(f.path), size: f.size }));
+    const width = Math.max(0, ...largest.map((f) => f.path.length));
+    const sizeWidth = Math.max(0, ...largest.map((f) => formatBytes(f.size).length));
+    return 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. */
 /**
@@ -455,7 +482,7 @@ export function noDist(distDir, buildCommand) {
         "",
         "  Nothing was uploaded.",
         "",
-    ].map(escapeControl);
+    ].map(escapeTerminal);
 }
 export function noIndexHtml(distDir, buildCommand) {
     return [
@@ -469,7 +496,7 @@ export function noIndexHtml(distDir, buildCommand) {
         "",
         "  Nothing was uploaded.",
         "",
-    ].map(escapeControl);
+    ].map(escapeTerminal);
 }
 /** Flow U1 — the output is the project folder itself. */
 export function outputIsRoot(o) {
@@ -487,13 +514,13 @@ export function outputIsRoot(o) {
         "",
         "  Nothing was uploaded.",
         "",
-    ].map(escapeControl);
+    ].map(escapeTerminal);
 }
 /** 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.`,
+        `✗ The build output ${escapeTerminal(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.",
@@ -506,7 +533,7 @@ export function outputOutside(shown) {
 export function outputInHidden(shown, hidden) {
     return [
         "",
-        `✗ The build output ${escapeControl(shown)} is inside ${hidden}/, not a build.`,
+        `✗ The build output ${escapeTerminal(shown)} is inside ${escapeTerminal(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",
@@ -516,18 +543,30 @@ export function outputInHidden(shown, hidden) {
         "",
     ];
 }
+/** Where a credential reason starts, unless a longer path pushes it right. */
+const WHY_COLUMN = 40;
+const CREDENTIAL_WHY = {
+    name: "named like a credential",
+    private_key: "holds a private key",
+    service_account: "holds a service-account key",
+    authorized_user: "holds a Google sign-in credential",
+};
 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);
+    folder = escapeTerminal(folder);
     const shown = paths.slice(0, FINDINGS_SHOWN).map((p) => ({
-        path: escapeControl(p.path),
-        target: p.target === undefined ? undefined : escapeControl(p.target),
+        path: escapeTerminal(p.path),
+        target: p.target === undefined ? undefined : escapeTerminal(p.target),
+        why: p.why,
     }));
     const width = Math.max(...shown.map((p) => folder.length + p.path.length));
+    const whyColumn = Math.max(WHY_COLUMN, width + 3);
     const out = shown.map((p) => p.target !== undefined
         ? `    ${(folder + p.path).padEnd(width)}   links to ${p.target}`
-        : `    ${folder}${p.path}`);
+        : p.why !== undefined
+            ? `    ${(folder + p.path).padEnd(whyColumn)}${CREDENTIAL_WHY[p.why]}`
+            : `    ${folder}${p.path}`);
     if (paths.length > FINDINGS_SHOWN)
         out.push(`    and ${paths.length - FINDINGS_SHOWN} more`);
     return out;
@@ -540,13 +579,64 @@ export function secretFiles(paths, output = DEFAULT_OUTPUT) {
         "",
         ...offenderList(paths, output.folder),
         "",
-        `  Everything in ${escapeControl(output.folder)} becomes public at your address. Remove these from the build`,
+        `  Everything in ${escapeTerminal(output.folder)} becomes public at your address. Remove these from the build`,
         "  output, rebuild, then publish.",
         "",
         "  Nothing was uploaded.",
         "",
     ];
 }
+/**
+ * Flow U1 — files whose folder resolved outside the output after the walk: a
+ * folder was swapped for a link while publish read it. The whole publish is
+ * refused, never just the file. After the header and reading line.
+ */
+export function escapedFiles(paths, output = DEFAULT_OUTPUT) {
+    return [
+        "",
+        `✗ These files resolved outside ${escapeTerminal(output.folder)} while publish was reading them.`,
+        "",
+        ...offenderList(paths, output.folder),
+        "",
+        "  A folder in the build output became a link to somewhere else, so publish",
+        "  cannot vouch for what it would upload. Let your build finish, then publish",
+        "  again.",
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
+/** Flow U1 — credential files, from the early checks or the hash step. After the header and reading line. */
+export function credentialFiles(paths, output = DEFAULT_OUTPUT) {
+    return [
+        "",
+        "✗ This build holds files that look like private keys.",
+        "",
+        ...offenderList(paths, output.folder),
+        "",
+        `  Everything in ${escapeTerminal(output.folder)} becomes public at your address, and a published version`,
+        "  cannot be taken back. Move these out of the build output, rebuild, then",
+        "  publish. A file only named like a key, such as a Keynote .key, needs a new",
+        "  name.",
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
+/** Flow U1 — a file that changed, became a link, or could not be read while checked or hashed. */
+export function fileUnreadable(filePath, output = DEFAULT_OUTPUT) {
+    return [
+        "",
+        `✗ ${escapeTerminal(output.folder + filePath)} changed while publish was reading it.`,
+        "",
+        "  It became a link or a different file, or could not be read, so publish",
+        "  cannot vouch for what it would upload. Let your build finish, then publish",
+        "  again.",
+        "",
+        "  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 [
@@ -560,7 +650,7 @@ export function lfsPointers(paths, output = DEFAULT_OUTPUT, buildCommand) {
         "",
         "    git lfs pull",
         buildCommand !== undefined
-            ? `    ${escapeControl(buildCommand)}`
+            ? `    ${escapeTerminal(buildCommand)}`
             : "    then run your build again",
         "",
         "  Nothing was uploaded.",
@@ -581,7 +671,7 @@ export function badPath(reason, offending) {
         "",
         `✗ This build ${why[reason] ?? "has a path we can't publish"}.`,
         "",
-        `    ${escapeControl(offending)}`,
+        `    ${escapeTerminal(offending)}`,
         "",
         "  Rename it in your source, rebuild, then publish again.",
         "",
@@ -845,7 +935,7 @@ export function publishIncomplete(address, counts, liveVersion) {
 export function badDigest(filePath, address, liveVersion) {
     return [
         "",
-        `✗ ${filePath} changed while uploading. Rebuild and publish again.`,
+        `✗ ${escapeTerminal(filePath)} changed while uploading. Rebuild and publish again.`,
         "",
         ...unchangedLines(address, liveVersion),
         "",

package/dist/publish/keyScan.d.ts

@@ -0,0 +1,25 @@
+/** The label is bounded to 40 characters so the carried tail stays finite. */
+export declare const KEY_HEADER: RegExp;
+/**
+ * A newline (real, or the two-character `\n` or four-character `\r\n` of a
+ * string literal), then a base64 line.
+ */
+export declare const KEY_BODY: RegExp;
+/** Below this offset a header alone is a match. */
+export declare const HEAD_BYTES = 4096;
+/** How far past a header its key body may sit. */
+export declare const BODY_WINDOW = 256;
+export interface KeyScanner {
+    /** Feed the next chunk, as latin1. */
+    push(chunk: string): void;
+    /** Judge any header still waiting on its body window. True when a key was seen. */
+    end(): boolean;
+    readonly matched: boolean;
+}
+export declare function createKeyScanner(): KeyScanner;
+export type CredentialJsonType = "service_account" | "authorized_user";
+/**
+ * The top-level `type` of a Google credential JSON, or undefined. A parse
+ * failure is "not a match" and its message is discarded: it echoes the input.
+ */
+export declare function credentialJson(bytes: Uint8Array): CredentialJsonType | undefined;

package/dist/publish/keyScan.js

@@ -0,0 +1,88 @@
+// Content rules for credential files: a private-key header (PEM, OpenSSH, PGP)
+// and a Google service-account or user credential JSON. Bytes are read as
+// latin1, one character per byte, so the ASCII header matches inside UTF-8 and
+// no decode can throw.
+/** The label is bounded to 40 characters so the carried tail stays finite. */
+export const KEY_HEADER = /-----BEGIN [A-Z0-9 ]{0,40}PRIVATE KEY( BLOCK)?-----/;
+/**
+ * A newline (real, or the two-character `\n` or four-character `\r\n` of a
+ * string literal), then a base64 line.
+ */
+export const KEY_BODY = /(?:\r?\n|(?:\\r)?\\n)[A-Za-z0-9+/=]{64}/;
+/** Below this offset a header alone is a match. */
+export const HEAD_BYTES = 4096;
+/** How far past a header its key body may sit. */
+export const BODY_WINDOW = 256;
+/** Covers the longest header plus the body window. */
+const CARRY = 512;
+export function createKeyScanner() {
+    let buf = "";
+    let bufStart = 0;
+    // Absolute offset below which every header has been judged.
+    let judgedTo = 0;
+    let matched = false;
+    const scan = (final) => {
+        const re = new RegExp(KEY_HEADER.source, "g");
+        re.lastIndex = Math.max(0, judgedTo - bufStart);
+        let m;
+        while ((m = re.exec(buf)) !== null) {
+            const at = bufStart + m.index;
+            if (at < HEAD_BYTES) {
+                matched = true;
+                return;
+            }
+            const end = m.index + m[0].length;
+            if (!final && end + BODY_WINDOW > buf.length) {
+                judgedTo = at;
+                return;
+            }
+            if (KEY_BODY.test(buf.slice(end, end + BODY_WINDOW))) {
+                matched = true;
+                return;
+            }
+            judgedTo = at + 1;
+            re.lastIndex = m.index + 1;
+        }
+    };
+    return {
+        push(chunk) {
+            if (matched)
+                return;
+            buf += chunk;
+            scan(false);
+            if (buf.length > CARRY) {
+                const drop = buf.length - CARRY;
+                buf = buf.slice(drop);
+                bufStart += drop;
+            }
+        },
+        end() {
+            if (!matched)
+                scan(true);
+            return matched;
+        },
+        get matched() {
+            return matched;
+        },
+    };
+}
+/**
+ * The top-level `type` of a Google credential JSON, or undefined. A parse
+ * failure is "not a match" and its message is discarded: it echoes the input.
+ */
+export function credentialJson(bytes) {
+    const start = bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf
+        ? 3
+        : 0;
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(bytes.buffer, bytes.byteOffset + start, bytes.length - start).toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const type = value.type;
+    return type === "service_account" || type === "authorized_user" ? type : undefined;
+}

package/dist/publish/manifest.d.ts

@@ -1,3 +1,4 @@
+import { type CredentialJsonType } from "./keyScan.js";
 import { type PathRejection } from "./paths.js";
 export interface ManifestEntry {
     /** dist-relative, forward slashes, no leading `/`, normalized. */
@@ -10,13 +11,16 @@ 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 type ManifestReason = PathRejection | "no_dist" | "output_is_repo_root" | "output_outside_repo" | "output_in_hidden" | "secret_path" | "path_escaped" | "credential_file" | "lfs_pointer" | "file_unreadable";
+export type CredentialWhy = "name" | "private_key" | CredentialJsonType;
+/** An output-relative path the leak, credential 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;
+    /** For a credential file: what made it one. */
+    why?: CredentialWhy;
 }
 export interface ManifestErrorDetail {
     paths?: Offender[];
@@ -36,33 +40,70 @@ export declare class ManifestError extends Error {
     };
     constructor(reason: ManifestReason, offendingPath: string, message: string, detail?: ManifestErrorDetail);
 }
+/** A file the walk passed: what the hash step must find again at the same path. */
+export interface WalkedFile {
+    /** Output-relative, POSIX. */
+    rel: string;
+    /** Absolute, under the real output folder. */
+    abs: string;
+    size: number;
+    dev: number;
+    ino: number;
+}
 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.
+     * The directory holding the binding. Required: there is no unchecked
+     * manifest. 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, holds a
+     * credential file, or holds a Git LFS pointer. All of it is local.
+     */
+    repoRoot: string;
+    /**
+     * Test-only: runs after the checks and before the hash step, so a test can
+     * change a checked file. Never set by the command.
+     */
+    beforeHash?: (files: readonly WalkedFile[]) => Promise<void> | void;
+    /**
+     * Test-only: runs before the walk reads each folder, so a test can swap a
+     * folder mid-walk. Never set by the command.
      */
-    repoRoot?: string;
+    beforeReadDir?: (dir: string) => Promise<void> | void;
+}
+/** Test-only hooks into the checks. */
+export interface CheckOutputHooks {
+    beforeReadDir?: (dir: string) => Promise<void> | void;
 }
 /** 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>;
+export declare function isLfsPointer(head: Uint8Array, size: number): 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.
+ * The early pass's read: the first `min(size, 4096)` bytes, or the whole file
+ * for a `.json` of at most 64 KB. Opens without following links.
  */
-export declare function checkOutput(distDir: string, repoRoot: string): Promise<{
-    rel: string;
+export declare function readHead(file: WalkedFile): Promise<Buffer>;
+/**
+ * The leak, credential and LFS checks, in that order, before anything is hashed
+ * or sent. Returns the 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, hooks?: CheckOutputHooks): Promise<WalkedFile[]>;
+export interface HashResult {
+    /** base64 std, the exact form `x-amz-checksum-sha256` wants. */
+    sha256: 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. */
-export declare function hashFile(absPath: string): Promise<string>;
+    /** Set when the hashed bytes hold a private key or a Google credential. */
+    why?: CredentialWhy;
+}
+/**
+ * Hash a walked file and re-run the content rules over the exact bytes hashed.
+ * The file is opened without following links and must still be the regular
+ * file the walk saw. Every read error throws `file_unreadable`; only a JSON
+ * parse failure is "not a match".
+ */
+export declare function hashAndScan(absPath: string, walked: WalkedFile): Promise<HashResult>;
 /**
  * Build the manifest for a dist directory. Every path is normalized before it is
  * 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, opts?: BuildManifestOptions): Promise<Manifest>;
+export declare function buildManifest(distDir: string, opts: BuildManifestOptions): Promise<Manifest>;