@buildinternet/uploads 0.33.0 → 0.33.1

package/README.md

@@ -17,6 +17,8 @@ uploads --version
 uploads attach ./before.png ./after.png
 uploads screenshot https://app.example --pr 123 --comment   # capture + host in one step
 uploads screenshot ./report.html --dark --selector "main"
+uploads screenshot http://localhost:3000 --via local --annotate ./callouts.json
+uploads annotate ./shot.png --spec ./callouts.json --out ./shot.marked.png
 uploads put ./shot.png
 uploads put ./shot.png --destination screenshots
 uploads put ./shot.png --no-optimize

package/dist/commands/install.d.ts

@@ -8,6 +8,17 @@ export interface StepResult {
     error?: string;
     output?: string;
 }
+/** npm 7+ for `npx -y`. Node 22 ships npm 10+; this catches ancient/system npm. */
+export declare const MIN_NPM_MAJOR_FOR_SKILLS = 7;
+/** Install guidance when a host binary is missing (not "run manually: <same binary>"). */
+export declare function missingBinaryHint(binary: string): string;
+export declare function npmTooOldHint(version: string): string;
+/**
+ * Probe npx/npm once before the per-skill loop. Returns an error string when
+ * tooling is missing/too old; undefined means skill steps should proceed.
+ * Non-ENOENT npx failures are left for the real `skills add` to surface.
+ */
+export declare function probeSkillTooling(run: CommandRunner): string | undefined;
 export declare function runStep(run: CommandRunner, command: string[]): StepResult;
 export declare function runInstall(args: string[], opts: {
     globals: GlobalFlags;

package/dist/commands/install.js

@@ -33,9 +33,11 @@ What it does:
 
 What runs under the hood:
   skill   npx -y skills add ${SKILL_SOURCE} --skill <name> -g -y -a '*'
-          (once per skill: ${SKILL_NAMES.join(", ")})
+          (once per skill: ${SKILL_NAMES.join(", ")}; needs Node 22+ / npm 7+
+          with npx on PATH — missing tooling fails once with install guidance)
   mcp     claude mcp add --transport http uploads ${DEFAULT_MCP_URL} \\
             --header "Authorization: Bearer <token>"
+          (needs the Claude Code CLI on PATH)
   hooks   write/merge ~/.grok/hooks/… and ~/.cursor/hooks.json when present
 
 Options:
@@ -51,6 +53,8 @@ Examples:
   uploads install hooks
   uploads install --dry-run
 `;
+/** npm 7+ for `npx -y`. Node 22 ships npm 10+; this catches ancient/system npm. */
+export const MIN_NPM_MAJOR_FOR_SKILLS = 7;
 /** Mask Bearer credentials and the configured token in any printed text. */
 function redactor(token) {
     return (text) => {
@@ -60,6 +64,55 @@ function redactor(token) {
         return out;
     };
 }
+function isEnoent(err) {
+    return err?.code === "ENOENT";
+}
+/** Install guidance when a host binary is missing (not "run manually: <same binary>"). */
+export function missingBinaryHint(binary) {
+    switch (binary) {
+        case "npx":
+        case "npm":
+            return (`${binary} not found on PATH — skill install needs Node.js (npm includes npx). ` +
+                `Install Node 22+ from https://nodejs.org (or your package manager), open a new shell, ` +
+                `confirm \`${binary} --version\` works, then re-run \`uploads install skill\`.`);
+        case "claude":
+            return (`claude not found on PATH — MCP install needs the Claude Code CLI. ` +
+                `Install it from https://docs.anthropic.com/en/docs/claude-code, ensure \`claude\` is on PATH, ` +
+                `then re-run \`uploads install mcp\`. Skills and hooks still work without Claude Code.`);
+        default:
+            return `${binary} not found on PATH — install it and ensure it is available in this shell.`;
+    }
+}
+export function npmTooOldHint(version) {
+    return (`npm ${version} is too old for skill install (need npm ${MIN_NPM_MAJOR_FOR_SKILLS}+ for \`npx -y\`). ` +
+        `Upgrade Node/npm (Node 22+ recommended: https://nodejs.org), confirm \`npm --version\`, ` +
+        `then re-run \`uploads install skill\`.`);
+}
+/**
+ * Probe npx/npm once before the per-skill loop. Returns an error string when
+ * tooling is missing/too old; undefined means skill steps should proceed.
+ * Non-ENOENT npx failures are left for the real `skills add` to surface.
+ */
+export function probeSkillTooling(run) {
+    try {
+        run("npx", ["--version"]);
+    }
+    catch (err) {
+        return isEnoent(err) ? missingBinaryHint("npx") : undefined;
+    }
+    try {
+        const out = run("npm", ["--version"]).trim();
+        const major = Number.parseInt(out.split(".")[0] ?? "", 10);
+        if (Number.isFinite(major) && major < MIN_NPM_MAJOR_FOR_SKILLS) {
+            return npmTooOldHint(out);
+        }
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return missingBinaryHint("npm");
+    }
+    return undefined;
+}
 export function runStep(run, command) {
     try {
         const output = run(command[0], command.slice(1)).trim();
@@ -67,10 +120,11 @@ export function runStep(run, command) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        const hint = err.code === "ENOENT"
-            ? `${command[0]} not found on PATH — install it, or run manually: ${command.join(" ")}`
-            : message;
-        return { command, ok: false, error: hint };
+        return {
+            command,
+            ok: false,
+            error: isEnoent(err) ? missingBinaryHint(command[0]) : message,
+        };
     }
 }
 function skillCommand(skill) {
@@ -115,31 +169,63 @@ function peekToken(globals) {
         return undefined;
     }
 }
