@buildinternet/uploads 0.7.0 → 0.9.0

package/dist/commands.js

@@ -1,18 +1,32 @@
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { createUploadsClient } from "./client.js";
-import { parseCommandArgs, flagString, flagBool, flagInt, UsageError, } from "./cli-args.js";
+import { parseCommandArgs, flagString, flagBool, flagInt, flagValues, UsageError, } from "./cli-args.js";
 import { resolvePutDefaults, workspaceMismatch, workspaceFromToken, } from "./config.js";
 import { buildMarkdown } from "./embed.js";
+import { urlForGithubEmbed } from "./public-urls.js";
 import { UploadsError } from "./errors.js";
 import { writeJson, writeStdout } from "./io.js";
-import { ghAttachmentKey, ghKeyPrefix, attachmentsCommentBody, normalizeGithubCoordinate, } from "./github.js";
-import { resolveRepo, resolveCurrentPullRequest, execRunner, upsertAttachmentsComment, } from "./github-gh.js";
+import { parseMetaFlags, validateMetaMap } from "./metadata.js";
+import { ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, attachmentsCommentBody, normalizeGithubCoordinate, } from "./github.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";
 import { buildCliProvenance } from "./provenance.js";
 import { packageVersion } from "./package-version.js";
+/** Read a local file (or `-` for stdin). Missing path → FILE_NOT_FOUND (exit 2). */
+export function readFileArg(fileArg) {
+    try {
+        return new Uint8Array(readFileSync(fileArg === "-" ? 0 : fileArg));
+    }
+    catch (err) {
+        if (err?.code === "ENOENT") {
+            throw new UploadsError(`file not found: ${fileArg}`, "FILE_NOT_FOUND");
+        }
+        throw err;
+    }
+}
 // --- put ---
 const PUT_HELP = `uploads put <file> [options]
 
@@ -30,8 +44,12 @@ Uploads are public. --pr/--issue keys include the repo, number, and filename and
 remain public even for private/internal GitHub repositories. Upload only media
 that is safe at a predictable public URL.
 
+Human/json output includes durable url and (when dual-host applies) embedUrl.
+MARKDOWN prefers embedUrl for GitHub. Override: UPLOADS_EMBED_PUBLIC_BASE_URL.
+
 Options:
   --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>)
+  --name <leaf>         Clean key leaf + default alt (no '/'); keeps --pr/default path. Not with --key
   --destination <id>    Typed root: screenshots | gh | f (sets --prefix)
   --prefix <path>       Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX)
   --repo <owner/repo>   Repo segment (default: git remote, or UPLOADS_DEFAULT_REPO)
@@ -47,19 +65,32 @@ 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)
   --issue <num>         Attach to an issue: key gh/<owner>/<repo>/issues/<num>/<name>
   --comment             With --pr/--issue: update one managed comment with attachments and linked galleries via local gh auth
   --gallery <id>         Add the uploaded object to this public gallery
+  --meta <k=v>          Queryable custom metadata (repeatable; value may contain "="): key ^[a-z][a-z0-9._-]{0,63}$, value 1-512 printable ASCII, max 24 pairs
+                        Re-uploading to an existing key WITH --meta replaces that file's
+                        entire metadata set; without --meta the existing metadata is
+                        preserved. Use "uploads meta set" to edit individual keys.
+  --dry-run             Print key + public URL without uploading. Not with --comment/--gallery
+
+Exit codes: 0 ok · 2 usage/token/file · 3 auth/policy · 4 network · 1 other.
+Scripted formats (json|url|markdown) also print failures on stdout.
 
 Examples:
   uploads put ./shot.png --repo myorg/myapp --ref 1722 --alt "New cards" --width 700
   uploads put ./mobile.png --frame phone
   uploads put ./ui.png --frame browser --frame-url "https://app.example/settings"
   uploads put ./shot.png --destination screenshots
+  uploads put ./capture-….webp --pr 128 --name hero.webp
+  uploads put ./shot.png --pr 128 --name hero.webp --dry-run --format url
   uploads put ./after.png --gallery gal_example
+  uploads put ./shot.png --meta app=myapp --meta page=settings
 `;
 /**
  * Turns a pr/issue pair (+ optional repo) into a GhTarget; undefined when
@@ -78,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") {
@@ -160,7 +209,7 @@ function frameOptionsFromFlags(flags) {
  * fatal (`comment` command) or a warning (`put --comment`).
  */
 export async function syncAttachmentsComment(client, target, run) {
-    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url }) => ({ key, url }));
+    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url, embedUrl }) => ({ key, url, embedUrl }));
     const galleries = [];
     let cursor;
     do {
@@ -183,6 +232,7 @@ export async function syncAttachmentsComment(client, target, run) {
                     .slice(0, 3)
                     .map((item) => ({
                     url: item.url,
+                    embedUrl: item.embedUrl,
                     alt: item.altText ?? item.objectKey,
                     itemUrl: item.pageUrl,
                 })),
@@ -226,12 +276,19 @@ Options:
   --optimize-quality <1-100>  WebP quality (default: 85)
   --keep-exif           Keep EXIF/XMP/ICC when optimizing (default: strip for privacy)
   --workspace, -w <name>  Override workspace
+  --meta <k=v>          Extra queryable metadata (repeatable; value may contain "=").
+                        gh.repo/gh.kind/gh.number/gh.ref are always set from the resolved
+                        target — a --meta pair with the same key is overridden by it.
+                        Because attach always sends its own gh.* pairs, re-attaching to
+                        the same key always replaces that file's entire metadata set
+                        (never preserves) — use "uploads meta set" to add to it instead.
 
 Examples:
   uploads attach ./before.png ./after.png
   uploads attach ./mobile.png --frame phone
   uploads attach ./shot.png --pr 123 --repo myorg/myapp
   uploads attach ./artifact.zip --issue 45 --no-comment
+  uploads attach ./shot.png --meta app=myapp --meta page=settings
 `;
 export async function runAttach(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
@@ -253,6 +310,15 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
     const frameOpts = frameOptionsFromFlags(parsed.flags);
     const contentTypeOverride = flagString(parsed.flags, "--content-type");
+    // User-supplied extras first, then the resolved target's gh.* — explicit
+    // target pairs always win over a same-named --meta extra (documented above).
+    // Validate the merged map (not just the extras) so the 24-key/8KB caps are
+    // enforced client-side even when extras alone are under the cap but extras
+    // + the 4 gh.* pairs push the merged map over it.
+    const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
+    const metadata = { ...metaExtras, ...ghMetadataFromTarget(target) };
+    if (Object.keys(metadata).length > 0)
+        validateMetaMap(metadata);
     const results = [];
     for (const file of parsed.positionals) {
         if (file === "-")
@@ -260,7 +326,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         const sourceName = basename(file);
         if (!ctx.quiet && !ctx.json)
             process.stderr.write(`>> uploading ${file}\n`);
-        const prepared = await prepareImageForUpload(new Uint8Array(readFileSync(file)), sourceName, {
+        const prepared = await prepareImageForUpload(readFileArg(file), sourceName, {
             ...frameOpts,
             optimize: optimizeOpts,
         });
@@ -280,10 +346,12 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
                 frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
                 keepExif: optimizeOpts.keepExif === true,
             }),
+            metadata,
         });
+        const embedSrc = urlForGithubEmbed(result.url, result.embedUrl);
         results.push({
             ...result,
-            markdown: buildMarkdown(result.url, { alt: sourceName }),
+            markdown: buildMarkdown(embedSrc, { alt: sourceName }),
             optimize: {
                 optimized: prepared.optimized,
                 skippedReason: prepared.skippedReason,
@@ -310,10 +378,16 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     }
     else {
         for (const result of results) {
-            await writeStdout(`URL: ${result.url}\nMARKDOWN: ${result.markdown}\n`);
+            const embedLine = result.embedUrl ? `EMBED: ${result.embedUrl}\n` : "";
+            await writeStdout(`URL: ${result.url}\n${embedLine}MARKDOWN: ${result.markdown}\n`);
         }
         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;
 }
@@ -338,20 +412,47 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const ghTarget = ghTargetFromFlags(parsed.flags, run);
     const wantComment = parsed.flags.has("--comment");
     const galleryId = flagString(parsed.flags, "--gallery");
+    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 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) {
-        if (keyHint)
-            throw new UsageError("--key cannot be combined with --pr/--issue");
+        if (keyHint) {
+            throw new UsageError("--key cannot be combined with --pr/--issue; use --name <leaf> to set a clean filename on the stable path");
+        }
         if (flagString(parsed.flags, "--ref")) {
             throw new UsageError("--ref cannot be combined with --pr/--issue");
         }
         if (prefixFlag)
             throw new UsageError("--prefix cannot be combined with --pr/--issue");
     }
+    if (nameFlag !== undefined) {
+        if (nameFlag === "" || nameFlag.includes("/")) {
+            throw new UsageError("--name must be a bare filename with no '/'");
+        }
+        if (keyHint)
+            throw new UsageError("--name cannot be combined with --key");
+    }
+    if (dryRun) {
+        if (wantComment)
+            throw new UsageError("--dry-run cannot be combined with --comment");
+        if (galleryId)
+            throw new UsageError("--dry-run cannot be combined with --gallery");
+    }
     let resolvedPrefix;
     try {
         resolvedPrefix = resolvePutPrefix({
@@ -364,8 +465,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     catch (err) {
         throw new UsageError(err instanceof Error ? err.message : String(err));
     }
-    const bytes = fileArg === "-" ? new Uint8Array(readFileSync(0)) : new Uint8Array(readFileSync(fileArg));
-    const sourceName = fileArg === "-" ? (keyHint ? basename(keyHint) : "stdin.bin") : basename(fileArg);
+    const bytes = readFileArg(fileArg);
+    const sourceName = nameFlag ?? (fileArg === "-" ? (keyHint ? basename(keyHint) : "stdin.bin") : basename(fileArg));
     const format = ctx.json
         ? "json"
         : (() => {
@@ -379,6 +480,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const defaults = resolvePutDefaults({ envFile: ctx.envFile });
     const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
     const frameOpts = frameOptionsFromFlags(parsed.flags);
+    // Optimize even on --dry-run so the preview key extension/hash match a real put.
     const prepared = await prepareImageForUpload(bytes, sourceName, {
         ...frameOpts,
         optimize: optimizeOpts,
@@ -395,7 +497,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             })()
             : defaults.width;
     if (!ctx.quiet && format === "human") {
-        process.stderr.write(`>> uploading ${fileArg === "-" ? "stdin" : fileArg}\n`);
+        process.stderr.write(`>> ${dryRun ? "dry run" : "uploading"} ${fileArg === "-" ? "stdin" : fileArg}\n`);
         if (prepared.frame?.framed)
             process.stderr.write(`>> framed with ${prepared.frame.frameId}\n`);
         const note = formatOptimizeNote(prepared);
@@ -403,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);
@@ -414,14 +553,17 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
         contentType: prepared.optimized ? prepared.contentType : contentTypeOverride,
         deriveRepoFromGit: !noGit,
+        dryRun,
         provenance: buildCliProvenance({
             sourceName,
             optimized: prepared.optimized,
             frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
             keepExif: optimizeOpts.keepExif === true,
         }),
+        metadata,
     });
-    const markdown = buildMarkdown(result.url, { alt, width });
+    const embedSrc = urlForGithubEmbed(result.url, result.embedUrl);
+    const markdown = buildMarkdown(embedSrc, { alt, width });
     let gallery;
     if (galleryId) {
         try {
@@ -446,7 +588,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         filename: prepared.filename,
     };
     if (!ctx.quiet && format === "human") {
-        process.stderr.write(`>> key: ${result.key}\n\n`);
+        process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n\n`);
     }
     switch (format) {
         case "json":
@@ -456,6 +598,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 optimize: optimizeMeta,
                 frame: prepared.frame,
                 gallery,
+                ...(dryRun ? { dryRun: true } : {}),
             });
             break;
         case "url":
