@buildinternet/uploads 0.44.0 → 0.46.0

package/dist/commands/screenshot.js

@@ -82,7 +82,16 @@ Options:
   --no-hide-dev-tools       Don't auto-hide framework dev toolbars (auto-hidden on localhost/private)
   --reduced-motion          Emulate prefers-reduced-motion: reduce so animations settle (best-effort
                             on --via remote — neutralizes animations via injected CSS)
-  --eval <js>               Run JS in the page after settle, before capture (--via local only)
+  --wait-for <js>           Poll this JS expression in the page until truthy before --eval and
+                            capture (--via local only). Bridges framework hydration: load/
+                            networkidle settle before React/Next attach handlers, so a synthetic
+                            click in --eval hits the inert server-rendered DOM. Express the app's
+                            own "interactive" signal, e.g. --wait-for 'window.__hydrated===true' or
+                            --wait-for 'document.querySelector("[data-hydrated]")'. Times out with
+                            the capture timeout if it never becomes truthy.
+  --eval <js>               Run JS in the page after settle, before capture (--via local only).
+                            Note: synthetic events (el.click()) won't reach framework handlers
+                            until the app hydrates — pair with --wait-for on React/Next apps.
   --init-script <file>      Inject a JS file before navigation (--via local only)
   --annotate <file|->       Bake hand-drawn boxes, arrows, labels, and redactions from a JSON
                             annotation spec onto the capture before upload (file path or - for
@@ -216,6 +225,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     // lets captureScreenshot apply its localhost-aware default.
     const hideDevTools = flagBool(parsed.flags, "--no-hide-dev-tools") ? false : undefined;
     const reducedMotion = flagBool(parsed.flags, "--reduced-motion");
+    const waitForExpr = flagString(parsed.flags, "--wait-for");
     const evalJs = flagString(parsed.flags, "--eval");
     const initScriptPath = flagString(parsed.flags, "--init-script");
     let initScript;
@@ -445,6 +455,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         hide,
         hideDevTools,
         reducedMotion,
+        waitForExpr,
         evalJs,
         initScript,
         // Skip folding when an explicit --key was given — --key sets the whole

package/dist/commands.js

@@ -14,7 +14,7 @@ import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
 import { mergeSidecarMeta } from "./sidecar.js";
 import { ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, ghBranchKeyPrefix, ghKeyPrefix, ghPrivateKeyPrefix, ghPrivateBranchKeyPrefix, ghMetadataFromTarget, parseGhKey, parseGhPrivateKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, AUTO_RENDER_OPTIONS, GH_FALLBACK_AUTHOR_NOTE, normalizeGithubCoordinate, } from "./github.js";
-import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
+import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, hasLinkCandidate, extractCandidateUrls, fetchAdoptionCandidateText, } from "./github-gh.js";
 import { deriveRepoFromGit, deriveRepoSlugFromGit } from "./keys.js";
 import { noProjectContextNudge } from "./project-context-nudge.js";
 import { resolvePutPrefix } from "./destinations.js";
@@ -564,6 +564,59 @@ export async function syncAttachmentsComment(client, target, run, workspace, opt
                 `Posting via local gh in the meantime.\n`);
         }
     }