-function printHumanSteps(results, redact, verbose, mcpName) {
-    for (const [step, r] of Object.entries(results)) {
-        const cmd = redact(r.command.join(" "));
-        if (r.skipped === "dry-run") {
-            process.stdout.write(`${step}: would run — ${cmd}\n`);
-        }
-        else if (r.skipped === "sign-in") {
-            process.stdout.write(`${step}: skipped — ${redact(r.error ?? "needs sign-in")}\n`);
-        }
-        else if (r.skipped === "already-configured") {
-            process.stdout.write(`${step}: already configured — "${mcpName}" is registered in Claude Code (nothing to do)\n` +
-                `  To re-register (e.g. with a new token): claude mcp remove ${mcpName} && uploads install mcp\n`);
+function printOneHumanStep(step, r, redact, verbose, mcpName) {
+    const cmd = redact(r.command.join(" "));
+    if (r.skipped === "dry-run") {
+        process.stdout.write(`${step}: would run — ${cmd}\n`);
+    }
+    else if (r.skipped === "sign-in") {
+        process.stdout.write(`${step}: skipped — ${redact(r.error ?? "needs sign-in")}\n`);
+    }
+    else if (r.skipped === "already-configured") {
+        process.stdout.write(`${step}: already configured — "${mcpName}" is registered in Claude Code (nothing to do)\n` +
+            `  To re-register (e.g. with a new token): claude mcp remove ${mcpName} && uploads install mcp\n`);
+    }
+    else if (r.ok) {
+        process.stdout.write(`${step}: ok\n`);
+        if (verbose && r.output) {
+            process.stdout.write(`  ${redact(r.output).split("\n").join("\n  ")}\n`);
         }
-        else if (r.ok) {
-            process.stdout.write(`${step}: ok\n`);
-            if (verbose && r.output) {
-                process.stdout.write(`  ${redact(r.output).split("\n").join("\n  ")}\n`);
+    }
+    else {
+        process.stderr.write(`${step}: failed — ${redact(r.error ?? "")}\n`);
+        if (verbose)
+            process.stderr.write(`  command: ${cmd}\n`);
+    }
+}
+/** Shared error when every skill step failed identically; otherwise undefined. */
+function identicalSkillFailure(skillEntries) {
+    if (skillEntries.length < 2)
+        return undefined;
+    const error = skillEntries[0]?.[1].error;
+    if (!error)
+        return undefined;
+    const allSame = skillEntries.every(([, r]) => !r.ok && !r.skipped && r.error === error);
+    return allSame ? error : undefined;
+}
+/** Collapse identical skill failures to one `skills:` line (missing npx, old npm, …). */
+function printHumanSteps(results, redact, verbose, mcpName) {
+    const entries = Object.entries(results);
+    const skillEntries = entries.filter(([step]) => step.startsWith("skill:"));
+    const sharedError = identicalSkillFailure(skillEntries);
+    if (sharedError !== undefined) {
+        process.stderr.write(`skills: failed — ${redact(sharedError)}\n`);
+        if (verbose) {
+            for (const [step, r] of skillEntries) {
+                process.stderr.write(`  ${step}: ${redact(r.command.join(" "))}\n`);
             }
         }
-        else {
-            process.stderr.write(`${step}: failed — ${redact(r.error ?? "")}\n`);
-            if (verbose)
-                process.stderr.write(`  command: ${cmd}\n`);
+    }
+    else {
+        for (const [step, r] of skillEntries) {
+            printOneHumanStep(step, r, redact, verbose, mcpName);
         }
     }
+    for (const [step, r] of entries) {
+        if (step.startsWith("skill:"))
+            continue;
+        printOneHumanStep(step, r, redact, verbose, mcpName);
+    }
 }
 function printSuccessFooter(steps, signedIn) {
     process.stdout.write(`\nDone — ${steps.join(" and ")} ready.\n` +
@@ -187,11 +273,18 @@ export async function runInstall(args, opts, help = false) {
     if (target === "skill" || target === "all") {
         if (human)
             process.stdout.write("Installing skills…\n");
+        const toolingError = dryRun ? undefined : probeSkillTooling(run);
         for (const skill of SKILL_NAMES) {
             const command = skillCommand(skill);
-            results[`skill:${skill}`] = dryRun
-                ? { command, ok: true, skipped: "dry-run" }
-                : runStep(run, command);
+            if (dryRun) {
+                results[`skill:${skill}`] = { command, ok: true, skipped: "dry-run" };
+            }
+            else if (toolingError) {
+                results[`skill:${skill}`] = { command, ok: false, error: toolingError };
+            }
+            else {
+                results[`skill:${skill}`] = runStep(run, command);
+            }
         }
     }
     if (target === "mcp" || target === "all") {
@@ -264,14 +357,26 @@ export async function runInstall(args, opts, help = false) {
         printSuccessFooter(stepLabels, signedIn);
     }
     else if (failed && !dryRun && skillsOk && results.mcp && !results.mcp.ok) {
-        const next = results.mcp.skipped === "sign-in"
-            ? "Sign in with `uploads login`, then re-run `uploads install mcp`."
-            : "Fix the MCP step above, then re-run `uploads install mcp`.";
+        let next;
+        if (results.mcp.skipped === "sign-in") {
+            next = "Sign in with `uploads login`, then re-run `uploads install mcp`.";
+        }
+        else if (results.mcp.error?.includes("not found on PATH")) {
+            next = "Install the Claude Code CLI (or skip MCP), then re-run `uploads install mcp`.";
+        }
+        else {
+            next = "Fix the MCP step above, then re-run `uploads install mcp`.";
+        }
         process.stdout.write(`\nSkills are installed. ${next}\n`);
     }
     else if (failed && !dryRun && skillsFailed) {
-        // Mixed or total skill failure used to print only per-step lines (#191).
-        process.stdout.write("\nSkill install incomplete. Fix the errors above, then re-run `uploads install skill`.\n");
+        // Closing guidance when skills fail (issue #191: used to be per-step only).
+        const skillErrText = skillResults.map((r) => r.error ?? "").join("\n");
+        const toolingMissing = /npx not found|npm not found|too old for skill install/i.test(skillErrText);
+        process.stdout.write(toolingMissing
+            ? "\nSkill install needs a working Node.js toolchain (npx + npm 7+ on PATH). " +
+                "Fix that, then re-run `uploads install skill`.\n"
+            : "\nSkill install incomplete. Fix the errors above, then re-run `uploads install skill`.\n");
     }
     return failed ? 1 : 0;
 }

package/dist/commands.js

@@ -12,7 +12,7 @@ import { imageFactsFromBytes } from "./image-facts.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
 import { mergeSidecarMeta } from "./sidecar.js";
-import { ghAttachmentKey, ghBranchAttachmentKey, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, parseGhKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, normalizeGithubCoordinate, } from "./github.js";
+import { ghAttachmentKey, ghBranchAttachmentKey, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, parseGhKey, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, GH_FALLBACK_AUTHOR_NOTE, 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";
@@ -543,7 +543,9 @@ export async function syncAttachmentsComment(client, target, run, workspace, opt
         }
     }));
     const marker = attachmentsMarker(workspace);
-    const body = attachmentsCommentBody(items, previewGalleries, marker);
+    // Append only on the local-gh path: bot posts already carry the uploads-sh
+    // bot identity, so this note would be wrong there.
+    const body = `${attachmentsCommentBody(items, previewGalleries, marker)}\n${GH_FALLBACK_AUTHOR_NOTE}`;
     const count = items.length + previewGalleries.length;
     // Empty (count 0) renders the neutral empty-state body but must not create a
     // comment — it only rewrites one that already exists (`action: "skipped"`

package/dist/github-gh.js

@@ -2,7 +2,26 @@ import { execFileSync } from "node:child_process";
 import { UsageError } from "./cli-args.js";
 import { ATTACHMENTS_MARKER, ghMetadataFromTarget, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
 import { META_VALUE_MAX, isMetaValueSafe } from "./metadata.js";
-export const execRunner = (cmd, args, input) => execFileSync(cmd, args, { encoding: "utf8", input, stdio: ["pipe", "pipe", "pipe"] });
+/**
+ * Windows npm shims are `.cmd`/`.bat`; bare `execFileSync` ENOENTs them.
+ * Retry once with `shell: true` so PATHEXT resolves the shim. Other platforms
+ * and non-ENOENT errors stay on the no-shell path. Args are from our CLI, not
+ * free-form shell strings.
+ */
+function execFileSyncCompat(cmd, args, opts) {
+    try {
+        return execFileSync(cmd, args, opts);
+    }
+    catch (err) {
+        const isWinShim = process.platform === "win32" &&
+            err.code === "ENOENT" &&
+            !/\.(cmd|bat|exe|com)$/i.test(cmd);
+        if (isWinShim)
+            return execFileSync(cmd, args, { ...opts, shell: true });
+        throw err;
+    }
+}
+export const execRunner = (cmd, args, input) => execFileSyncCompat(cmd, args, { encoding: "utf8", input, stdio: ["pipe", "pipe", "pipe"] });
 /**
  * A `CommandRunner` bounded by `timeoutMs` (node's native `execFileSync`
  * `timeout` option). There is no other subprocess-timeout wrapper in this
@@ -10,7 +29,7 @@ export const execRunner = (cmd, args, input) => execFileSync(cmd, args, { encodi
  * that must never block its caller for long (e.g. the bare-`put` nudge's `gh
  * pr view` check, issue #393), pass this instead of the default `execRunner`.
  */
-export const timedExecRunner = (timeoutMs) => (cmd, args, input) => execFileSync(cmd, args, {
+export const timedExecRunner = (timeoutMs) => (cmd, args, input) => execFileSyncCompat(cmd, args, {
     encoding: "utf8",
     input,
     stdio: ["pipe", "pipe", "pipe"],

package/dist/github.d.ts

@@ -138,3 +138,8 @@ export declare const ATTACHMENT_IMAGE_WIDTH_PAIR = 320;
  * intentionally preserves the legacy attachment-only body byte-for-byte.
  */
 export declare function attachmentsCommentBody(items: AttachmentItem[], galleries?: GalleryCommentItem[], marker?: string): string;
+/**
+ * Extra footer line appended only on the local-`gh` fallback path (never on
+ * bot-authored comments). Short note that the App isn't on this repo yet.
+ */
+export declare const GH_FALLBACK_AUTHOR_NOTE = "<sub><a href=\"https://github.com/apps/uploads-sh\">Install the uploads GitHub App</a> for bot-managed comments.</sub>";

package/dist/github.js

@@ -506,3 +506,8 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
     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");
 }
+/**
+ * Extra footer line appended only on the local-`gh` fallback path (never on
+ * bot-authored comments). Short note that the App isn't on this repo yet.
+ */
+export const GH_FALLBACK_AUTHOR_NOTE = '<sub><a href="https://github.com/apps/uploads-sh">Install the uploads GitHub App</a> for bot-managed comments.</sub>';

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { UploadsError, type UploadsErrorCode } from "./errors.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 GetMetadataResult, type PatchMetadataOptions, } 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, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } 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

@@ -7,7 +7,7 @@ export { UploadsError } from "./errors.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, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, GH_FALLBACK_AUTHOR_NOTE, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
 export { DEFAULT_OPTIMIZE_MAX_EDGE, DEFAULT_OPTIMIZE_QUALITY, optimizeImageForUpload, rewriteKeyExtension, withImageExtension, } from "./optimize.js";
 export { FRAME_PRESETS, applyFrame, listFramePresets, resolveFrameId, } from "./frame.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, } from "./github-gh.js";

package/package.json

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