@@ -464,8 +607,10 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         case "markdown":
             await writeStdout(`${markdown}\n`);
             break;
-        default:
-            await writeStdout(`URL: ${result.url}\nMARKDOWN: ${markdown}${gallery?.url ? `\nGALLERY: ${gallery.url}` : ""}\n`);
+        default: {
+            const embedLine = result.embedUrl ? `EMBED: ${result.embedUrl}\n` : "";
+            await writeStdout(`URL: ${result.url}\n${embedLine}MARKDOWN: ${markdown}${gallery?.url ? `\nGALLERY: ${gallery.url}` : ""}\n`);
+        }
     }
     if (gallery?.url && format !== "human") {
         process.stderr.write(`gallery: ${gallery.url}\n`);
@@ -703,21 +848,58 @@ export async function runGallery(ctx, args, help = false) {
     }
 }
 // --- list ---
-const LIST_HELP = `uploads list [--prefix <p>] [--pr <num> | --issue <num>] [--repo <owner/name>] [--limit <n>] [--cursor <c>] [--all] [--workspace <name>]
+const LIST_HELP = `uploads list [--prefix <p>] [--pr <num> | --issue <num>] [--repo <owner/name>] [--limit <n>] [--cursor <c>] [--all] [--meta <k=v>]... [--workspace <name>]
 
 Default prefix: UPLOADS_DEFAULT_PREFIX (screenshots if unset).
 
