@buildinternet/uploads 0.53.0 → 0.55.0

package/dist/docs.js

@@ -0,0 +1,439 @@
+/**
+ * Fetch and search the public uploads.sh docs catalog for `uploads docs`
+ * and the MCP `search_docs` tool.
+ */
+import { UploadsError } from "./errors.js";
+import { packageVersion } from "./package-version.js";
+export const DOCS_HUB_URL = "https://uploads.sh/docs";
+export const DOCS_JSON_URL = "https://uploads.sh/docs.json";
+export const DEFAULT_DOCS_LIMIT = 5;
+export const MAX_DOCS_LIMIT = 50;
+export const DOCS_SNIPPET_MAX_CHARS = 1500;
+export const DOCS_PAGE_MAX_CHARS = 50_000;
+const FETCH_TIMEOUT_MS = 8000;
+const SITE_ORIGIN = "https://uploads.sh";
+const STOP_WORDS = new Set([
+    "a",
+    "an",
+    "and",
+    "at",
+    "do",
+    "for",
+    "how",
+    "i",
+    "in",
+    "is",
+    "my",
+    "of",
+    "on",
+    "or",
+    "the",
+    "to",
+    "we",
+    "your",
+]);
+/** Built-in catalog used when /docs.json is unreachable. */
+export const FALLBACK_DOCS_CATALOG = {
+    url: DOCS_HUB_URL,
+    pages: [
+        {
+            page: "docs",
+            title: "Docs",
+            url: "https://uploads.sh/docs",
+            summary: "Install the uploads CLI, attach screenshots and video to GitHub PRs, issues, and code reviews, and set up your agent.",
+            aliases: ["overview", "hub", "install"],
+        },
+        {
+            page: "attach-pull-request-images",
+            title: "Attach & share",
+            url: "https://uploads.sh/docs/attach-pull-request-images",
+            summary: "Attach screenshots and video to GitHub PRs and issues, get a public URL for any accepted file, capture a screenshot, and bake callouts or redactions onto it with the uploads CLI.",
+            aliases: [
+                "attach",
+                "stage",
+                "staging",
+                "screenshot",
+                "annotate",
+                "pr",
+                "issue",
+                "before",
+                "after",
+                "put",
+                "share",
+            ],
+        },
+        {
+            page: "galleries",
+            title: "Galleries",
+            url: "https://uploads.sh/docs/galleries",
+            summary: "Create an ordered set of media behind one public link at /g/<id>, add files with uploads put --gallery, and link the gallery to a PR or issue.",
+            aliases: ["gallery", "collection"],
+        },
+        {
+            page: "github-app",
+            title: "GitHub App",
+            url: "https://uploads.sh/docs/github-app",
+            summary: "Install the uploads-sh GitHub App so attachment comments post as the bot, private-repo PR and issue titles show on file pages, and titles stay current.",
+            aliases: ["bot", "webhook", "promote", "app", "ingest"],
+        },
+        {
+            page: "comment-config",
+            title: "Comment config",
+            url: "https://uploads.sh/docs/comment-config",
+            summary: "Reference for .uploads.yml — a repo-committed file that controls image width, inline-image caps, caption metadata, and an optional note on the managed PR/issue comment.",
+            aliases: ["uploads.yml", "comment", "yaml", "yml", "width"],
+        },
+        {
+            page: "agents",
+            title: "Set up your agent",
+            url: "https://uploads.sh/docs/agents",
+            summary: "Install the uploads agent skill and MCP server so your coding agent can attach screenshots to GitHub on its own.",
+            aliases: ["mcp", "skill", "plugin", "claude", "codex"],
+        },
+        {
+            page: "reference",
+            title: "Reference",
+            url: "https://uploads.sh/docs/reference",
+            summary: "Manage uploaded files with the uploads CLI (list, delete, usage), plus what to know about visibility, access, and stability.",
+            aliases: ["list", "delete", "usage", "visibility"],
+        },
+        {
+            page: "limits",
+            title: "Plans & limits",
+            url: "https://uploads.sh/docs/limits",
+            summary: "Storage, file size, and member limits for uploads.sh free and pro workspaces, and how they compare with GitHub's own attachment caps.",
+            aliases: ["plan", "plans", "pricing", "quota", "storage", "pro", "free"],
+        },
+        {
+            page: "byo-bucket",
+            title: "Bring your own bucket",
+            url: "https://uploads.sh/docs/byo-bucket",
+            summary: "Point a workspace at your own Cloudflare R2 or S3-compatible bucket instead of hosted storage on storage.uploads.sh.",
+            aliases: ["r2", "s3", "byo", "bucket", "bring-your-own"],
+        },
+        {
+            page: "github-screenshots",
+            title: "How to get agents to upload screenshots & video to GitHub",
+            url: "https://uploads.sh/github-screenshots",
+            summary: "One command for Claude Code, CI jobs, and scripts that captures, hosts, and posts screenshots and video to PRs and issues, before or after the PR exists.",
+            aliases: ["walkthrough", "agent-guide", "how-to"],
+        },
+        {
+            page: "changelog",
+            title: "Changelog",
+            url: "https://uploads.sh/changelog",
+            summary: "Platform updates and CLI releases, newest first.",
+            aliases: ["updates", "release", "whats-new"],
+        },
+        {
+            page: "auth",
+            title: "Auth for agents",
+            url: "https://uploads.sh/auth.md",
+            summary: "Device sign-in, workspace bearer tokens, and hosted MCP OAuth.",
+            aliases: ["login", "token", "oauth", "bearer"],
+        },
+    ],
+};
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function asHttpUrl(value) {
+    const raw = asString(value);
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = new URL(raw);
+        if (parsed.protocol === "https:" || parsed.protocol === "http:")
+            return raw;
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string" && item.trim().length > 0);
+}
+function parsePage(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const rec = raw;
+    const page = asString(rec.page);
+    const title = asString(rec.title);
+    const url = asHttpUrl(rec.url);
+    const summary = asString(rec.summary);
+    if (!page || !title || !url || !summary)
+        return undefined;
+    return { page, title, url, summary, aliases: asStringArray(rec.aliases) };
+}
+export function parseDocsCatalog(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new UploadsError("docs catalog was not a JSON object", "API_ERROR");
+    }
+    const rec = raw;
+    if (!Array.isArray(rec.pages)) {
+        throw new UploadsError("docs catalog is missing a pages array", "API_ERROR");
+    }
+    const pages = rec.pages.map(parsePage).filter((p) => p !== undefined);
+    if (pages.length === 0) {
+        throw new UploadsError("docs catalog had no usable pages", "API_ERROR");
+    }
+    return { url: asHttpUrl(rec.url) ?? DOCS_HUB_URL, pages };
+}
+function clampDocsLimit(limit, fallback = DEFAULT_DOCS_LIMIT) {
+    const n = limit ?? fallback;
+    if (n > MAX_DOCS_LIMIT)
+        return MAX_DOCS_LIMIT;
+    if (n < 1)
+        return fallback;
+    return n;
+}
+function tokenizeDocsQuery(query) {
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 1 && !STOP_WORDS.has(token));
+}
+function normalizeDocsKey(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/^https:\/\/uploads\.sh/i, "")
+        .replace(/^\/+/, "")
+        .replace(/\/+$/, "");
+}
+function pageKeys(page) {
+    const keys = [page.page, ...page.aliases];
+    try {
+        const path = new URL(page.url).pathname.replace(/^\/+/, "").replace(/\/+$/, "");
+        keys.push(path);
+        const leaf = path.split("/").pop();
+        if (leaf)
+            keys.push(leaf);
+        if (path.startsWith("docs/"))
+            keys.push(path.slice("docs/".length));
+    }
+    catch {
+        // Catalog URLs are validated on parse; ignore a malformed fallback entry.
+    }
+    return keys.map(normalizeDocsKey).filter(Boolean);
+}
+export function resolveDocsPage(catalog, raw) {
+    const query = normalizeDocsKey(raw);
+    if (!query)
+        return undefined;
+    const stripped = query.startsWith("docs/") ? query.slice("docs/".length) : query;
+    for (const page of catalog.pages) {
+        const keys = pageKeys(page);
+        if (keys.includes(query) || keys.includes(stripped))
+            return page;
+    }
+    return undefined;
+}
+function searchableText(page) {
+    return `${page.page} ${page.title} ${page.summary} ${page.aliases.join(" ")}`.toLowerCase();
+}
+function scoreDocsPage(page, tokens) {
+    if (tokens.length === 0)
+        return 0;
+    const text = searchableText(page);
+    let matched = 0;
+    for (const token of tokens) {
+        if (text.includes(token))
+            matched += 1;
+    }
+    if (matched === 0)
+        return 0;
+    return matched * 10 + (matched === tokens.length ? 40 : 0);
+}
+export function rankDocsPages(catalog, query) {
+    const tokens = tokenizeDocsQuery(query);
+    const needle = query.trim().toLowerCase();
+    const scored = catalog.pages
+        .map((page) => {
+        const tokenScore = tokens.length > 0 ? scoreDocsPage(page, tokens) : 0;
+        const substringScore = tokenScore === 0 && needle.length > 0 && searchableText(page).includes(needle) ? 5 : 0;
+        return { page, score: tokenScore + substringScore };
+    })
+        .filter((row) => row.score > 0)
+        .sort((a, b) => b.score - a.score || a.page.title.localeCompare(b.page.title));
+    return scored.map((row) => row.page);
+}
+export function truncateDocsSnippet(text, maxChars = DOCS_SNIPPET_MAX_CHARS) {
+    const trimmed = text.trim();
+    if (trimmed.length <= maxChars)
+        return trimmed;
+    const cut = trimmed.slice(0, maxChars - 1);
+    const atSpace = cut.lastIndexOf(" ");
+    return `${atSpace > 40 ? cut.slice(0, atSpace) : cut}…`;
+}
+function hitFromPage(page, body) {
+    if (body === undefined) {
+        return {
+            title: page.title,
+            url: page.url,
+            page: page.page,
+            snippet: page.summary,
+        };
+    }
+    const clipped = body.length > DOCS_PAGE_MAX_CHARS ? body.slice(0, DOCS_PAGE_MAX_CHARS) : body;
+    const snippet = truncateDocsSnippet(clipped);
+    return {
+        title: page.title,
+        url: page.url,
+        page: page.page,
+        snippet,
+        body: clipped,
+        ...(snippet.length < clipped.trim().length || body.length > DOCS_PAGE_MAX_CHARS
+            ? { truncated: true }
+            : {}),
+    };
+}
+function indent(text, prefix = "  ") {
+    return text
+        .split("\n")
+        .map((line) => (line.length === 0 ? prefix.trimEnd() : `${prefix}${line}`))
+        .join("\n");
+}
+/** Human terminal output for catalog/search hits. A fetched page prints its body. */
+export function formatDocsHuman(doc) {
+    const lines = [];
+    const only = doc.results.length === 1 ? doc.results[0] : undefined;
+    if (only?.body) {
+        lines.push(only.title);
+        lines.push(only.url);
+        lines.push("");
+        lines.push(only.body.trimEnd());
+        return `${lines.join("\n")}\n`;
+    }
+    lines.push("Docs", "");
+    if (doc.results.length === 0) {
+        lines.push("No matching docs.");
+    }
+    else {
+        for (const hit of doc.results) {
+            lines.push(hit.title);
+            lines.push(hit.url);
+            lines.push("");
+            lines.push(indent(hit.snippet));
+            lines.push("");
+        }
+    }
+    lines.push(`See all docs: ${doc.url}`);
+    return `${lines.join("\n")}\n`;
+}
+function isUploadsDocsUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.origin === SITE_ORIGIN;
+    }
+    catch {
+        return false;
+    }
+}
+async function fetchUrl(fetchImpl, url, headers, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchImpl(url, { signal: controller.signal, headers });
+    }
+    catch (err) {
+        const aborted = err instanceof Error && err.name === "AbortError";
+        throw new UploadsError(aborted
+            ? `timed out fetching docs (${timeoutMs}ms)`
+            : `couldn't reach docs (${err instanceof Error ? err.message : String(err)})`, "NETWORK");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function loadDocsCatalog(opts = {}) {
+    if (opts.catalog)
+        return opts.catalog;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? FETCH_TIMEOUT_MS;
+    const userAgent = opts.userAgent ?? `uploads/${packageVersion()}`;
+    const jsonUrl = opts.url ?? DOCS_JSON_URL;
+    try {
+        const res = await fetchUrl(fetchImpl, jsonUrl, { "user-agent": userAgent, accept: "application/json" }, timeoutMs);
+        if (res.ok) {
+            try {
+                const payload = await res.json();
+                return parseDocsCatalog(payload);
+            }
+            catch (err) {
+                if (opts.url) {
+                    throw err instanceof UploadsError
+                        ? err
+                        : new UploadsError("docs catalog was not valid JSON", "API_ERROR", res.status);
+                }
+            }
+        }
+        else if (opts.url) {
+            throw new UploadsError(`docs catalog returned HTTP ${res.status}; see ${DOCS_HUB_URL}`, "API_ERROR", res.status);
+        }
+    }
+    catch (err) {
+        if (opts.url)
+            throw err;
+    }
+    return FALLBACK_DOCS_CATALOG;
+}
+async function fetchPageMarkdown(page, opts) {
+    if (!isUploadsDocsUrl(page.url)) {
+        throw new UploadsError(`refusing to fetch docs outside ${SITE_ORIGIN}`, "USAGE");
+    }
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? FETCH_TIMEOUT_MS;
+    const userAgent = opts.userAgent ?? `uploads/${packageVersion()}`;
+    const res = await fetchUrl(fetchImpl, page.url, {
+        "user-agent": userAgent,
+        accept: "text/markdown, text/plain;q=0.9",
+    }, timeoutMs);
+    if (!res.ok) {
+        throw new UploadsError(`docs page returned HTTP ${res.status}; see ${page.url}`, "API_ERROR", res.status);
+    }
+    const body = await res.text();
+    return hitFromPage(page, body);
+}
+export async function searchDocs(opts = {}) {
+    const catalog = await loadDocsCatalog(opts);
+    const pageArg = opts.page?.trim();
+    const query = opts.query?.trim();
+    if (pageArg) {
+        const page = resolveDocsPage(catalog, pageArg);
+        if (!page) {
+            throw new UploadsError(`unknown docs page: ${pageArg}`, "USAGE");
+        }
+        const hit = await fetchPageMarkdown(page, opts);
+        return {
+            url: catalog.url,
+            query: pageArg,
+            results: [hit],
+            total: 1,
+        };
+    }
+    if (query) {
+        const exact = resolveDocsPage(catalog, query);
+        if (exact && !/\s/.test(query)) {
+            const hit = await fetchPageMarkdown(exact, opts);
+            return { url: catalog.url, query, results: [hit], total: 1 };
+        }
+        const ranked = rankDocsPages(catalog, query);
+        const sliced = ranked.slice(0, clampDocsLimit(opts.limit));
+        return {
+            url: catalog.url,
+            query,
+            results: sliced.map((page) => hitFromPage(page)),
+            total: ranked.length,
+        };
+    }
+    const sliced = opts.limit === undefined ? catalog.pages : catalog.pages.slice(0, clampDocsLimit(opts.limit));
+    return {
+        url: catalog.url,
+        results: sliced.map((page) => hitFromPage(page)),
+        total: catalog.pages.length,
+    };
+}

package/dist/github.d.ts

@@ -5,9 +5,21 @@ export interface GithubCoordinate {
     coordinate: string;
     canonicalUrl: string;
 }
+/** Parsed `owner/repo#number` or a strict GitHub issue/PR URL. */
+export interface GithubIssueRef {
+    repo: string;
+    number: number;
+    kind?: "pull" | "issue";
+}
 export declare function isValidRepo(repo: string): boolean;
 /** Parse "owner/name" from a git remote URL (SSH or HTTPS), else undefined. */
 export declare function parseRepoFromRemoteUrl(url: string): string | undefined;
+/**
+ * Parse `owner/repo#number` or a strict
+ * `https://github.com/<owner>/<repo>/issues|pull/<number>` URL. Kind is set
+ * only when the URL path names `/pull/` or `/issues/`.
+ */
+export declare function parseGithubIssueRef(value: string): GithubIssueRef | undefined;
 /** Normalize a GitHub issue or pull-request coordinate for gallery linking. */
 export declare function normalizeGithubCoordinate(value: string): GithubCoordinate | undefined;
 /**

package/dist/github.js

@@ -13,6 +13,46 @@ export function parseRepoFromRemoteUrl(url) {
     const repo = match?.[1];
     return repo && isValidRepo(repo) ? repo : undefined;
 }
+/**
+ * Parse `owner/repo#number` or a strict
+ * `https://github.com/<owner>/<repo>/issues|pull/<number>` URL. Kind is set
+ * only when the URL path names `/pull/` or `/issues/`.
+ */
+export function parseGithubIssueRef(value) {
+    const input = value.trim();
+    const coordinate = /^([^/\s#]+)\/([^/\s#]+)#([1-9][0-9]*)$/.exec(input);
+    if (coordinate)
+        return githubIssueRef(coordinate[1], coordinate[2], coordinate[3]);
+    try {
+        const url = new URL(input);
+        if (url.protocol !== "https:" ||
+            url.hostname.toLowerCase() !== "github.com" ||
+            url.port ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash)
+            return undefined;
+        const match = /^\/([^/]+)\/([^/]+)\/(issues|pull)\/([1-9][0-9]*)\/?$/.exec(url.pathname);
+        if (!match)
+            return undefined;
+        return githubIssueRef(match[1], match[2], match[4], match[3] === "issues" ? "issue" : "pull");
+    }
+    catch {
+        return undefined;
+    }
+}
+function githubIssueRef(ownerRaw, repositoryRaw, numberRaw, kind) {
+    const repo = ownerRaw + "/" + repositoryRaw;
+    const number = Number(numberRaw);
+    if (!isValidRepo(repo) || !Number.isSafeInteger(number))
+        return undefined;
+    return {
+        repo: ownerRaw.toLowerCase() + "/" + repositoryRaw.toLowerCase(),
+        number,
+        ...(kind ? { kind } : {}),
+    };
+}
 /** Normalize a GitHub issue or pull-request coordinate for gallery linking. */
 export function normalizeGithubCoordinate(value) {
     const input = value.trim();

package/dist/index.d.ts

@@ -5,11 +5,12 @@ export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, reso
 export { DEFAULT_API_URL, DEFAULT_WORKSPACE, UPLOADS_CONFIG_KEYS, defaultConfigPath, resolveConfigPath, loadConfigFile, loadEnvFile, resolveApiUrl, resolveConfig, describeConfigSources, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, workspaceFromToken, workspaceMismatch, type UploadsClientConfig, type ResolvedConfig, type WorkspaceSource, type ConfigValueSource, type ConfigSources, type UploadsConfigKey, type UploadsConfigValues, type PutDefaults, } from "./config.js";
 export { UploadsError, type UploadsErrorCode } from "./errors.js";
 export { CHANGELOG_JSON_URL, CHANGELOG_PAGE_URL, CHANGELOG_XML_URL, DEFAULT_CHANGELOG_LIMIT, MAX_CHANGELOG_LIMIT, fetchChangelog, formatChangelogHuman, parseChangelogAtom, parseChangelogJson, selectChangelogEntries, type ChangelogDocument, type ChangelogJsonEntry, type FetchChangelogOptions, } from "./changelog.js";
+export { DEFAULT_DOCS_LIMIT, DOCS_HUB_URL, DOCS_JSON_URL, MAX_DOCS_LIMIT, formatDocsHuman, searchDocs, type DocsCatalog, type DocsSearchDocument, type SearchDocsOptions, } from "./docs.js";
 export { assertFetchableUploadUrl, fetchUploadSource, filenameFromUploadUrl, resolveUploadFilename, FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES, FETCH_UPLOAD_SOURCE_MAX_REDIRECTS, FETCH_UPLOAD_SOURCE_TIMEOUT_MS, } from "./fetch-upload-source.js";
 export { createUploadsClient, type UploadsClient, type PutOptions, type ProvenanceInput, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type GalleryItem, type Gallery, type GallerySummary, type GalleryListOptions, type GalleryListResult, type CreateGalleryOptions, type AddGalleryItemOptions, type DeleteGalleryOptions, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type MetadataKeysResult, type MetadataValuesResult, type GetMetadataResult, type PatchMetadataOptions, type ResolveGhPrefixOptions, type ResolveGhPrefixResult, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, GH_PRIVATE_ROOT, ghPrivateKeyPrefix, ghPrivateAttachmentKey, ghPrivateBranchKeyPrefix, ghPrivateBranchAttachmentKey, ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, parseGhKey, parseGhPrivateKey, type AttachmentItem, type GhTarget, type GhTargetKind, type GhKeyMode, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseGithubIssueRef, parseRepoFromRemoteUrl, GH_PRIVATE_ROOT, ghPrivateKeyPrefix, ghPrivateAttachmentKey, ghPrivateBranchKeyPrefix, ghPrivateBranchAttachmentKey, ghAttachmentKeyForMode, ghBranchAttachmentKeyForMode, parseGhKey, parseGhPrivateKey, type AttachmentItem, type GithubIssueRef, type GhTarget, type GhTargetKind, type GhKeyMode, } from "./github.js";
 export { DEFAULT_OPTIMIZE_MAX_EDGE, DEFAULT_OPTIMIZE_QUALITY, optimizeImageForUpload, rewriteKeyExtension, withImageExtension, type OptimizeImageOptions, type OptimizeImageResult, type OptimizeOutputFormat, } from "./optimize.js";
 export { FRAME_PRESETS, applyFrame, listFramePresets, resolveFrameId, type FrameFit, type FrameOptions, type FrameResult, } from "./frame.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, type CommandRunner, } from "./github-gh.js";

package/dist/index.js

@@ -5,11 +5,12 @@ export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, reso
 export { DEFAULT_API_URL, DEFAULT_WORKSPACE, UPLOADS_CONFIG_KEYS, defaultConfigPath, resolveConfigPath, loadConfigFile, loadEnvFile, resolveApiUrl, resolveConfig, describeConfigSources, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, workspaceFromToken, workspaceMismatch, } from "./config.js";
 export { UploadsError } from "./errors.js";
 export { CHANGELOG_JSON_URL, CHANGELOG_PAGE_URL, CHANGELOG_XML_URL, DEFAULT_CHANGELOG_LIMIT, MAX_CHANGELOG_LIMIT, fetchChangelog, formatChangelogHuman, parseChangelogAtom, parseChangelogJson, selectChangelogEntries, } from "./changelog.js";
+export { DEFAULT_DOCS_LIMIT, DOCS_HUB_URL, DOCS_JSON_URL, MAX_DOCS_LIMIT, formatDocsHuman, searchDocs, } from "./docs.js";
 export { assertFetchableUploadUrl, fetchUploadSource, filenameFromUploadUrl, resolveUploadFilename, FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES, FETCH_UPLOAD_SOURCE_MAX_REDIRECTS, FETCH_UPLOAD_SOURCE_TIMEOUT_MS, } from "./fetch-upload-source.js";
 export { createUploadsClient, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, 
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseGithubIssueRef, parseRepoFromRemoteUrl, 
 // Private-repo randomized-prefix builders (issue #631) — needed by the
 // hosted MCP (apps/mcp), which builds keys in-process rather than via
 // the CLI's own commands.ts.

package/dist/mcp/docs-tool.d.ts

@@ -0,0 +1,4 @@
+import { type ToolArgs } from "./args.js";
+export declare const SEARCH_DOCS_DESCRIPTION = "Search the public uploads.sh documentation. Use this to answer questions about uploads.sh product workflows, including: attaching screenshots and video to GitHub PRs and issues; staging files before a PR exists; galleries; the GitHub App; comment config (.uploads.yml); hosted MCP and agent setup; screenshot capture and annotate; plans and limits; bring-your-own bucket. Same as `uploads docs`. Returns titles, URLs, and snippets. Pass `page` to fetch the full markdown of one page (slug, path, or URL). Omit `query` to list the catalog.";
+export declare const SEARCH_DOCS_INPUT_SCHEMA: Record<string, unknown>;
+export declare function runSearchDocsTool(args: ToolArgs): Promise<import("../docs.js").DocsSearchDocument>;

package/dist/mcp/docs-tool.js

@@ -0,0 +1,35 @@
+/**
+ * Shared MCP `search_docs` surface for stdio and hosted servers.
+ */
+import { DEFAULT_DOCS_LIMIT, MAX_DOCS_LIMIT, searchDocs } from "../docs.js";
+import { optPosInt, optString, usage } from "./args.js";
+export const SEARCH_DOCS_DESCRIPTION = "Search the public uploads.sh documentation. Use this to answer questions about uploads.sh product workflows, including: attaching screenshots and video to GitHub PRs and issues; staging files before a PR exists; galleries; the GitHub App; comment config (.uploads.yml); hosted MCP and agent setup; screenshot capture and annotate; plans and limits; bring-your-own bucket. Same as `uploads docs`. Returns titles, URLs, and snippets. Pass `page` to fetch the full markdown of one page (slug, path, or URL). Omit `query` to list the catalog.";
+export const SEARCH_DOCS_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        query: {
+            type: "string",
+            description: "Search query (e.g. 'stage before a PR'). A single slug like 'attach' fetches that page.",
+        },
+        page: {
+            type: "string",
+            description: "Fetch one page as markdown. Accepts a slug (`attach`), path (`/docs/agents`), or https://uploads.sh URL.",
+        },
+        limit: {
+            type: "number",
+            description: `How many search hits to return (default ${DEFAULT_DOCS_LIMIT}, max ${MAX_DOCS_LIMIT}). Ignored when fetching one page.`,
+        },
+    },
+    additionalProperties: false,
+};
+export async function runSearchDocsTool(args) {
+    const query = optString(args, "query");
+    const page = optString(args, "page");
+    if (query && page)
+        usage("pass query or page, not both");
+    const limit = optPosInt(args, "limit");
+    if (limit !== undefined && limit > MAX_DOCS_LIMIT) {
+        usage(`limit must be ${MAX_DOCS_LIMIT} or less`);
+    }
+    return searchDocs({ query, page, limit });
+}

package/dist/mcp/output-schemas.d.ts

@@ -22,9 +22,11 @@ export declare const reconcileResultSchema: JsonSchema;
 export declare const purgeExpiredResultSchema: JsonSchema;
 export declare const whoamiResultSchema: JsonSchema;
 export declare const changelogResultSchema: JsonSchema;
+export declare const searchDocsResultSchema: JsonSchema;
 export declare const promoteToolResultSchema: JsonSchema;
 export declare const galleryResultSchema: JsonSchema;
 export declare const galleryFindResultSchema: JsonSchema;
+export declare const feedResultSchema: JsonSchema;
 /** Hosted catalog — every tool must have an entry. */
 export declare const hostedOutputSchemas: Record<string, JsonSchema>;
 /** Shared-shape stdio tools. Hosted-only tools (`promote`, `repo_link_status`) omitted. */