+    // Link adoption (issue #708): local-gh fallback parity with the bot's own
+    // adoption (issue #701, apps/api/src/github-link-adopt.ts). When the bot
+    // already handled this target the server already adopted for us, so this
+    // only runs once we've fallen through to gh. Scans the PR/issue body and
+    // every comment for pasted uploads.sh URLs and adopts each one that
+    // resolves (server-side, inside `POST .../github/attach`) to a file in
+    // THIS workspace's own bound-repo attachment prefix — copy, never move,
+    // same as the bot path. Best-effort end to end: any failure (not a git
+    // repo, `gh` unavailable/unauthenticated, config unreadable) degrades to
+    // "adopt nothing" rather than blocking the comment sync it rides along
+    // with.
+    let adoptedCount = 0;
+    let preAdoptionAttachmentCount;
+    try {
+        const root = run("git", ["rev-parse", "--show-toplevel"]).trim();
+        const { config: adoptConfig } = readLocalRepoCommentConfig(root);
+        const { options: adoptOptions } = resolveCommentOptions(adoptConfig, null);
+        if (adoptOptions.adoptLinkedFiles) {
+            const text = fetchAdoptionCandidateText(target, run);
+            if (hasLinkCandidate(text)) {
+                const urls = extractCandidateUrls(text);
+                if (urls.length > 0) {
+                    // Baseline BEFORE this pass's adoptions land (mirrors the bot
+                    // path's `gatherCommentBody` call before its own copies) — feeds
+                    // the noise guard below without a lone adoption inflating its own
+                    // count. Plain prefix only (not the private-prefix listing done
+                    // for the final render below) — good enough for a guard decision.
+                    preAdoptionAttachmentCount = (await client.listAll({ prefix: ghKeyPrefix(target) }))
+                        .length;
+                    for (const url of urls) {
+                        try {
+                            await client.attachExisting({
+                                source: url,
+                                repo: target.repo,
+                                ...(target.kind === "pull" ? { pr: target.num } : { issue: target.num }),
+                            });
+                            adoptedCount++;
+                        }
+                        catch {
+                            // Not a resolvable uploads.sh URL, belongs to a different
+                            // workspace, or the source was deleted — silently dropped,
+                            // matching the bot path's contract (a throw from
+                            // `resolveAttachSourceKey` is caught per-URL there too).
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Not a git repo, `.uploads.yml` unreadable, or `gh` unavailable for the
+        // PR/comments fetch — degrade to no adoption this pass.
+    }
     // gh fallback: gather from this workspace's own data and post via local `gh`.
     // Note (issues #304, #365): this CLI process has no server-side
     // WorkspaceRecord in scope, so it cannot honor a workspace's
@@ -658,11 +711,21 @@ export async function syncAttachmentsComment(client, target, run, workspace, opt
     // bot identity, so this note would be wrong there.
     const body = `${attachmentsCommentBody(items, previewGalleries, marker, renderOptions, target)}\n${GH_FALLBACK_AUTHOR_NOTE}`;
     const count = items.length + previewGalleries.length;
+    // Noise guard (issue #708, mirrors the bot's `shouldSyncAfterAdopt`): a
+    // lone adopted link with nothing else already attached is already fully
+    // visible inline in the PR/comment — don't create a brand-new comment just
+    // to repeat it. `upsertAttachmentsComment` still PATCHes an existing
+    // managed comment unconditionally (its own `if (existing)` branch runs
+    // regardless of `createIfMissing`), so "a managed comment already exists"
+    // and "other attachments are already present" both heal/sync for free
+    // here without any extra condition — this only ever suppresses a fresh
+    // create.
+    const skipLoneAdoptionCreate = adoptedCount === 1 && (preAdoptionAttachmentCount ?? 0) === 0;
     // Empty (count 0) renders the neutral empty-state body but must not create a
     // comment — it only rewrites one that already exists (`action: "skipped"`
     // when none does).
     const { action } = upsertAttachmentsComment(target, body, run, marker, {
-        createIfMissing: count > 0,
+        createIfMissing: count > 0 && !skipLoneAdoptionCreate,
     });
     return { action, count, via: "gh" };
 }

package/dist/github-gh.d.ts

@@ -98,3 +98,30 @@ export declare function upsertAttachmentsComment(target: GhTarget, body: string,
 }): {
     action: "created" | "updated" | "skipped";
 };
+/** Cheap, regex-only reject: no http(s) URL at all means nothing to scan for.
+ * Mirrors `hasLinkCandidate` in apps/api/src/github-link-adopt.ts. */
+export declare function hasLinkCandidate(text: string): boolean;
+/**
+ * Distinct http(s) URLs found in `text`, trailing prose punctuation
+ * stripped, order preserved, first occurrence wins on duplicates. Ported
+ * verbatim from apps/api/src/github-link-adopt.ts's `extractCandidateUrls`
+ * so the two paths recognize the same URL spellings — resolution itself
+ * (storage host / embed host / `/f/` page → key, and the bound-workspace
+ * check) happens server-side inside `POST .../github/attach`, so this file
+ * doesn't need its own copy of that logic.
+ */
+export declare function extractCandidateUrls(text: string): string[];
+/**
+ * Best-effort concatenation of a PR/issue's current body plus every comment's
+ * current body, for link-adoption scanning. Returns "" on any `gh` failure
+ * (not authenticated, network, repo/number not found) — adoption degrades to
+ * a no-op rather than blocking the comment sync it rides along with.
+ *
+ * Unlike the webhook path (which re-scans one specific body/comment ref per
+ * event), the CLI has no per-event ref to key off of — `uploads comment` is
+ * one ad-hoc invocation — so this scans the PR/issue body and every comment
+ * on the thread in one pass every time it runs. That's a documented
+ * divergence: harmless (adoption is idempotent) but does mean a link posted
+ * in comment #1 gets rescanned on every later `uploads comment` run too.
+ */
+export declare function fetchAdoptionCandidateText(target: GhTarget, run: CommandRunner): string;

package/dist/github-gh.js

@@ -344,6 +344,72 @@ function reconcileAfterCreate(target, body, run, marker, createdRaw) {
         return null;
     }
 }
+// --- link adoption (issue #708, local-gh fallback parity with the bot's
+// #701/apps/api/src/github-link-adopt.ts) ---
+/** Cheap, regex-only reject: no http(s) URL at all means nothing to scan for.
+ * Mirrors `hasLinkCandidate` in apps/api/src/github-link-adopt.ts. */
+export function hasLinkCandidate(text) {
+    return /https?:\/\//i.test(text);
+}
+const URL_RE = /https?:\/\/[^\s)"'<>\]]+/gi;
+/**
+ * Distinct http(s) URLs found in `text`, trailing prose punctuation
+ * stripped, order preserved, first occurrence wins on duplicates. Ported
+ * verbatim from apps/api/src/github-link-adopt.ts's `extractCandidateUrls`
+ * so the two paths recognize the same URL spellings — resolution itself
+ * (storage host / embed host / `/f/` page → key, and the bound-workspace
+ * check) happens server-side inside `POST .../github/attach`, so this file
+ * doesn't need its own copy of that logic.
+ */
+export function extractCandidateUrls(text) {
+    const seen = new Set();
+    const out = [];
+    for (const m of text.matchAll(URL_RE)) {
+        const url = m[0].replace(/[.,;:]+$/, "");
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        out.push(url);
+    }
+    return out;
+}
+/**
+ * Best-effort concatenation of a PR/issue's current body plus every comment's
+ * current body, for link-adoption scanning. Returns "" on any `gh` failure
+ * (not authenticated, network, repo/number not found) — adoption degrades to
+ * a no-op rather than blocking the comment sync it rides along with.
+ *
+ * Unlike the webhook path (which re-scans one specific body/comment ref per
+ * event), the CLI has no per-event ref to key off of — `uploads comment` is
+ * one ad-hoc invocation — so this scans the PR/issue body and every comment
+ * on the thread in one pass every time it runs. That's a documented
+ * divergence: harmless (adoption is idempotent) but does mean a link posted
+ * in comment #1 gets rescanned on every later `uploads comment` run too.
+ */
+export function fetchAdoptionCandidateText(target, run) {
+    let body = "";
+    try {
+        body = run("gh", ["api", `repos/${target.repo}/issues/${target.num}`, "--jq", '.body // ""']);
+    }
+    catch {
+        // Not found / no access — fall through with an empty body; comments may
+        // still be readable.
+    }
+    let comments = "";
+    try {
+        comments = run("gh", [
+            "api",
+            `repos/${target.repo}/issues/${target.num}/comments?per_page=100`,
+            "--paginate",
+            "--jq",
+            '[.[].body] | join("\\n")',
+        ]);
+    }
+    catch {
+        // Same degrade — an empty comments blob just means nothing more to scan.
+    }
+    return `${body}\n${comments}`;
+}
 /** PATCH one comment's body via stdin, so the body is never shell-interpolated. */
 function patchComment(target, run, id, body) {
     run("gh", ["api", `repos/${target.repo}/issues/comments/${id}`, "-X", "PATCH", "-F", "body=@-"], body);

package/dist/screenshot-local.d.ts

@@ -62,6 +62,15 @@ export interface LocalCaptureOptions {
     hide?: string[];
     /** Emulate prefers-reduced-motion: reduce so animations settle deterministically. */
     reducedMotion?: boolean;
+    /**
+     * JS expression polled in the page (page.waitForFunction) after settle and
+     * before `evalJs`/capture — the caller's "app is interactive" signal. Lets a
+     * synthetic click in `evalJs` land after a framework (React/Next/…) has
+     * hydrated and attached its handlers, instead of firing on the still-inert
+     * server-rendered DOM. Throws `RENDER_FAILED` if it never becomes truthy
+     * within the capture timeout.
+     */
+    waitForExpr?: string;
     /** JS run via page.evaluate after settle, before capture. */
     evalJs?: string;
     /** JS injected via addInitScript before navigation. */

package/dist/screenshot-local.js

@@ -346,9 +346,28 @@ export async function captureLocal(opts) {
             }
         }
         const waitUntil = typeof opts.waitUntil === "string" ? opts.waitUntil : "load";
-        await page.goto(opts.url, { waitUntil, timeout: opts.timeoutMs ?? 30_000 });
+        const timeoutMs = opts.timeoutMs ?? 30_000;
+        await page.goto(opts.url, { waitUntil, timeout: timeoutMs });
         if (typeof opts.waitUntil === "number")
             await page.waitForTimeout(opts.waitUntil);
+        // Hydration-aware gate (issue #715): poll the caller's "app is interactive"
+        // predicate before running any eval or capturing. The load/networkidle
+        // settle strategies fire before a framework hydrates, so a synthetic
+        // click in `evalJs` would hit the inert server-rendered DOM with no
+        // handler attached. Waiting for the caller's own signal (e.g.
+        // `window.__hydrated === true`, or a class/attribute the app sets once
+        // interactive) closes that gap. A timeout means the predicate never
+        // became truthy — surface it clearly rather than capturing the un-ready
+        // page silently.
+        if (opts.waitForExpr) {
+            try {
+                await page.waitForFunction(opts.waitForExpr, undefined, { timeout: timeoutMs });
+            }
+            catch (err) {
+                throw new UploadsError(`--wait-for expression never became truthy within ${timeoutMs}ms: ${opts.waitForExpr}` +
+                    ` (${err instanceof Error ? err.message : String(err)})`, "RENDER_FAILED");
+            }
+        }
         // Hide overlays first, then run any user eval (which may depend on, or
         // deliberately override, the hidden state).
         if (opts.hide && opts.hide.length > 0) {

package/dist/screenshot.d.ts

@@ -99,6 +99,13 @@ export interface CaptureScreenshotOptions {
     hideDevTools?: boolean;
     /** Emulate prefers-reduced-motion: reduce so CSS/JS animations settle. */
     reducedMotion?: boolean;
+    /**
+     * JS expression polled in the page until truthy after settle, before
+     * `evalJs` and capture — the caller's "app is interactive" signal so a
+     * synthetic click in `evalJs` lands after framework hydration (issue #715).
+     * Local backend only — throws if the resolved backend is remote.
+     */
+    waitForExpr?: string;
     /** Run this JS in the page after settle, before capture (local backend only). */
     evalJs?: string;
     /** Inject this JS as an init script before navigation (local backend only). */
@@ -127,6 +134,7 @@ export interface CaptureScreenshotOptions {
         waitUntil: WaitUntil;
         hide?: string[];
         reducedMotion?: boolean;
+        waitForExpr?: string;
         evalJs?: string;
         initScript?: string;
         measureSelectors?: string[];

package/dist/screenshot.js

@@ -290,6 +290,12 @@ export async function captureScreenshot(opts) {
     if (backend === "remote" && (opts.evalJs !== undefined || opts.initScript !== undefined)) {
         throw new UploadsError("--eval and --init-script are local-only — use --via local", "USAGE");
     }
+    // --wait-for polls a JS predicate via the live local page (page.waitForFunction);
+    // the remote renderer has no eval escape hatch to evaluate it. Fail fast
+    // rather than silently ignore the caller's readiness signal.
+    if (backend === "remote" && opts.waitForExpr !== undefined) {
+        throw new UploadsError("--wait-for is local-only — use --via local", "USAGE");
+    }
     // Selector-based annotation measurement needs a live local page — the
     // remote render endpoint has no eval escape hatch to run
     // getBoundingClientRect. Covers both explicit --via remote and auto
@@ -315,6 +321,7 @@ export async function captureScreenshot(opts) {
             waitUntil,
             hide,
             reducedMotion: opts.reducedMotion,
+            waitForExpr: opts.waitForExpr,
             evalJs: opts.evalJs,
             initScript: opts.initScript,
             measureSelectors: opts.measureSelectors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,