@buildinternet/uploads 0.26.0 → 0.27.0

package/dist/commands.js

@@ -11,7 +11,8 @@ import { writeJson, writeStdout } from "./io.js";
 import { imageFactsFromBytes } from "./image-facts.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
-import { ghAttachmentKey, ghBranchAttachmentKey, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, normalizeGithubCoordinate, } from "./github.js";
+import { mergeSidecarMeta } from "./sidecar.js";
+import { ghAttachmentKey, ghBranchAttachmentKey, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, parseGhKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, normalizeGithubCoordinate, } from "./github.js";
 import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
 import { deriveRepoFromGit } from "./keys.js";
 import { resolvePutPrefix } from "./destinations.js";
@@ -56,6 +57,12 @@ upload as-is, or --keep-exif when image metadata matters for the discussion.
 Optional --frame wraps the image in a device/browser chrome before optimize
 (default off). See: uploads put --help frames
 
+If the file has a sidecar manifest (<file>.uploads.json, written by
+"screenshot --out") and its content hash still matches this file, that
+capture's derived metadata (path/url/env/viewport/state) is merged in
+automatically — explicit --meta/--state always win. A regenerated or edited
+file loses its sidecar silently (hash no longer matches).
+
 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.
@@ -558,6 +565,12 @@ URL and every embed hot-swap. Human mode prints ">> replaced existing object
 Still images are optimized to WebP by default (same as put). Use --no-optimize
 to upload originals. Optional --frame wraps images in device/browser chrome.
 
+If a file has a sidecar manifest (<file>.uploads.json, written by
+"screenshot --out") and its content hash still matches, that capture's
+derived metadata (path/url/env/viewport/state) is merged in automatically —
+explicit --meta/--state always win. A regenerated or edited file loses its
+sidecar silently (hash no longer matches).
+
 Branch staging (pre-PR): --branch [name] stages files against a git branch
 before a pull request exists, e.g. for a coding agent working a branch that
 hasn't opened a PR yet. Key: gh/<owner>/<repo>/branch/<branch>/<filename>
