@buildinternet/uploads 0.42.2 → 0.44.0

package/dist/mcp/tools.js

@@ -1,5 +1,5 @@
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, ghListPrefixes, ghMergedList, makeGhTarget, mergeStagingMeta, resolveGhPrefixSafe, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
+import { buildDoctorReport, ghListPrefixes, ghMergedList, makeGhTarget, mergeStagingMeta, resolveAutoPrTarget, resolveGhPrefixSafe, resolvePutNudgeContext, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, autoPrNoteText, putNudgeText, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
@@ -108,7 +108,7 @@ export function createUploadsMcpTools(opts) {
     const { globals } = opts;
     const run = opts.runner ?? execRunner;
     const clientFactory = opts.clientFactory ?? createUploadsClient;
-    function clientFor(args, requireToken = true) {
+    async function clientFor(args, requireToken = true) {
         const config = resolveConfig({
             apiUrl: globals.apiUrl,
             token: globals.token,
@@ -151,7 +151,7 @@ export function createUploadsMcpTools(opts) {
                 const title = optString(args, "title");
                 if (!title)
                     usage("title is required");
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.createGallery({ title, description: optString(args, "description") });
             },
         },
@@ -171,7 +171,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.getGallery(galleryId(args));
             },
         },
@@ -197,7 +197,7 @@ export function createUploadsMcpTools(opts) {
                 const objectKey = optString(args, "objectKey");
                 if (!objectKey)
                     usage("objectKey is required");
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 const id = galleryId(args);
                 const current = await client.getGallery(id);
                 return client.addGalleryItem(id, objectKey, {
@@ -228,7 +228,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 const id = galleryId(args);
                 const current = await client.getGallery(id);
                 return client.linkGalleryExternalReference(id, {
@@ -259,7 +259,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.findGalleriesByReference({
                     ...galleryReference(args),
                     limit: optPosInt(args, "limit"),
@@ -345,9 +345,13 @@ export function createUploadsMcpTools(opts) {
                     },
                     ...frameProps,
                     noGit: { type: "boolean", description: "Don't derive the repo segment from git." },
+                    noPr: {
+                        type: "boolean",
+                        description: "Skip auto-PR context (issue #700): without pr/issue/key/ref/prefix/destination, a call on a branch mapping to exactly one open PR otherwise behaves as if pr had been passed (stable key + managed comment sync when comment is set). Also opts out via UPLOADS_NO_AUTO_PR=1.",
+                    },
                     comment: {
                         type: "boolean",
-                        description: "With pr/issue: create or update the managed attachments comment. Posts as uploads-sh[bot] when the GitHub App is installed on the repo; otherwise via local gh auth (best-effort).",
+                        description: "With pr/issue (or auto-detected PR context): create or update the managed attachments comment. Posts as uploads-sh[bot] when the GitHub App is installed on the repo; otherwise via local gh auth (best-effort).",
                     },
                     dryRun: {
                         type: "boolean",
@@ -426,21 +430,44 @@ export function createUploadsMcpTools(opts) {
                 catch (err) {
                     usage(err instanceof Error ? err.message : String(err));
                 }
-                const { config, client } = clientFor(args);
+                const { config, client } = await clientFor(args);
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
                 const frameOpts = mcpFrameOptions(args);
                 const optimizeOpts = mcpOptimizeOptions(args, defaults);
                 const noGit = optBool(args, "noGit") || defaults.noGit === true;
+                const noAutoPr = optBool(args, "noPr") || defaults.noAutoPr === true;
                 const alt = optString(args, "alt");
                 const width = optPosInt(args, "width") ?? defaults.width;
                 const contentType = optString(args, "contentType");
+                // Auto-PR context (issue #700): local stdio MCP put mirrors the CLI
+                // default — no pr/issue/key/ref/prefix/destination, not noGit/noPr,
+                // on a branch that maps to exactly one open PR behaves as if `pr`
+                // had been passed (stable key + managed comment sync) instead of
+                // the #403 staging default below. Never throws — see
+                // resolveAutoPrTarget.
+                const autoPrTarget = target
+                    ? undefined
+                    : resolveAutoPrTarget({
+                        ghTarget: target,
+                        keyHint: keyArg,
+                        refArg,
+                        prefixArg,
+                        destinationArg: destArg,
+                        noGit,
+                        noAutoPr,
+                        repoArg: optString(args, "repo") ?? defaults.repo,
+                        run,
+                    });
+                const effectiveTarget = target ?? autoPrTarget;
                 // Bare-put branch staging (issue #403): local stdio MCP put mirrors
                 // the CLI default — no pr/issue/key/ref/prefix/destination, not
                 // noGit, on a non-default git branch stages to the branch prefix
                 // (identical key/metadata to `attach --branch`) instead of the
                 // dated layout. Never throws — see resolvePutStagingTarget.
+                // effectiveTarget (explicit pr/issue OR the #700 auto-PR match)
+                // wins over staging, same as it wins over the dated layout.
                 const stagingTarget = resolvePutStagingTarget({
-                    ghTarget: target,
+                    ghTarget: effectiveTarget,
                     keyHint: keyArg,
                     refArg,
                     prefixArg,
@@ -449,6 +476,21 @@ export function createUploadsMcpTools(opts) {
                     repoArg: optString(args, "repo") ?? defaults.repo,
                     run,
                 });
+                // Bare-put nudge context (issue #393/#700): only relevant when
+                // neither auto-PR nor staging took over. Finished into a hint once
+                // upload keys exist, below.
+                const nudgeCtx = effectiveTarget || stagingTarget
+                    ? undefined
+                    : resolvePutNudgeContext({
+                        quiet: false,
+                        noNudge: defaults.noNudge === true,
+                        ghTarget: target,
+                        keyHint: keyArg,
+                        noGit,
+                        repoArg: optString(args, "repo") ?? defaults.repo,
+                        run,
+                    });
+                const autoPrHint = autoPrTarget ? autoPrNoteText(autoPrTarget.num) : undefined;
                 // Derived `repo` metadata (spec: 2026-08-11-screenshots-project-grouping-design.md).
                 // Same derivation the CLI does; MCP always derives (no --no-auto), so
                 // this is only suppressed by noGit. metadataProp's contract: omitting
@@ -468,7 +510,7 @@ export function createUploadsMcpTools(opts) {
                     : metadataWithRepo;
                 const putShared = {
                     client,
-                    ghTarget: target,
+                    ghTarget: effectiveTarget,
                     ghBranchTarget: stagingTarget,
                     prefix: resolvedPrefix ?? defaults.prefix,
                     repo: optString(args, "repo") ?? defaults.repo,
@@ -496,11 +538,15 @@ export function createUploadsMcpTools(opts) {
                     if (uploads.length === 0 && failures.length > 0) {
                         throw new ToolBatchError(batchFailureMessage(failures), { uploads, failures });
                     }
-                    if (wantComment && target && uploads.length > 0) {
-                        const { comment, commentError } = await syncComment(client, target, config.workspace);
-                        return { uploads, failures, comment, commentError };
+                    const hint = autoPrHint ??
+                        (nudgeCtx && uploads.length > 0
+                            ? putNudgeText(nudgeCtx.branch, nudgeCtx.pr, uploads.map((u) => u.key))
+                            : undefined);
+                    if (wantComment && effectiveTarget && uploads.length > 0) {
+                        const { comment, commentError } = await syncComment(client, effectiveTarget, config.workspace);
+                        return { uploads, failures, comment, commentError, ...(hint ? { hint } : {}) };
                     }
-                    return { uploads, failures };
+                    return { uploads, failures, ...(hint ? { hint } : {}) };
                 }
                 // Single-file: contentBase64 still supported; paths go through uploadPuts.
                 if (contentBase64 !== undefined) {
@@ -509,7 +555,7 @@ export function createUploadsMcpTools(opts) {
                     const { result, prepared, markdown } = await uploadPreparedImage(client, bytes, sourceName, {
                         frame: frameOpts,
                         optimize: optimizeOpts,
-                        ghTarget: target,
+                        ghTarget: effectiveTarget,
                         ghBranchTarget: stagingTarget,
                         key: keyArg,
                         prefix: resolvedPrefix ?? defaults.prefix,
@@ -531,9 +577,19 @@ export function createUploadsMcpTools(opts) {
                         outputBytes: prepared.outputBytes,
                         filename: prepared.filename,
                     };
-                    if (wantComment && target) {
-                        const { comment, commentError } = await syncComment(client, target, config.workspace);
-                        return { ...result, markdown, optimize, frame: prepared.frame, comment, commentError };
+                    const hint = autoPrHint ??
+                        (nudgeCtx ? putNudgeText(nudgeCtx.branch, nudgeCtx.pr, [result.key]) : undefined);
+                    if (wantComment && effectiveTarget) {
+                        const { comment, commentError } = await syncComment(client, effectiveTarget, config.workspace);
+                        return {
+                            ...result,
+                            markdown,
+                            optimize,
+                            frame: prepared.frame,
+                            comment,
+                            commentError,
+                            ...(hint ? { hint } : {}),
+                        };
                     }
                     return {
                         ...result,
@@ -541,6 +597,7 @@ export function createUploadsMcpTools(opts) {
                         optimize,
                         frame: prepared.frame,
                         ...(dryRun ? { dryRun: true } : {}),
+                        ...(hint ? { hint } : {}),
                     };
                 }
                 const { uploads, failures, firstError } = await uploadPuts({
@@ -553,6 +610,8 @@ export function createUploadsMcpTools(opts) {
                     throw firstError instanceof Error ? firstError : new Error(String(firstError));
                 }
                 const u = uploads[0];
+                const hint = autoPrHint ??
+                    (nudgeCtx ? putNudgeText(nudgeCtx.branch, nudgeCtx.pr, [u.key]) : undefined);
                 const flat = {
                     workspace: u.workspace,
                     key: u.key,
@@ -566,9 +625,10 @@ export function createUploadsMcpTools(opts) {
                     optimize: u.optimize,
                     frame: u.frame,
                     ...(dryRun ? { dryRun: true } : {}),
+                    ...(hint ? { hint } : {}),
                 };
-                if (wantComment && target) {
-                    const { comment, commentError } = await syncComment(client, target, config.workspace);
+                if (wantComment && effectiveTarget) {
+                    const { comment, commentError } = await syncComment(client, effectiveTarget, config.workspace);
                     return { ...flat, comment, commentError };
                 }
                 return flat;
@@ -673,9 +733,13 @@ export function createUploadsMcpTools(opts) {
                     keepExif: { type: "boolean", description: "Keep EXIF/XMP/ICC when optimizing." },
                     ...frameProps,
                     noGit: { type: "boolean", description: "Don't derive the repo segment from git." },
+                    noPr: {
+                        type: "boolean",
+                        description: "Skip auto-PR context (issue #700): without pr/issue/key/ref/prefix/destination, a call on a branch mapping to exactly one open PR otherwise behaves as if pr had been passed. Also opts out via UPLOADS_NO_AUTO_PR=1.",
+                    },
                     comment: {
                         type: "boolean",
-                        description: "With pr/issue: create/update the managed attachments comment (best-effort).",
+                        description: "With pr/issue (or auto-detected PR context): create/update the managed attachments comment (best-effort).",
                     },
                     galleryId: {
                         type: "string",
@@ -736,21 +800,43 @@ export function createUploadsMcpTools(opts) {
                 const metadata = metadataArgWithCanonical(args);
                 if (metadata)
                     validateMetaMap(metadata);
-                const { config, client } = clientFor(args);
+                const { config, client } = await clientFor(args);
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
                 const frameOpts = mcpFrameOptions(args);
                 const optimizeOpts = mcpOptimizeOptions(args, defaults);
                 const noGit = optBool(args, "noGit") || defaults.noGit === true;
+                const noAutoPr = optBool(args, "noPr") || defaults.noAutoPr === true;
                 const alt = optString(args, "alt");
                 const width = optPosInt(args, "width") ?? defaults.width;
+                // Auto-PR context (issue #700): mirrors the CLI screenshot command
+                // and the put tool above — no pr/issue/key/ref/prefix/destination,
+                // not noGit/noPr, on a branch that maps to exactly one open PR
+                // behaves as if `pr` had been passed (stable key + managed comment
+                // sync) instead of the #469 auto-staging default below. Never
+                // throws — see resolveAutoPrTarget.
+                const autoPrTarget = target
+                    ? undefined
+                    : resolveAutoPrTarget({
+                        ghTarget: target,
+                        keyHint: keyArg,
+                        refArg,
+                        prefixArg,
+                        destinationArg: destArg,
+                        noGit,
+                        noAutoPr,
+                        repoArg: optString(args, "repo") ?? defaults.repo,
+                        run,
+                    });
+                const effectiveTarget = target ?? autoPrTarget;
                 // Auto branch staging (issue #469 lever 1): mirrors the CLI screenshot
                 // command and the put tool above (issue #403) — no pr/issue/key/ref/
                 // prefix/destination, not noGit, on a non-default git branch stages
                 // to the branch prefix (identical key/metadata to `attach --branch`)
                 // instead of the dated `screenshots/<repo>/<date>/...` layout. Never
-                // throws — see resolvePutStagingTarget.
+                // throws — see resolvePutStagingTarget. effectiveTarget (explicit
+                // pr/issue OR the #700 auto-PR match) wins over staging.
                 const stagingTarget = resolvePutStagingTarget({
-                    ghTarget: target,
+                    ghTarget: effectiveTarget,
                     keyHint: keyArg,
                     refArg,
                     prefixArg,
@@ -759,13 +845,27 @@ export function createUploadsMcpTools(opts) {
                     repoArg: optString(args, "repo") ?? defaults.repo,
                     run,
                 });
+                // Bare-screenshot nudge context (issue #393/#700): only relevant
+                // when neither auto-PR nor staging took over.
+                const nudgeCtx = effectiveTarget || stagingTarget
+                    ? undefined
+                    : resolvePutNudgeContext({
+                        quiet: false,
+                        noNudge: defaults.noNudge === true,
+                        ghTarget: target,
+                        keyHint: keyArg,
+                        noGit,
+                        repoArg: optString(args, "repo") ?? defaults.repo,
+                        run,
+                    });
+                const autoPrHint = autoPrTarget ? autoPrNoteText(autoPrTarget.num) : undefined;
                 let resolvedPrefix;
                 try {
                     resolvedPrefix = resolvePutPrefix({
                         destination: destArg,
                         prefix: prefixArg,
                         key: keyArg,
-                        ghAttachment: Boolean(target) || stagingTarget !== undefined,
+                        ghAttachment: Boolean(effectiveTarget) || stagingTarget !== undefined,
                     });
                 }
                 catch (err) {
@@ -837,10 +937,10 @@ export function createUploadsMcpTools(opts) {
                 }
                 // Resolved once (issue #631), only now that upload is actually
                 // about to happen — never per file (screenshot uploads exactly one).
-                const ghPrefix = target
+                const ghPrefix = effectiveTarget
                     ? await resolveGhPrefixSafe(client, {
-                        repo: target.repo,
-                        target: { kind: target.kind, num: target.num },
+                        repo: effectiveTarget.repo,
+                        target: { kind: effectiveTarget.kind, num: effectiveTarget.num },
                     })
                     : stagingTarget
                         ? await resolveGhPrefixSafe(client, {
@@ -851,7 +951,7 @@ export function createUploadsMcpTools(opts) {
                 const { result, prepared, markdown } = await uploadPreparedImage(client, captured.png, captured.filename, {
                     frame: frameOpts,
                     optimize: optimizeOpts,
-                    ghTarget: target,
+                    ghTarget: effectiveTarget,
                     ghBranchTarget: stagingTarget,
                     ghPrefix,
                     key: keyArg,
@@ -897,14 +997,19 @@ export function createUploadsMcpTools(opts) {
                     frame: prepared.frame,
                     gallery,
                     ...(dryRun ? { dryRun: true } : {}),
-                    // Full-page height cap note (issue #652), mirrors the CLI's stderr
-                    // note + `hint` field.
+                    // Hint precedence (mirrors the CLI): the full-page height cap note
+                    // (issue #652) is about the just-captured image itself, more
+                    // immediately actionable than the #700 auto-PR/nudge notes below.
                     ...(captured.capped?.clipped
                         ? { hint: screenshotModule.clipHintText(captured.capped.maxHeightPx, "maxHeight") }
-                        : {}),
+                        : autoPrHint
+                            ? { hint: autoPrHint }
+                            : nudgeCtx
+                                ? { hint: putNudgeText(nudgeCtx.branch, nudgeCtx.pr, [result.key]) }
+                                : {}),
                 };
-                if (wantComment && target) {
-                    const { comment, commentError } = await syncComment(client, target, config.workspace);
+                if (wantComment && effectiveTarget) {
+                    const { comment, commentError } = await syncComment(client, effectiveTarget, config.workspace);
                     return { ...flat, comment, commentError };
                 }
                 return flat;
@@ -969,7 +1074,7 @@ export function createUploadsMcpTools(opts) {
                 const explicitTarget = ghTargetFromArgs(args, run);
                 const target = explicitTarget ??
                     resolveCurrentPullRequest(resolveRepo(optString(args, "repo"), run), run);
-                const { config, client } = clientFor(args);
+                const { config, client } = await clientFor(args);
                 const contentType = optString(args, "contentType");
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
                 const frameOpts = mcpFrameOptions(args);
@@ -1037,7 +1142,7 @@ export function createUploadsMcpTools(opts) {
                 const prefixArg = optString(args, "prefix");
                 let prefix = prefixArg ?? (defaults.prefix ? `${defaults.prefix}/` : undefined);
                 const target = ghTargetFromArgs(args, run);
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 // Also list every active private prefix, if any (issue #631) —
                 // mirrors syncAttachmentsComment's gh-fallback gather: a repo's
                 // attachment history can be split across the plain shape and
@@ -1093,7 +1198,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 const repo = resolveRepo(optString(args, "repo"), run);
                 const branch = optString(args, "branch") ?? resolveCurrentBranch(run);
                 return resolveStaged({ client, repo, branch });
@@ -1124,7 +1229,7 @@ export function createUploadsMcpTools(opts) {
                     usage("key is required");
                 if (optBool(args, "dryRun"))
                     return { key, deleted: false, dryRun: true };
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.delete(key);
             },
         },
@@ -1147,7 +1252,7 @@ export function createUploadsMcpTools(opts) {
                 const key = optString(args, "key");
                 if (!key)
                     usage("key is required");
-                return clientFor(args).client.getMetadata(key);
+                return (await clientFor(args)).client.getMetadata(key);
             },
         },
         {
@@ -1184,7 +1289,7 @@ export function createUploadsMcpTools(opts) {
                 }
                 if (set)
                     validateMetaMap(set);
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.patchMetadata(key, { set, delete: del });
             },
         },
@@ -1223,7 +1328,7 @@ export function createUploadsMcpTools(opts) {
                 }
                 if (hasMeta)
                     validateMetaMap(filters);
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.findFiles(filters, {
                     name,
                     prefix: optString(args, "prefix"),
@@ -1249,7 +1354,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 const key = optString(args, "key");
                 return key ? client.listMetadataValues(key) : client.listMetadataKeys();
             },
@@ -1266,7 +1371,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.usage();
             },
         },
@@ -1282,7 +1387,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.reconcile();
             },
         },
@@ -1298,7 +1403,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.purgeExpired();
             },
         },
@@ -1320,7 +1425,7 @@ export function createUploadsMcpTools(opts) {
                 const target = ghTargetFromArgs(args, run);
                 if (!target)
                     usage("comment requires pr or issue");
-                const { config, client } = clientFor(args);
+                const { config, client } = await clientFor(args);
                 // Explicit resync, same as `uploads comment` (issue #480).
                 const result = await syncAttachmentsComment(client, target, run, config.workspace, {
                     resync: true,
@@ -1336,7 +1441,7 @@ export function createUploadsMcpTools(opts) {
             description: "Check uploads.sh API liveness. No auth or arguments required.",
             inputSchema: { type: "object", properties: {}, additionalProperties: false },
             async handler(args) {
-                const { config, client } = clientFor(args, false);
+                const { config, client } = await clientFor(args, false);
                 const result = await client.health();
                 return { ...result, apiUrl: config.apiUrl };
             },
@@ -1353,7 +1458,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { config, client } = clientFor(args);
+                const { config, client } = await clientFor(args);
                 return buildDoctorReport(config, client);
             },
         },

package/dist/project-context-nudge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * No-project-context nudge (issue #692 follow-up): a path-tagged upload with
+ * no repo/gh.repo/app metadata and no real (non-local) origin lands in the
+ * screenshots page's "local dev" / "Other" fallback buckets. One advisory
+ * stderr line teaches the fix at the moment the context went missing. The
+ * predicate mirrors apps/api's projectLabelFromMeta fallback rules exactly —
+ * a real URL host is a meaningful group, so it never fires there.
+ */
+export declare function noProjectContextNudge(meta: Record<string, string> | undefined): string | undefined;

package/dist/project-context-nudge.js

@@ -0,0 +1,39 @@
+/**
+ * No-project-context nudge (issue #692 follow-up): a path-tagged upload with
+ * no repo/gh.repo/app metadata and no real (non-local) origin lands in the
+ * screenshots page's "local dev" / "Other" fallback buckets. One advisory
+ * stderr line teaches the fix at the moment the context went missing. The
+ * predicate mirrors apps/api's projectLabelFromMeta fallback rules exactly —
+ * a real URL host is a meaningful group, so it never fires there.
+ */
+/** Hosts that identify a dev machine, not an app — same set as the API's
+ * isLocalHostname (apps/api/src/file-metadata.ts). */
+function isLocalHostname(hostname) {
+    const bare = hostname.toLowerCase();
+    return (bare === "localhost" ||
+        bare.endsWith(".localhost") ||
+        bare === "127.0.0.1" ||
+        bare === "0.0.0.0" ||
+        bare === "[::1]");
+}
+export function noProjectContextNudge(meta) {
+    // Only `path`-tagged uploads appear on the screenshots page at all.
+    if (!meta?.path)
+        return undefined;
+    if (meta.repo || meta["gh.repo"] || meta.app)
+        return undefined;
+    let bucket = "Other";
+    if (meta.url) {
+        try {
+            const parsed = new URL(meta.url);
+            if (!isLocalHostname(parsed.hostname))
+                return undefined; // real host = real group
+            bucket = "local dev";
+        }
+        catch {
+            // unparseable url is just "no url"
+        }
+    }
+    return (`note: no repo detected — the screenshots page will group this under "${bucket}". ` +
+        `Run from inside your project repo, or pass --app <name>.`);
+}

package/package.json

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