@buildinternet/uploads 0.8.0 → 0.9.0

package/README.md

@@ -98,7 +98,7 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 ## MCP server
 
-`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows: `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`. Gallery tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `usage`, `reconcile`, `purge_expired`, `comment`, `health`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`health` needs no auth).
+`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows: `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`. Gallery tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `set_metadata`, `find_files`, `usage`, `reconcile`, `purge_expired`, `comment`, `health`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. `put` and `attach` accept a `metadata` param (same `gh.*` auto-injection as the CLI's `attach`); `set_metadata` and `find_files` mirror `uploads meta set` and `uploads find`. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`health` needs no auth).
 
 ```json
 { "command": "uploads", "args": ["--env-file", "/path/to/.env", "mcp"] }
@@ -106,7 +106,7 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 Or with `UPLOADS_TOKEN`/`UPLOADS_WORKSPACE` in the environment or user config. Claude Code: `claude mcp add uploads -- uploads --env-file /path/to/.env mcp`.
 
-For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. `uploads install` registers the skill + hosted MCP (short progress; `--verbose` for underlying output). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
+For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. The hosted `put` also accepts a `metadata` param. `uploads install` registers the skill + hosted MCP (short progress; `--verbose` for underlying output). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
 
 ## Programmatic use
 

package/dist/commands.js

@@ -9,7 +9,7 @@ import { UploadsError } from "./errors.js";
 import { writeJson, writeStdout } from "./io.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, attachmentsCommentBody, normalizeGithubCoordinate, } from "./github.js";
-import { resolveRepo, resolveCurrentPullRequest, execRunner, upsertAttachmentsComment, } from "./github-gh.js";
+import { resolveRepo, resolveCurrentPullRequest, classifyGhNumber, execRunner, upsertAttachmentsComment, } from "./github-gh.js";
 import { resolvePutPrefix } from "./destinations.js";
 import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
 import { applyFrame, resolveFrameId } from "./frame.js";
@@ -65,6 +65,8 @@ Options:
   --optimize-quality <1-100>  WebP quality (default: 85)
   --keep-exif           Keep EXIF/XMP/ICC when optimizing (default: strip for privacy)
   --no-git              Don't derive --repo from git (or UPLOADS_NO_GIT=1)
+  --auto                Resolve current PR/issue and stamp gh.* metadata (default on)
+  --no-auto             Skip gh.* auto-resolution (also skipped by --no-git or UPLOADS_NO_AUTO_META=1)
   --workspace, -w <name>  Override workspace (wins over UPLOADS_WORKSPACE and token inference)
   --format human|url|markdown|json
   --pr <num>            Attach to a pull request: key gh/<owner>/<repo>/pull/<num>/<name> (stable URL, no hash)
@@ -107,6 +109,24 @@ export function makeGhTarget(pr, issue, repoArg, run) {
 function ghTargetFromFlags(flags, run) {
     return makeGhTarget(flagInt(flags, "--pr", "--pr"), flagInt(flags, "--issue", "--issue"), flagString(flags, "--repo"), run);
 }
+/**
+ * Best-effort GitHub target for the default put path (no --pr/--issue). A
+ * numeric --ref is classified as pull vs issue; otherwise the current branch's
+ * PR is resolved. Never throws — any failure yields undefined so the upload
+ * proceeds without gh metadata.
+ */
+function resolveAutoGhTarget(repoArg, ref, run) {
+    try {
+        const repo = resolveRepo(repoArg, run);
+        if (ref !== undefined && /^\d+$/.test(ref) && Number(ref) > 0) {
+            return classifyGhNumber(repo, Number.parseInt(ref, 10), run);
+        }
+        return resolveCurrentPullRequest(repo, run);
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Shared put/attach optimize flags + UPLOADS_NO_OPTIMIZE default. */
 export function optimizeOptionsFromFlags(flags, defaults) {
     if (flags.has("--no-optimize") && typeof flags.get("--no-optimize") === "string") {
@@ -363,6 +383,11 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         }
         if (!ctx.quiet && comment)
             process.stderr.write(`>> attachments comment ${comment.action}\n`);
+        // attach auto-writes gh.* metadata; point the user at how to find it later.
+        if (!ctx.quiet) {
+            const ref = ghMetadataFromTarget(target)["gh.ref"];
+            process.stderr.write(`>> find these later: uploads find gh.ref=${ref}\n`);
+        }
     }
     return 0;
 }
@@ -390,13 +415,19 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const nameFlag = flagString(parsed.flags, "--name");
     const dryRun = flagBool(parsed.flags, "--dry-run");
     // Validate --meta up front (fail fast, before reading/optimizing the file).
-    const metadata = (() => {
+    const userMeta = (() => {
         const pairs = flagValues(parsed.flags, "--meta");
         return pairs.length > 0 ? parseMetaFlags(pairs) : undefined;
     })();
     if (wantComment && typeof parsed.flags.get("--comment") === "string") {
         throw new UsageError("--comment takes no value — place it after the file argument");
     }
+    if (parsed.flags.has("--auto") && typeof parsed.flags.get("--auto") === "string") {
+        throw new UsageError("--auto takes no value");
+    }
+    if (parsed.flags.has("--no-auto") && typeof parsed.flags.get("--no-auto") === "string") {
+        throw new UsageError("--no-auto takes no value");
+    }
     if (wantComment && !ghTarget)
         throw new UsageError("--comment requires --pr or --issue");
     if (ghTarget) {
@@ -474,6 +505,43 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             process.stderr.write(`>> ${note}\n`);
     }
     const noGit = flagBool(parsed.flags, "--no-git") || defaults.noGit === true;
+    // gh.* metadata: explicit --pr/--issue target wins over --meta; otherwise
+    // best-effort auto resolution (on by default) where --meta wins. --no-git,
+    // --no-auto, or UPLOADS_NO_AUTO_META disable auto; --auto forces past the
+    // config default but never past --no-git (no repo to resolve).
+    let metadata = userMeta;
+    let attachedRef;
+    if (ghTarget) {
+        const merged = { ...userMeta, ...ghMetadataFromTarget(ghTarget) };
+        validateMetaMap(merged); // enforce 24-key/8KB caps on the merged map (matches attach)
+        metadata = merged;
+        attachedRef = merged["gh.ref"];
+    }
+    else {
+        const autoEnabled = !noGit &&
+            !flagBool(parsed.flags, "--no-auto") &&
+            (flagBool(parsed.flags, "--auto") || defaults.noAutoMeta !== true);
+        if (autoEnabled) {
+            const autoTarget = resolveAutoGhTarget(flagString(parsed.flags, "--repo") ?? defaults.repo, flagString(parsed.flags, "--ref") ?? defaults.ref, run);
+            if (autoTarget) {
+                const autoMeta = ghMetadataFromTarget(autoTarget);
+                const merged = { ...autoMeta, ...userMeta };
+                // Auto resolution must never fail the upload: if merging the gh.* pairs
+                // would exceed the metadata caps, drop them and upload with --meta only.
+                try {
+                    validateMetaMap(merged);
+                    metadata = merged;
+                    attachedRef = merged["gh.ref"];
+                }
+                catch {
+                    // keep metadata = userMeta (already validated); skip auto gh.*
+                }
+            }
+        }
+    }
+    if (attachedRef && !ctx.quiet && format === "human") {
+        process.stderr.write(`>> attached to ${attachedRef}\n`);
+    }
     let key = ghTarget ? ghAttachmentKey(ghTarget, filename) : keyHint;
     if (key && prepared.optimized)
         key = rewriteKeyExtension(key, filename);
@@ -805,8 +873,15 @@ async function runFindFiles(ctx, filters, flags) {
     if (ctx.json)
         await writeJson(result);
     else
-        for (const item of result.items)
-            await writeStdout(`${item.key}${item.url ? `  ${item.url}` : ""}\n`);
+        for (const item of result.items) {
+            // LIST_HELP promises matched metadata in the output; render it inline
+            // (sorted for stable output) so human mode honors that, not just --json.
+            const meta = Object.entries(item.metadata)
+                .toSorted(([a], [b]) => a.localeCompare(b))
+                .map(([k, v]) => `${k}=${v}`)
+                .join(" ");
+            await writeStdout(`${item.key}${item.url ? `  ${item.url}` : ""}${meta ? `  ${meta}` : ""}\n`);
+        }
     return 0;
 }
 export async function runList(ctx, args, help = false, run = execRunner) {
@@ -910,6 +985,11 @@ export async function runMeta(ctx, args, help = false) {
             const result = await ctx.client.getMetadata(key);
             if (ctx.json)
                 await writeJson(result);
+            else if (Object.keys(result.metadata).length === 0) {
+                // Empty stdout reads as failure; a stderr note keeps stdout parseable.
+                if (!ctx.quiet)
+                    process.stderr.write("(no metadata)\n");
+            }
             else
                 for (const [k, v] of Object.entries(result.metadata))
                     await writeStdout(`${k}=${v}\n`);

package/dist/config-file.d.ts

@@ -1,5 +1,5 @@
 import type { UploadsClientConfig } from "./config.js";
-export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_DEFAULT_PREFIX", "UPLOADS_DEFAULT_REPO", "UPLOADS_DEFAULT_REF", "UPLOADS_DEFAULT_WIDTH", "UPLOADS_NO_GIT", "UPLOADS_NO_OPTIMIZE", "UPLOADS_KEEP_EXIF"];
+export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_DEFAULT_PREFIX", "UPLOADS_DEFAULT_REPO", "UPLOADS_DEFAULT_REF", "UPLOADS_DEFAULT_WIDTH", "UPLOADS_NO_GIT", "UPLOADS_NO_OPTIMIZE", "UPLOADS_KEEP_EXIF", "UPLOADS_NO_AUTO_META"];
 export type UploadsConfigKey = (typeof UPLOADS_CONFIG_KEYS)[number];
 export type UploadsConfigValues = Partial<Record<UploadsConfigKey, string>>;
 export interface PutDefaults {
@@ -12,6 +12,8 @@ export interface PutDefaults {
     noOptimize?: boolean;
     /** When true, optimize keeps EXIF/XMP/ICC (default strips). */
     keepExif?: boolean;
+    /** When true, `put` does NOT auto-resolve/stamp gh.* on the default path. */
+    noAutoMeta?: boolean;
 }
 declare const PUT_DEFAULT_KEY_MAP: Record<keyof PutDefaults, UploadsConfigKey>;
 export declare function putDefaultsToConfigValues(defaults: PutDefaults): UploadsConfigValues;

package/dist/config-file.js

@@ -12,6 +12,7 @@ export const UPLOADS_CONFIG_KEYS = [
     "UPLOADS_NO_GIT",
     "UPLOADS_NO_OPTIMIZE",
     "UPLOADS_KEEP_EXIF",
+    "UPLOADS_NO_AUTO_META",
 ];
 const PUT_DEFAULT_KEY_MAP = {
     prefix: "UPLOADS_DEFAULT_PREFIX",
@@ -21,6 +22,7 @@ const PUT_DEFAULT_KEY_MAP = {
     noGit: "UPLOADS_NO_GIT",
     noOptimize: "UPLOADS_NO_OPTIMIZE",
     keepExif: "UPLOADS_KEEP_EXIF",
+    noAutoMeta: "UPLOADS_NO_AUTO_META",
 };
 function isTruthyConfigFlag(value) {
     if (!value)
@@ -44,6 +46,8 @@ export function putDefaultsToConfigValues(defaults) {
         out.UPLOADS_NO_OPTIMIZE = "1";
     if (defaults.keepExif)
         out.UPLOADS_KEEP_EXIF = "1";
+    if (defaults.noAutoMeta)
+        out.UPLOADS_NO_AUTO_META = "1";
     return out;
 }
 function parsePutDefaultsFromRaw(raw) {
@@ -65,6 +69,8 @@ function parsePutDefaultsFromRaw(raw) {
         out.noOptimize = true;
     if (isTruthyConfigFlag(raw.UPLOADS_KEEP_EXIF))
         out.keepExif = true;
+    if (isTruthyConfigFlag(raw.UPLOADS_NO_AUTO_META))
+        out.noAutoMeta = true;
     return out;
 }
 function parsePutDefaultsFromEnv() {
@@ -83,6 +89,8 @@ function parsePutDefaultsFromEnv() {
         raw.UPLOADS_NO_OPTIMIZE = process.env.UPLOADS_NO_OPTIMIZE;
     if (process.env.UPLOADS_KEEP_EXIF)
         raw.UPLOADS_KEEP_EXIF = process.env.UPLOADS_KEEP_EXIF;
+    if (process.env.UPLOADS_NO_AUTO_META)
+        raw.UPLOADS_NO_AUTO_META = process.env.UPLOADS_NO_AUTO_META;
     return parsePutDefaultsFromRaw(raw);
 }
 /** XDG default shared across buildinternet skills (github-screenshots, uploads, …). */
@@ -152,6 +160,8 @@ export function mergePutDefaults(...layers) {
             out.noOptimize = layer.noOptimize;
         if (layer.keepExif != null)
             out.keepExif = layer.keepExif;
+        if (layer.noAutoMeta != null)
+            out.noAutoMeta = layer.noAutoMeta;
     }
     return out;
 }

package/dist/github-gh.d.ts

@@ -9,6 +9,13 @@ export declare const execRunner: CommandRunner;
 export declare function resolveRepo(explicit: string | undefined, run?: CommandRunner): string;
 /** Resolve the pull request associated with the current branch. */
 export declare function resolveCurrentPullRequest(repo: string, run?: CommandRunner): GhTarget;
+/**
+ * Classify a bare PR/issue number via the GitHub API so the default `put`
+ * path can stamp the right `gh.kind`. Returns undefined on any failure (gh
+ * missing, 404, network) — the caller treats that as "no gh context" and
+ * uploads without metadata.
+ */
+export declare function classifyGhNumber(repo: string, num: number, run?: CommandRunner): GhTarget | undefined;
 /**
  * Create the managed attachments comment, or edit it in place if it already
  * exists. Never touches any other comment. Body is passed via stdin

package/dist/github-gh.js

@@ -61,6 +61,30 @@ export function resolveCurrentPullRequest(repo, run = execRunner) {
     }
     throw new UsageError("could not infer a pull request for the current branch — pass --pr <num> or --issue <num>");
 }
+/**
+ * Classify a bare PR/issue number via the GitHub API so the default `put`
+ * path can stamp the right `gh.kind`. Returns undefined on any failure (gh
+ * missing, 404, network) — the caller treats that as "no gh context" and
+ * uploads without metadata.
+ */
+export function classifyGhNumber(repo, num, run = execRunner) {
+    try {
+        const out = run("gh", [
+            "api",
+            `repos/${repo}/issues/${num}`,
+            "--jq",
+            'if .pull_request then "pull" else "issue" end',
+        ]).trim();
+        if (out === "pull")
+            return { repo, kind: "pull", num };
+        if (out === "issue")
+            return { repo, kind: "issues", num };
+    }
+    catch {
+        // gh missing / not found / network — caller skips
+    }
+    return undefined;
+}
 /**
  * PR comments live on the issues endpoint, so one path covers PRs and issues.
  * Only the first 100 comments are searched (accepted v1 limitation).

package/package.json

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