@buildinternet/uploads 0.42.1 → 0.43.0

package/dist/hooks-install.d.ts

@@ -2,12 +2,20 @@
  * Install thin user-global hook manifests for Grok and Cursor.
  *
  * Claude and Codex ship the same PreToolUse hook via their plugins
- * (`hooks/hooks.json` → `uploads hook pre-pr-screenshot`). Do not also write
+ * (`hooks/hooks.json` → HOOK_COMMAND). Do not also write
  * ~/.codex/hooks.json here, or the reminder would fire twice.
  *
  * Idempotent: skip when our command string is already present.
+ * An older bare `uploads hook …` entry is upgraded in place.
  */
-export declare const HOOK_COMMAND = "uploads hook pre-pr-screenshot";
+/** What the harness actually runs once `uploads` is on PATH. */
+export declare const HOOK_INVOCATION = "uploads hook pre-pr-screenshot";
+/**
+ * Fail-open shell used in every harness manifest.
+ * A missing `uploads` binary is a silent no-op (exit 0, no stderr) so plugin
+ * users without the CLI do not get a hook-failure annotation on every shell tool.
+ */
+export declare const HOOK_COMMAND = "if command -v uploads >/dev/null 2>&1; then uploads hook pre-pr-screenshot; fi";
 export type HookWriteResult = {
     path: string;
     action: "wrote" | "merged" | "skipped" | "would-write" | "would-merge";

package/dist/hooks-install.js

@@ -2,15 +2,23 @@
  * Install thin user-global hook manifests for Grok and Cursor.
  *
  * Claude and Codex ship the same PreToolUse hook via their plugins
- * (`hooks/hooks.json` → `uploads hook pre-pr-screenshot`). Do not also write
+ * (`hooks/hooks.json` → HOOK_COMMAND). Do not also write
  * ~/.codex/hooks.json here, or the reminder would fire twice.
  *
  * Idempotent: skip when our command string is already present.
+ * An older bare `uploads hook …` entry is upgraded in place.
  */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-export const HOOK_COMMAND = "uploads hook pre-pr-screenshot";
+/** What the harness actually runs once `uploads` is on PATH. */
+export const HOOK_INVOCATION = "uploads hook pre-pr-screenshot";
+/**
+ * Fail-open shell used in every harness manifest.
+ * A missing `uploads` binary is a silent no-op (exit 0, no stderr) so plugin
+ * users without the CLI do not get a hook-failure annotation on every shell tool.
+ */
+export const HOOK_COMMAND = `if command -v uploads >/dev/null 2>&1; then ${HOOK_INVOCATION}; fi`;
 const TIMEOUT_SEC = 15;
 const GROK_PAYLOAD = {
     description: "Advisory reminder to stage screenshots on uploads.sh before opening a PR that touches UI files.",
@@ -38,6 +46,16 @@ function containsCommand(filePath) {
         return false;
     }
 }
+function hookCommandOf(entry) {
+    if (!entry || typeof entry !== "object")
+        return undefined;
+    const command = entry.command;
+    return typeof command === "string" ? command : undefined;
+}
+function isOurHookEntry(entry) {
+    const command = hookCommandOf(entry);
+    return Boolean(command?.includes(HOOK_INVOCATION));
+}
 function writeJson(filePath, value) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
@@ -79,7 +97,17 @@ function mergeCursor(home, dryRun) {
         ? { ...existing.hooks }
         : {};
     const list = Array.isArray(hooks.beforeShellExecution) ? [...hooks.beforeShellExecution] : [];
-    list.push({ command: HOOK_COMMAND, timeout: TIMEOUT_SEC });
+    const ours = list.findIndex(isOurHookEntry);
+    const nextEntry = { command: HOOK_COMMAND, timeout: TIMEOUT_SEC };
+    if (ours >= 0) {
+        if (hookCommandOf(list[ours]) === HOOK_COMMAND) {
+            return { path: filePath, action: "skipped" };
+        }
+        list[ours] = { ...list[ours], ...nextEntry };
+    }
+    else {
+        list.push(nextEntry);
+    }
     hooks.beforeShellExecution = list;
     existing.hooks = hooks;
     if (existing.version === undefined)

package/dist/mcp/tools.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"),
@@ -426,7 +426,7 @@ 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);
@@ -736,7 +736,7 @@ 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);
@@ -969,7 +969,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 +1037,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 +1093,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 +1124,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 +1147,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 +1184,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 +1223,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 +1249,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 +1266,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.usage();
             },
         },
@@ -1282,7 +1282,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.reconcile();
             },
         },
@@ -1298,7 +1298,7 @@ export function createUploadsMcpTools(opts) {
                 additionalProperties: false,
             },
             async handler(args) {
-                const { client } = clientFor(args);
+                const { client } = await clientFor(args);
                 return client.purgeExpired();
             },
         },
@@ -1320,7 +1320,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 +1336,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 +1353,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.1",
+  "version": "0.43.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,