@buildinternet/uploads 0.16.0 → 0.17.0

package/bin/dist-staleness.d.mts

@@ -0,0 +1,8 @@
+export interface DistStalenessResult {
+  stale: boolean;
+  checked: boolean;
+  reason?: string;
+}
+
+export declare function checkDistStaleness(packageRoot: string): DistStalenessResult;
+export declare function warnIfDistStale(packageRoot: string): void;

package/bin/dist-staleness.mjs

@@ -0,0 +1,94 @@
+// Dev-only staleness guard for the linked `uploads` CLI (issue #295).
+//
+// A globally-linked `uploads` binary resolves to this monorepo package and
+// imports the compiled `dist/cli.js`. `dist/` is only rebuilt by an explicit
+// `pnpm --filter @buildinternet/uploads build`, so after pulling new source
+// the linked CLI can silently keep running old compiled code while
+// `--version` still reports the current package version.
+//
+// This module is intentionally plain, dependency-free JS (not compiled)
+// so it can run before `dist/` is imported, and so it has no cost at all
+// for a published npm install: `files` in package.json ships only
+// `bin/`, `dist/`, and `README.md` — never `src/` — so `sourceDir` below
+// simply won't exist there, and `checkDistStaleness` returns early after
+// one `existsSync` call.
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** Recursively find the newest mtime (ms) among files under `dir`. */
+function newestMtimeMs(dir) {
+  let newest = -Infinity;
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile()) {
+        try {
+          const mtimeMs = statSync(full).mtimeMs;
+          if (mtimeMs > newest) newest = mtimeMs;
+        } catch {
+          // ignore races (file removed between readdir and stat)
+        }
+      }
+    }
+  }
+  return newest;
+}
+
+/**
+ * Compare source mtime against dist mtime.
+ *
+ * @param {string} packageRoot absolute path to packages/uploads
+ * @returns {{ stale: boolean, checked: boolean, reason?: string }}
+ *   `checked` is false when there's no source tree to compare against
+ *   (i.e. a published install) — the check is a no-op in that case.
+ */
+export function checkDistStaleness(packageRoot) {
+  const sourceDir = join(packageRoot, "src");
+  const distDir = join(packageRoot, "dist");
+
+  // No src/ tree ships in the published npm package (see package.json
+  // "files"), so this is the cheapest reliable signal that we're running
+  // inside the monorepo (dev/linked context) rather than a published install.
+  if (!existsSync(sourceDir)) {
+    return { stale: false, checked: false };
+  }
+
+  if (!existsSync(distDir)) {
+    return { stale: true, checked: true, reason: "dist/ is missing" };
+  }
+
+  const sourceMtime = newestMtimeMs(sourceDir);
+  const distMtime = newestMtimeMs(distDir);
+
+  if (sourceMtime > distMtime) {
+    return { stale: true, checked: true, reason: "dist/ predates src/" };
+  }
+
+  return { stale: false, checked: true };
+}
+
+/** Print a one-line stderr warning if the dev build looks stale. Never throws. */
+export function warnIfDistStale(packageRoot) {
+  try {
+    const result = checkDistStaleness(packageRoot);
+    if (result.checked && result.stale) {
+      process.stderr.write(
+        `warning: uploads dev build is stale (${result.reason}) — run \`pnpm --filter @buildinternet/uploads build\`\n`,
+      );
+    }
+  } catch {
+    // Never let the staleness check itself break the CLI.
+  }
+}

package/bin/uploads.js

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
-import { runCli } from "../dist/cli.js";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { warnIfDistStale } from "./dist-staleness.mjs";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+warnIfDistStale(packageRoot);
+
+const { runCli } = await import("../dist/cli.js");
 
 runCli(process.argv)
   .then((code) => process.exit(code ?? 0))

package/dist/client.d.ts

@@ -236,6 +236,13 @@ export interface GithubHealthResult {
     events: string[] | null;
     missingEvents: string[];
     requiredEvents: string[];
+    /**
+     * Recommended-but-non-gating events, e.g. `issue_comment` (issue #333).
+     * Optional: older servers' health payload predates this field — treat a
+     * missing field as "no recommendations", not an error.
+     */
+    recommendedEvents?: string[];
+    missingRecommendedEvents?: string[];
     hint?: string;
 }
 export interface UsageResult {

package/dist/commands.js

@@ -1755,6 +1755,16 @@ Examples:
   uploads github unlink --repo buildinternet/uploads
   uploads github doctor
 `;
+/** Older servers' health payload predates recommendedEvents/missingRecommendedEvents — treat as no recommendations rather than crashing. */
+function missingRecommendedEventsOf(result) {
+    return Array.isArray(result.missingRecommendedEvents) ? result.missingRecommendedEvents : [];
+}
+function recommendedNoteLine(result) {
+    const missing = missingRecommendedEventsOf(result);
+    if (missing.length === 0)
+        return "";
+    return `note: not subscribed to ${missing.join(", ")} (recommended) — enables bot-comment self-healing; subscribe under the App's Permissions & events\n`;
+}
 function formatGithubDoctor(result) {
     if (!result.configured) {
         return `github app: not configured on this server${result.hint ? ` — ${result.hint}` : ""}\n`;
@@ -1763,10 +1773,12 @@ function formatGithubDoctor(result) {
         return `github app: configured, but health check failed${result.hint ? ` — ${result.hint}` : ""}\n`;
     }
     if (result.ok) {
-        return `github app: ok — subscribed to ${result.requiredEvents.join(", ")}\n`;
+        return (`github app: ok — subscribed to ${result.requiredEvents.join(", ")}\n` +
+            recommendedNoteLine(result));
     }
     return (`github app: missing webhook event subscription(s): ${result.missingEvents.join(", ")}\n` +
-        (result.hint ? `  ${result.hint}\n` : ""));
+        (result.hint ? `  ${result.hint}\n` : "") +
+        recommendedNoteLine(result));
 }
 function formatGithubLink(repo, result) {
     return result.workspace

package/dist/github.js

@@ -239,5 +239,6 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         lines.push("", "</details>", "");
     }
     lines.push('<sub>Maintained by <a href="https://uploads.sh">uploads.sh</a> — re-uploading a file with the same name updates it everywhere it is embedded.</sub>');
+    lines.push('<sub>Add media: <code>uploads put &lt;file&gt; --pr &lt;N&gt; --comment</code> (or <code>--issue &lt;N&gt;</code>) · <a href="https://uploads.sh/docs/github-app">docs</a></sub>');
     return lines.join("\n");
 }

package/dist/mcp/tools.js

@@ -334,7 +334,7 @@ export function createUploadsMcpTools(opts) {
                     noGit: { type: "boolean", description: "Don't derive the repo segment from git." },
                     comment: {
                         type: "boolean",
-                        description: "With pr/issue: create or update the managed attachments comment via local gh auth (best-effort).",
+                        description: "With pr/issue: create or update the managed attachments comment. Posts as uploads-sh[bot] when the GitHub App is installed on the repo; otherwise via local gh auth (best-effort).",
                     },
                     dryRun: {
                         type: "boolean",
@@ -1049,7 +1049,7 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "comment",
-            description: "Create or update the managed attachments comment on a GitHub PR or issue, listing everything uploaded for it. Uses local gh auth; edits its own prior comment in place and never touches other comments.",
+            description: "Create or update the managed attachments comment on a GitHub PR or issue, listing everything uploaded for it. Posts as uploads-sh[bot] when the GitHub App is installed on the repo; otherwise via local gh auth. Edits its own prior comment in place and never touches other comments.",
             inputSchema: {
                 type: "object",
                 properties: {

package/package.json

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