+--meta <k=v> (repeatable, ANDed) switches to the metadata filter endpoint —
+returned items include their matched metadata. Combines with --prefix, not
+with --pr/--issue/--all. See also: uploads find (positional-pair alias).
+
 Examples:
   uploads list --prefix screenshots/
   uploads list --pr 123
   uploads list --all --json
+  uploads list --meta gh.repo=buildinternet/uploads --meta gh.number=123
 `;
+/** `--meta k=v` (repeatable) filter path, shared by `runList` and `runFind`. */
+async function runFindFiles(ctx, filters, flags) {
+    if (flagString(flags, "--cursor") !== undefined) {
+        throw new UsageError("--cursor is not supported with metadata filters");
+    }
+    const prefix = flagString(flags, "--prefix");
+    const limit = flagInt(flags, "--limit", "--limit");
+    const result = await ctx.client.findFiles(filters, { prefix, limit });
+    if (ctx.json)
+        await writeJson(result);
+    else
+        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) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
         process.stderr.write(LIST_HELP);
         return 0;
     }
+    const metaPairs = flagValues(parsed.flags, "--meta");
+    if (metaPairs.length > 0) {
+        if (ghTargetFromFlags(parsed.flags, run)) {
+            throw new UsageError("--meta cannot be combined with --pr/--issue");
+        }
+        if (flagBool(parsed.flags, "--all")) {
+            throw new UsageError("--meta cannot be combined with --all");
+        }
+        return runFindFiles(ctx, parseMetaFlags(metaPairs), parsed.flags);
+    }
     const defaults = resolvePutDefaults({ envFile: ctx.envFile });
     const prefixFlag = flagString(parsed.flags, "--prefix");
     let prefix = prefixFlag ?? (defaults.prefix ? `${defaults.prefix}/` : undefined);
@@ -750,6 +932,94 @@ export async function runList(ctx, args, help = false, run = execRunner) {
     }
     return 0;
 }
+// --- find ---
+const FIND_HELP = `uploads find k=v [k=v...] [--prefix <p>] [--limit <n>] [--workspace <name>]
+
+Human-friendly alias for \`uploads list --meta k=v...\` — same metadata filter
+(ANDed equality), same output; pairs are positional instead of repeated flags.
+
+Examples:
+  uploads find gh.repo=buildinternet/uploads gh.number=123
+  uploads find app=myapp page=settings --prefix screenshots/
+`;
+export async function runFind(ctx, args, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        process.stderr.write(FIND_HELP);
+        return 0;
+    }
+    if (parsed.positionals.length === 0) {
+        process.stderr.write(FIND_HELP);
+        return 2;
+    }
+    const filters = parseMetaFlags(parsed.positionals);
+    return runFindFiles(ctx, filters, parsed.flags);
+}
+// --- meta ---
+const META_HELP = `uploads meta <command> [args]
+
+Read/write an object's queryable custom metadata (D1-backed key-value pairs;
+distinct from the R2 provenance headers put on upload).
+
+Commands:
+  get <key>                            Show metadata for an object
+  set <key> k=v [k=v...] [--delete k]...   Merge-set and/or delete pairs
+
+Examples:
+  uploads meta get screenshots/myapp/42/shot.png
+  uploads meta set screenshots/myapp/42/shot.png app=myapp page=settings
+  uploads meta set screenshots/myapp/42/shot.png --delete app --delete page
+`;
+export async function runMeta(ctx, args, help = false) {
+    const parsed = parseCommandArgs(args);
+    const action = parsed.positionals[0];
+    if (help || parsed.help || !action) {
+        process.stderr.write(META_HELP);
+        return help || parsed.help ? 0 : 2;
+    }
+    switch (action) {
+        case "get": {
+            const key = parsed.positionals[1];
+            if (!key)
+                throw new UsageError("meta get requires an object key");
+            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`);
+            return 0;
+        }
+        case "set": {
+            const key = parsed.positionals[1];
+            if (!key)
+                throw new UsageError("meta set requires an object key");
+            const pairs = parsed.positionals.slice(2);
+            const del = flagValues(parsed.flags, "--delete");
+            if (pairs.length === 0 && del.length === 0) {
+                throw new UsageError("meta set requires k=v pairs and/or --delete <key>");
+            }
+            const set = pairs.length > 0 ? parseMetaFlags(pairs) : undefined;
+            const result = await ctx.client.patchMetadata(key, {
+                set,
+                delete: del.length > 0 ? del : undefined,
+            });
+            if (ctx.json)
+                await writeJson(result);
+            else
+                for (const [k, v] of Object.entries(result.metadata))
+                    await writeStdout(`${k}=${v}\n`);
+            return 0;
+        }
+        default:
+            throw new UsageError(`unknown meta command: ${action}`);
+    }
+}
 // --- delete ---
 const DELETE_HELP = `uploads delete <key> [--dry-run] [--workspace <name>]
 

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/config.js

@@ -140,11 +140,14 @@ export function resolveConfig(flags) {
 }
 function missingTokenMessage(configPath) {
     return [
-        "UPLOADS_TOKEN is required.",
-        "  uploads login                         # exchange an admin-provided enrollment code",
+        "You're not signed in yet — one quick step and you're set:",
+        "",
+        "  uploads login                         # open a browser and authorize this device",
+        "",
+        "Already have a token?",
         `  uploads setup --token <token>         # guided setup → ${configPath}`,
         `  uploads config init --token <token>   # writes ${configPath}`,
-        "  or set UPLOADS_TOKEN in env, pass --token, or use --env-file",
+        "  or set UPLOADS_TOKEN / pass --token / use --env-file",
     ].join("\n");
 }
 /** Warn when an explicit workspace override may not match the token's embedded workspace. */

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "API_ERROR" | "NETWORK" | "USAGE";
+export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "FILE_NOT_FOUND" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "API_ERROR" | "NETWORK" | "USAGE";
 export declare class UploadsError extends Error {
     readonly code: UploadsErrorCode;
     readonly status?: number;

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).