@@ -620,6 +633,21 @@ Examples:
   uploads attach ./shot.png --branch feature/new-settings
   uploads attach --promote
 `;
+/**
+ * Lever 3 (issue #469): a nudge for when an image lands on a PR/issue with
+ * no `path` metadata — `path` is one of the highest-value queryable tags
+ * (same tier as `state=`), and unlike `uploads screenshot` (which derives it
+ * from the captured URL), a plain `attach`/`put --pr`/`put --issue` of an
+ * already-existing image has nothing to derive it from, so it's easy to
+ * forget. Fires once per batch (not per file) — checks the metadata the
+ * server actually stored (`PutResult.metadata`), not what was requested, so
+ * a merge/validation drop still surfaces the gap. Non-image uploads (zips,
+ * PDFs, etc.) are exempt — "findable by page" doesn't apply to them.
+ */
+export function pathMetaHintFor(uploads) {
+    const missingPath = uploads.some((u) => u.contentType.startsWith("image/") && !u.metadata?.path);
+    return missingPath ? "tip: add --meta path=/route so this shot is findable by page" : undefined;
+}
 /**
  * Shared prepare + put loop for both PR/issue attach (`uploadAttachments`)
  * and branch-staged attach (`uploadBranchAttachments`) — bounded concurrency,
@@ -634,11 +662,14 @@ async function uploadAttachmentBatch(opts) {
         try {
             const sourceName = basename(file);
             const bytes = readFileArg(file);
+            // Sidecar manifest from a prior `screenshot --out` of this exact file
+            // (issue #469 lever 2) — see mergeSidecarMeta.
+            const baseMetadata = mergeSidecarMeta(file, bytes, opts.metadata);
             // Same EXIF promotion uploadPreparedImage does; attach keeps its own
             // per-file tail (it builds keys differently), so it opts in here too.
             const metadata = opts.deriveImageFacts
-                ? await mergeImageFacts(bytes, opts.metadata)
-                : opts.metadata;
+                ? await mergeImageFacts(bytes, baseMetadata)
+                : baseMetadata;
             const prepared = await prepareImageForUpload(bytes, sourceName, {
                 ...opts.frame,
                 optimize: opts.optimize,
@@ -743,7 +774,11 @@ export async function uploadPuts(opts) {
                         ? basename(opts.explicitKey)
                         : "stdin.bin"
                     : basename(file));
-            const { result, prepared, markdown } = await uploadPreparedImage(opts.client, readFileArg(file), sourceName, {
+            const bytes = readFileArg(file);
+            // Sidecar manifest from a prior `screenshot --out` of this exact file
+            // (issue #469 lever 2) — see mergeSidecarMeta. Not applicable to stdin.
+            const metadata = file !== "-" ? mergeSidecarMeta(file, bytes, opts.metadata) : opts.metadata;
+            const { result, prepared, markdown } = await uploadPreparedImage(opts.client, bytes, sourceName, {
                 frame: opts.frame,
                 optimize: opts.optimize,
                 ghTarget: opts.ghTarget,
@@ -756,7 +791,7 @@ export async function uploadPuts(opts) {
                 contentType: opts.contentType,
                 dryRun: opts.dryRun,
                 replace: opts.replace,
-                metadata: opts.metadata,
+                metadata,
                 deriveImageFacts: opts.deriveImageFacts,
                 provenanceClient: opts.provenanceClient,
                 alt: () => opts.alt ?? basename(sourceName),
@@ -935,6 +970,8 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
             process.stderr.write(`warning: uploads succeeded but the GitHub comment failed (is gh installed and authenticated?): ${commentError}\n`);
         }
     }
+    // Lever 3 (issue #469): tip when an image lands here with no `path` meta.
+    const pathHint = uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads) : undefined;
     if (ctx.json) {
         await writeJson({
             target,
@@ -943,6 +980,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
             comment,
             commentError,
             promotion: promotion ?? null,
+            ...(pathHint ? { hint: pathHint } : {}),
         });
     }
     else {
@@ -971,6 +1009,8 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
             const ref = ghMetadataFromTarget(target)["gh.ref"];
             process.stderr.write(`>> find these later: uploads find gh.ref=${ref}\n`);
         }
+        if (pathHint)
+            process.stderr.write(`${pathHint}\n`);
     }
     return failures.length === 0 ? 0 : 1;
 }
@@ -1269,6 +1309,18 @@ export function resolvePutStagingTarget(opts) {
         return undefined; // gh/git unavailable, or repo unresolvable — dated layout
     }
 }
+/**
+ * Merges a staging target's `gh.*` branch metadata over `base` and validates
+ * the result (same builder, same contract as `attach --branch`) — the one
+ * merge+validate step shared by every staging call site: `runPut`,
+ * `runScreenshot`, and both the local stdio MCP `put` and `screenshot`
+ * tools.
+ */
+export function mergeStagingMeta(base, target) {
+    const merged = { ...base, ...ghMetadataForBranch(target.repo, target.branch) };
+    validateMetaMap(merged);
+    return merged;
+}
 /**
  * The bare-put staging note's wording (issue #403): replaces the #393 nudge
  * for the (now default) case where a bare put on a non-default branch stages
@@ -1553,12 +1605,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         attachedRef = merged["gh.ref"];
     }
     else if (stagingTarget) {
-        const merged = {
-            ...userMeta,
-            ...ghMetadataForBranch(stagingTarget.repo, stagingTarget.branch),
-        };
-        validateMetaMap(merged); // matches attach --branch's unwrapped call — same builder, same contract
-        metadata = merged;
+        metadata = mergeStagingMeta(userMeta, stagingTarget);
     }
     else {
         // gh.* additionally needs git, which the shared derived gate ignores.
@@ -1648,13 +1695,19 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const bindingWarning = stagingTarget && uploads.length > 0
         ? await resolveStageBindingWarning({ ctx, defaults, repo: stagingTarget.repo })
         : undefined;
+    // Lever 3 (issue #469): tip when a --pr/--issue put lands an image with no
+    // `path` meta. Only relevant on the ghTarget path — the bare-put paths
+    // above (staging/auto/dated) aren't attached to a PR/issue yet, so there's
+    // nothing to look up from a page later.
+    const pathHint = ghTarget && uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads) : undefined;
     // One JSON `hint` slot, shared with the #393 nudge (mutually exclusive with
     // it — nudge is undefined whenever staging took over). When staging fires,
     // prefer the more actionable binding warning over the generic staging note
     // (mirrors attach --branch, whose only JSON hint content IS the binding
     // warning); stderr prints the nudge/staging-note and binding-warning lines
-    // independently, below.
-    const jsonHint = nudge ?? bindingWarning ?? stagingNote;
+    // independently, below. pathHint only ever fires on the ghTarget path, so
+    // it never competes with the other three.
+    const jsonHint = nudge ?? bindingWarning ?? stagingNote ?? pathHint;
     const galleriesByKey = new Map();
     let galleryHadError = false;
     if (galleryId && uploads.length > 0) {
@@ -1737,6 +1790,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 process.stderr.write(`${stagingNote}\n`);
             if (bindingWarning)
                 process.stderr.write(`${bindingWarning}\n`);
+            if (pathHint)
+                process.stderr.write(`${pathHint}\n`);
         }
         return failures.length === 0 && !galleryHadError ? 0 : 1;
     }
@@ -1794,6 +1849,8 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         process.stderr.write(`${stagingNote}\n`);
     if (bindingWarning && format !== "json")
         process.stderr.write(`${bindingWarning}\n`);
+    if (pathHint && format !== "json")
+        process.stderr.write(`${pathHint}\n`);
     return gallery?.error ? 1 : 0;
 }
 // --- galleries ---
@@ -2173,12 +2230,50 @@ export async function runMeta(ctx, args, help = false) {
             else
                 for (const [k, v] of Object.entries(result.metadata))
                     await writeStdout(`${k}=${v}\n`);
+            await resyncCommentAfterMetaSet(ctx, key, [...Object.keys(set ?? {}), ...del]);
             return 0;
         }
         default:
             throw new UsageError(`unknown meta command: ${action}`);
     }
 }
+/** The metadata keys the managed comment renders (path/state, PR #370). */
+const COMMENT_RENDERED_META_KEYS = ["path", "state"];
+/**
+ * Best-effort managed-comment refresh after `meta set` touches a
+ * display-relevant key on a PR/issue-keyed object (issue #470) — without
+ * this, backfilled `path=`/`state=` never reaches the rendered comment until
+ * an unrelated attach fires. Bot endpoint only (no gh fallback — this is a
+ * metadata tweak, not an explicit comment command); any failure degrades to
+ * a stderr hint instead of failing the metadata write that already landed.
+ */
+async function resyncCommentAfterMetaSet(ctx, key, touchedKeys) {
+    if (!touchedKeys.some((k) => COMMENT_RENDERED_META_KEYS.includes(k)))
+        return;
+    const target = parseGhKey(key);
+    if (!target)
+        return;
+    try {
+        const bot = await ctx.client.upsertGithubComment({
+            repo: target.repo,
+            num: target.num,
+            kind: target.kind,
+        });
+        if (bot.posted) {
+            if (!ctx.quiet && !ctx.json) {
+                process.stderr.write(`refreshed the managed comment on ${target.repo}#${target.num}\n`);
+            }
+            return;
+        }
+    }
+    catch {
+        // Fall through to the hint.
+    }
+    if (!ctx.quiet && !ctx.json) {
+        const flag = target.kind === "pull" ? "--pr" : "--issue";
+        process.stderr.write(`tip: run \`uploads comment ${flag} ${target.num}\` to refresh the PR comment\n`);
+    }
+}
 // --- delete ---
 const DELETE_HELP = `uploads delete <key> [--dry-run] [--workspace <name>]
 
@@ -2424,9 +2519,10 @@ const USAGE_HELP = `uploads usage [--workspace <name>]
 Show workspace storage and monthly upload counters.
 
 When the API reports workspace quotas (typical on uploads.sh cloud /
-self-serve plans), human output includes progress bars toward those caps.
-Self-hosted or unlimited operator workspaces get usage totals only, plus a
-short unmetered note — no invented limits.
+self-serve Free and Pro), human output includes the plan name and progress
+bars toward those caps. Free is not unlimited — storage and monthly upload
+limits show on the meters. Self-hosted or unlimited operator workspaces get
+usage totals only, plus a short unmetered note — no invented limits.
 
 Examples:
   uploads --env-file .env usage

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", "UPLOADS_NO_AUTO_META", "UPLOADS_SCREENSHOT_VIA", "UPLOADS_NO_NUDGE"];
+export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_SESSION_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", "UPLOADS_SCREENSHOT_VIA", "UPLOADS_NO_NUDGE"];
 export type UploadsConfigKey = (typeof UPLOADS_CONFIG_KEYS)[number];
 export type UploadsConfigValues = Partial<Record<UploadsConfigKey, string>>;
 export interface PutDefaults {

package/dist/config-file.js

@@ -5,6 +5,8 @@ export const UPLOADS_CONFIG_KEYS = [
     "UPLOADS_API_URL",
     "UPLOADS_WORKSPACE",
     "UPLOADS_TOKEN",
+    /** Better Auth device-flow session bearer — keeps session.cliVersion fresh. */
+    "UPLOADS_SESSION_TOKEN",
     "UPLOADS_DEFAULT_PREFIX",
     "UPLOADS_DEFAULT_REPO",
     "UPLOADS_DEFAULT_REF",

package/dist/config.d.ts

@@ -4,6 +4,8 @@ export interface UploadsClientConfig {
     workspace: string;
     token: string;
 }
+/** Derive auth origin from an API base (`api.` → `auth.`), else production default. */
+export declare function authUrlFromApi(apiUrl: string): string;
 export declare const DEFAULT_API_URL = "https://api.uploads.sh";
 export declare const DEFAULT_WORKSPACE = "default";
 /** Workspace encoded in minted tokens: `up_<workspace>_…` */

package/dist/config.js

@@ -2,6 +2,20 @@ import { existsSync, readFileSync } from "node:fs";
 import { loadConfigFile, resolveConfigPath } from "./config-file.js";
 import { UploadsError } from "./errors.js";
 export { defaultConfigPath, resolveConfigPath, loadConfigFile, redactToken, writeConfigKeys, removeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, resolveScreenshotDefaults, UPLOADS_CONFIG_KEYS, } from "./config-file.js";
+/** Derive auth origin from an API base (`api.` → `auth.`), else production default. */
+export function authUrlFromApi(apiUrl) {
+    try {
+        const url = new URL(apiUrl);
+        if (url.hostname.startsWith("api.")) {
+            url.hostname = `auth.${url.hostname.slice(4)}`;
+            return url.origin;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "https://auth.uploads.sh";
+}
 export const DEFAULT_API_URL = "https://api.uploads.sh";
 export const DEFAULT_WORKSPACE = "default";
 const TOKEN_WORKSPACE_RE = /^up_([a-z0-9][a-z0-9-]{1,62})_/;

package/dist/format-bytes.d.ts

@@ -1,5 +1,9 @@
 /**
- * Human-readable size for CLI notes (1024-based).
- * files-sdk has no size formatter — only raw `size` on head/upload results.
+ * Decimal (SI) human sizes for CLI output. Plan catalog caps are round decimal
+ * numbers (250 MB free, 10 GB pro); binary units made Free look like 238.4 MB.
+ * Used for usage meters, list sizes, optimize notes, and doctor — same base
+ * as apps/web `formatBytes` / `formatMarketedBytes`.
  */
 export declare function formatByteSize(bytes: number): string;
+/** Alias for call sites that want plan-cap wording; same SI formatter. */
+export declare function formatMarketedBytes(bytes: number): string;

package/dist/format-bytes.js

@@ -1,11 +1,25 @@
 /**
- * Human-readable size for CLI notes (1024-based).
- * files-sdk has no size formatter — only raw `size` on head/upload results.
+ * Decimal (SI) human sizes for CLI output. Plan catalog caps are round decimal
+ * numbers (250 MB free, 10 GB pro); binary units made Free look like 238.4 MB.
+ * Used for usage meters, list sizes, optimize notes, and doctor — same base
+ * as apps/web `formatBytes` / `formatMarketedBytes`.
  */
 export function formatByteSize(bytes) {
     if (!Number.isFinite(bytes) || bytes <= 0)
         return "0 B";
-    const units = ["B", "KB", "MB", "GB", "TB"];
-    const exponent = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
-    return `${(bytes / 1024 ** exponent).toFixed(exponent === 0 ? 0 : 1)} ${units[exponent]}`;
+    if (bytes < 1000)
+        return `${Math.round(bytes)} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let value = bytes / 1000;
+    let unit = 0;
+    while (value >= 1000 && unit < units.length - 1) {
+        value /= 1000;
+        unit += 1;
+    }
+    const rounded = value >= 10 ? Math.round(value) : Math.round(value * 10) / 10;
+    return `${rounded} ${units[unit]}`;
+}
+/** Alias for call sites that want plan-cap wording; same SI formatter. */
+export function formatMarketedBytes(bytes) {
+    return formatByteSize(bytes);
 }

package/dist/format-usage.d.ts

@@ -9,6 +9,8 @@ export type UsageSnapshotLike = {
     storageRemainingBytes?: number;
     maxUploadsPerPeriod?: number;
     uploadsRemaining?: number;
+    /** Catalog plan id when the API reports it (`free` | `pro`). */
+    plan?: string;
 };
 export type FormatUsageOptions = {
     /** IANA zone or undefined for the host local zone. */
@@ -34,5 +36,12 @@ export declare function formatProgressBar(pct: number, opts?: {
 }): string;
 /** Host-local time by default; pass `timeZone` for stable tests. */
 export declare function formatUsageTimestamp(iso: string, timeZone?: string): string;
+/**
+ * Display label for a plan catalog id. Free is shown too — free workspaces
+ * still have quotas (storage / monthly uploads) that usage meters report.
+ */
+export declare function planLabel(plan: string | undefined): string | null;
+/** @deprecated use planLabel — kept as an alias for any external importers. */
+export declare const paidPlanLabel: typeof planLabel;
 /** Human-readable lines for `uploads usage` (not JSON). */
 export declare function formatUsageHuman(result: UsageSnapshotLike, opts?: FormatUsageOptions): string[];

package/dist/format-usage.js

@@ -7,7 +7,7 @@
  * and operator workspaces usually omit them (unlimited). Progress bars only
  * appear for fields that have a positive cap — never invent a budget.
  */
-import { formatByteSize } from "./format-bytes.js";
+import { formatByteSize, formatMarketedBytes } from "./format-bytes.js";
 import { BRAND } from "./cli-brand.js";
 /** True when the API reported any cumulative workspace quota. */
 export function isUsageMetered(result) {
@@ -87,17 +87,39 @@ export function formatUsageTimestamp(iso, timeZone) {
         return iso;
     }
 }
+/**
+ * Display label for a plan catalog id. Free is shown too — free workspaces
+ * still have quotas (storage / monthly uploads) that usage meters report.
+ */
+export function planLabel(plan) {
+    if (!plan)
+        return null;
+    if (plan === "free")
+        return "Free";
+    if (plan === "pro")
+        return "Pro";
+    // Future tiers: title-case the id rather than hiding them.
+    return plan.charAt(0).toUpperCase() + plan.slice(1);
+}
+/** @deprecated use planLabel — kept as an alias for any external importers. */
+export const paidPlanLabel = planLabel;
 /** Human-readable lines for `uploads usage` (not JSON). */
 export function formatUsageHuman(result, opts = {}) {
     const width = opts.barWidth ?? 20;
     const color = opts.color === true;
     const metered = isUsageMetered(result);
     const lines = [`workspace: ${result.workspace}`];
+    const label = planLabel(result.plan);
+    if (label)
+        lines.push(`plan:      ${label}`);
     const storagePct = usagePct(result.bytes, result.maxStorageBytes);
     if (storagePct !== null && result.maxStorageBytes != null) {
-        const detail = `${formatByteSize(result.bytes)} / ${formatByteSize(result.maxStorageBytes)}` +
+        // Caps (and remaining-against-cap) use SI marketed formatting so Free's
+        // 250_000_000 reads as "250 MB", not binary "238.4 MB". Used bytes share
+        // the same base on this line so the three numbers stay coherent.
+        const detail = `${formatMarketedBytes(result.bytes)} / ${formatMarketedBytes(result.maxStorageBytes)}` +
             (result.storageRemainingBytes != null
-                ? ` (${formatByteSize(result.storageRemainingBytes)} free)`
+                ? ` (${formatMarketedBytes(result.storageRemainingBytes)} free)`
                 : "");
         const bar = formatProgressBar(storagePct, { width, color });
         lines.push(`storage:   ${bar}  ${detail}`);
@@ -118,8 +140,15 @@ export function formatUsageHuman(result, opts = {}) {
     }
     lines.push(`updated:   ${formatUsageTimestamp(result.updatedAt, opts.timeZone)}`);
     if (!metered) {
-        // Self-host / operator unlimited: report usage without implying a plan.
-        lines.push("note:      unmetered — no storage or upload quotas on this workspace");
+        // Self-host / operator unlimited, or a plan without reported caps.
+        // Free self-serve normally reports maxStorageBytes / maxUploadsPerPeriod;
+        // when those are missing, say so explicitly rather than implying unlimited free.
+        if (result.plan === "free") {
+            lines.push("note:      free plan — no quotas reported for this workspace (limits may still apply server-side)");
+        }
+        else {
+            lines.push("note:      unmetered — no storage or upload quotas on this workspace");
+        }
     }
     return lines;
 }

package/dist/github.d.ts

@@ -15,6 +15,12 @@ export declare function isValidRepo(repo: string): boolean;
 export declare function parseRepoFromRemoteUrl(url: string): string | undefined;
 /** Normalize a GitHub issue or pull-request coordinate for gallery linking. */
 export declare function normalizeGithubCoordinate(value: string): GithubCoordinate | undefined;
+/**
+ * Inverse of `ghKeyPrefix`: parse the PR/issue coordinate back out of a
+ * stable attachment key (`gh/<owner>/<name>/<kind>/<num>/<filename>`), or
+ * undefined for any other key shape.
+ */
+export declare function parseGhKey(key: string): GhTarget | undefined;
 export declare function ghKeyPrefix(target: GhTarget): string;
 /**
  * Stable attachment key: same filename → same key → same public URL, so

package/dist/github.js

@@ -53,6 +53,18 @@ export function normalizeGithubCoordinate(value) {
             number,
     };
 }
+/**
+ * Inverse of `ghKeyPrefix`: parse the PR/issue coordinate back out of a
+ * stable attachment key (`gh/<owner>/<name>/<kind>/<num>/<filename>`), or
+ * undefined for any other key shape.
+ */
+export function parseGhKey(key) {
+    const match = /^gh\/([^/]+)\/([^/]+)\/(pull|issues)\/([1-9][0-9]*)\/./.exec(key);
+    if (!match)
+        return undefined;
+    const [, owner, name, kind, num] = match;
+    return { repo: `${owner}/${name}`, kind: kind, num: Number(num) };
+}
 export function ghKeyPrefix(target) {
     const [owner, name] = target.repo.split("/");
     return `gh/${sanitizeKeySegment(owner)}/${sanitizeKeySegment(name)}/${target.kind}/${target.num}/`;

package/dist/mcp/tools.js

@@ -1,9 +1,9 @@
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, makeGhTarget, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
+import { buildDoctorReport, makeGhTarget, mergeStagingMeta, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { ghKeyPrefix, ghMetadataForBranch } from "../github.js";
+import { ghBranchAttachmentKey, ghKeyPrefix } from "../github.js";
 import { safeCaptureFacts } from "../capture-facts.js";
 import { validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
@@ -430,16 +430,7 @@ export function createUploadsMcpTools(opts) {
                     repoArg: optString(args, "repo") ?? defaults.repo,
                     run,
                 });
-                const putMetadata = stagingTarget
-                    ? (() => {
-                        const merged = {
-                            ...metadata,
-                            ...ghMetadataForBranch(stagingTarget.repo, stagingTarget.branch),
-                        };
-                        validateMetaMap(merged); // same builder, same contract as attach --branch
-                        return merged;
-                    })()
-                    : metadata;
+                const putMetadata = stagingTarget ? mergeStagingMeta(metadata, stagingTarget) : metadata;
                 const putShared = {
                     client,
                     ghTarget: target,
@@ -695,25 +686,41 @@ export function createUploadsMcpTools(opts) {
                 const metadata = metadataArgWithCanonical(args);
                 if (metadata)
                     validateMetaMap(metadata);
+                const { config, client } = 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 alt = optString(args, "alt");
+                const width = optPosInt(args, "width") ?? defaults.width;
+                // 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.
+                const stagingTarget = resolvePutStagingTarget({
+                    ghTarget: target,
+                    keyHint: keyArg,
+                    refArg,
+                    prefixArg,
+                    destinationArg: destArg,
+                    noGit,
+                    repoArg: optString(args, "repo") ?? defaults.repo,
+                    run,
+                });
                 let resolvedPrefix;
                 try {
                     resolvedPrefix = resolvePutPrefix({
                         destination: destArg,
                         prefix: prefixArg,
                         key: keyArg,
-                        ghAttachment: Boolean(target),
+                        ghAttachment: Boolean(target) || stagingTarget !== undefined,
                     });
                 }
                 catch (err) {
                     usage(err instanceof Error ? err.message : String(err));
                 }
-                const { config, client } = 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 alt = optString(args, "alt");
-                const width = optPosInt(args, "width") ?? defaults.width;
                 // Dynamic import only: keeps mcp/tools.ts (and therefore anything
                 // that statically imports it) free of a static reference to the
                 // local-backend chain. If this fails, the runtime can't do Node-side
@@ -730,9 +737,15 @@ export function createUploadsMcpTools(opts) {
                 // Keep undefined when nothing at all was supplied or derived, so the
                 // "omit to leave stored metadata untouched" contract still holds.
                 const captureDerived = safeCaptureFacts(targetArg, viewport, colorSchemeArg);
-                const metadataWithCaptureFacts = metadata === undefined && Object.keys(captureDerived).length === 0
+                const metadataBase = metadata === undefined && Object.keys(captureDerived).length === 0
                     ? undefined
                     : mergeDerivedMeta(metadata ?? {}, captureDerived);
+                // gh.* metadata: explicit pr/issue target wins; staging wins the same
+                // way (matches attach --branch/bare put); otherwise capture-derived +
+                // explicit only.
+                const metadataWithCaptureFacts = stagingTarget
+                    ? mergeStagingMeta(metadataBase, stagingTarget)
+                    : metadataBase;
                 let captured;
                 try {
                     captured = await screenshotModule.captureScreenshot({
@@ -761,11 +774,14 @@ export function createUploadsMcpTools(opts) {
                     }
                     throw err;
                 }
+                const branchKey = stagingTarget
+                    ? ghBranchAttachmentKey(stagingTarget.repo, stagingTarget.branch, captured.filename)
+                    : undefined;
                 const { result, prepared, markdown } = await uploadPreparedImage(client, captured.png, captured.filename, {
                     frame: frameOpts,
                     optimize: optimizeOpts,
                     ghTarget: target,
-                    key: keyArg,
+                    key: keyArg ?? branchKey,
                     prefix: resolvedPrefix ?? defaults.prefix,
                     repo: optString(args, "repo") ?? defaults.repo,
                     ref: refArg ?? defaults.ref,

package/dist/session-cli-version.d.ts

@@ -0,0 +1,15 @@
+export interface SyncCliVersionOptions {
+    sessionToken?: string;
+    authUrl?: string;
+    apiUrl?: string;
+    envFile?: string;
+    version?: string;
+    /** Skip the local "already synced this version" short-circuit. */
+    force?: boolean;
+    cachePath?: string;
+    fetchImpl?: typeof fetch;
+}
+/** Best-effort POST; never throws. */
+export declare function syncSessionCliVersion(opts?: SyncCliVersionOptions): Promise<boolean>;
+/** Fire-and-forget for CLI command starts. */
+export declare function maybeSyncSessionCliVersion(opts?: SyncCliVersionOptions): void;