@buildinternet/uploads 0.28.0 → 0.29.0

package/README.md

@@ -175,7 +175,7 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 Or with `UPLOADS_TOKEN`/`UPLOADS_WORKSPACE` in the environment or user config. Claude Code: `claude mcp add uploads -- uploads --env-file /path/to/.env mcp`.
 
-For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations (including `get_metadata` / `set_metadata` / `find_files`) plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. The hosted `put` also accepts a `metadata` param. `uploads install` registers the skills + hosted MCP (short progress; `--verbose` for underlying output). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
+For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations (including `get_metadata` / `set_metadata` / `find_files`) plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. The hosted `put` also accepts a `metadata` param. `uploads install` registers the skills + hosted MCP + Grok/Cursor hooks (short progress; `--verbose` for underlying output). Claude and Codex use their plugins for the same pre-PR screenshot reminder (`uploads hook pre-pr-screenshot`). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
 
 ## Programmatic use
 

package/dist/cli-catalog.js

@@ -180,12 +180,23 @@ export const ROOT_COMMANDS = [
     { name: "setup", summary: "Inspect/configure advanced CLI settings" },
     {
         name: "install",
-        summary: "Install the agent skills + register the remote MCP server",
+        summary: "Install agent skills, remote MCP, and harness hooks",
         essential: true,
         subcommands: [
             { name: "skill", summary: "Install the agent skills only" },
             { name: "mcp", summary: "Register the remote MCP server only" },
-            { name: "all", summary: "Install skills and MCP (default)" },
+            { name: "hooks", summary: "Install PR screenshot hooks for Grok/Cursor" },
+            { name: "all", summary: "Install skills, MCP, and hooks (default)" },
+        ],
+    },
+    {
+        name: "hook",
+        summary: "Agent harness hook handlers (stdin → advisory JSON)",
+        subcommands: [
+            {
+                name: "pre-pr-screenshot",
+                summary: "Remind to stage screenshots before gh pr create",
+            },
         ],
     },
     {

package/dist/cli-help.js

@@ -6,10 +6,18 @@ const CMD_WIDTH = 22;
 function toRow(c) {
     return [c.usage ?? c.name, c.summary];
 }
-/** Preferred order for the short essentials help (subset of ROOT_COMMANDS). */
+/**
+ * Display order for the short essentials help. Membership is *not* declared
+ * here — it comes from `essential: true` in cli-catalog.ts, the one source of
+ * truth (issue #491: this array used to decide membership too, and had already
+ * drifted, silently keeping `screenshot` out of short help). This list only
+ * says what order the essential commands appear in; the check below fails the
+ * build-time module load if the two ever disagree in either direction.
+ */
 const ESSENTIAL_ORDER = [
     "put",
     "attach",
+    "screenshot",
     "login",
     "whoami",
     "list",
@@ -19,12 +27,23 @@ const ESSENTIAL_ORDER = [
     "update",
 ];
 /** Day-to-day commands shown on bare `uploads` / `uploads help`. */
-const ESSENTIALS = ESSENTIAL_ORDER.map((name) => {
-    const cmd = ROOT_COMMANDS.find((c) => c.name === name);
-    if (!cmd)
-        throw new Error(`cli-catalog missing essential command: ${name}`);
-    return toRow(cmd);
-});
+const ESSENTIALS = (() => {
+    const essential = ROOT_COMMANDS.filter((c) => c.essential);
+    const rank = new Map(ESSENTIAL_ORDER.map((name, i) => [name, i]));
+    const unordered = essential.filter((c) => !rank.has(c.name));
+    if (unordered.length > 0) {
+        throw new Error(`cli-help ESSENTIAL_ORDER missing essential command(s): ${unordered.map((c) => c.name).join(", ")}`);
+    }
+    const names = new Set(essential.map((c) => c.name));
+    const stale = ESSENTIAL_ORDER.filter((name) => !names.has(name));
+    if (stale.length > 0) {
+        throw new Error(`cli-help ESSENTIAL_ORDER names non-essential command(s): ${stale.join(", ")}`);
+    }
+    return essential
+        .slice()
+        .sort((a, b) => rank.get(a.name) - rank.get(b.name))
+        .map(toRow);
+})();
 /** Full catalog (same surface as before, still discoverable via help --all). */
 const ALL_COMMANDS = ROOT_COMMANDS.map(toRow);
 function rows(style, items) {
@@ -148,10 +167,9 @@ ${section(style, "Examples:")}
   ${style.command("uploads logout")}
   ${style.command("uploads --version")}
 
-${section(style, "Agent/MCP:")} ${style.body("`uploads install` sets up the agent skills and the hosted MCP server")}
-${style.body("(https://agents.uploads.sh/mcp, workspace inferred from the token). Run")}
-${style.body("`uploads mcp` for local stdio, or use createUploadsWorkerFileTools()")}
-${style.body("from @buildinternet/uploads/agent on the Worker.")}
+${section(style, "Agent/MCP:")} ${style.body("`uploads install` sets up skills, hosted MCP, and hooks for")}
+${style.body("Grok/Cursor. Claude and Codex use their plugins for the same PR-screenshot")}
+${style.body("hook. Run `uploads mcp` for local stdio.")}
 
 ${style.muted("Tip: uploads help          essentials only")}
 ${style.muted("     uploads help --all    this full listing")}

package/dist/cli.js

@@ -12,6 +12,7 @@ import { runInvite } from "./commands/invite.js";
 import { runAdmin } from "./commands/admin-enrollment.js";
 import { runMcp } from "./commands/mcp.js";
 import { runInstall } from "./commands/install.js";
+import { runHook } from "./commands/hook.js";
 import { runUpdate } from "./commands/update.js";
 import { runCompletion } from "./commands/completion.js";
 import { runLogout, runWhoami } from "./commands/session.js";
@@ -269,6 +270,10 @@ export async function runCli(argv) {
             case "install":
                 code = await runInstall(cmdArgs, { globals: parsed.globals, json }, showHelp);
                 break;
+            case "hook":
+                // Fail-open harness hooks — no token required, no telemetry noise.
+                code = await runHook(cmdArgs, showHelp);
+                break;
             case "update":
                 code = await runUpdate(cmdArgs, { globals: parsed.globals }, showHelp);
                 break;

package/dist/commands/hook.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `uploads hook pre-pr-screenshot` — agent PreToolUse / beforeShellExecution
+ * handler. When the shell command is `gh pr create`, the branch touches UI
+ * files, and nothing is staged on uploads.sh, emit a non-blocking advisory.
+ *
+ * Always fail-open. Disable with UPLOADS_HOOK_DISABLE=1.
+ */
+export type HookDeps = {
+    stdin: string;
+    testFiles?: string;
+    cwd?: string;
+    countStaged?: (branch: string) => Promise<number | null>;
+    isFork?: () => boolean | null;
+    git?: {
+        isRepo: () => boolean;
+        branch: () => string | null;
+        changedFiles: () => string[];
+    };
+};
+/** Claude/Codex: tool_input.command · Grok: toolInput.command · Cursor: command */
+export declare function shellCommandFromHookInput(raw: unknown): string;
+export declare function isCursorHookInput(raw: unknown): boolean;
+export declare function looksLikeGhPrCreate(command: string): boolean;
+export declare function isVisualPath(filePath: string): boolean;
+export declare function anyVisual(files: string[]): boolean;
+export declare function formatAdvisory(message: string, cursor: boolean): string;
+/** Returns advisory JSON, or null when silent. Never throws for product paths. */
+export declare function runPrePrScreenshot(deps: HookDeps): Promise<string | null>;
+export declare function runHook(args: string[], help?: boolean): Promise<number>;

package/dist/commands/hook.js

@@ -0,0 +1,204 @@
+/**
+ * `uploads hook pre-pr-screenshot` — agent PreToolUse / beforeShellExecution
+ * handler. When the shell command is `gh pr create`, the branch touches UI
+ * files, and nothing is staged on uploads.sh, emit a non-blocking advisory.
+ *
+ * Always fail-open. Disable with UPLOADS_HOOK_DISABLE=1.
+ */
+import { execFileSync } from "node:child_process";
+import { createUploadsClient } from "../client.js";
+import { resolveConfig } from "../config.js";
+import { writeCommandHelp } from "../cli-style.js";
+const HOOK_CMD = "pre-pr-screenshot";
+const VISUAL_EXT = /\.(astro|tsx|jsx|vue|svelte|html|css|scss|less)$/i;
+const EMAIL_PATH = /(?:^|\/)email\//i;
+const FIND_TIMEOUT_MS = 5_000;
+const HOOK_HELP = `uploads hook <name> — agent harness hook handlers (stdin JSON → stdout JSON)
+
+Usage:
+  uploads hook pre-pr-screenshot
+
+Invoked by Claude Code / Codex / Grok / Cursor hooks. Never blocks.
+
+  pre-pr-screenshot
+    If the shell command is \`gh pr create\`, the branch touches UI files, and
+    no screenshots are staged for the branch, emit an advisory to stage with
+    \`uploads attach … --branch\`.
+
+Disable with UPLOADS_HOOK_DISABLE=1.
+`;
+/** Claude/Codex: tool_input.command · Grok: toolInput.command · Cursor: command */
+export function shellCommandFromHookInput(raw) {
+    if (!raw || typeof raw !== "object")
+        return "";
+    const o = raw;
+    const toolInput = (o.tool_input ?? o.toolInput);
+    if (toolInput && typeof toolInput.command === "string")
+        return toolInput.command;
+    if (typeof o.command === "string")
+        return o.command;
+    return "";
+}
+export function isCursorHookInput(raw) {
+    if (!raw || typeof raw !== "object")
+        return false;
+    const o = raw;
+    return "conversation_id" in o || "workspace_roots" in o || "cursor_version" in o;
+}
+export function looksLikeGhPrCreate(command) {
+    return command.includes("gh pr create");
+}
+export function isVisualPath(filePath) {
+    return VISUAL_EXT.test(filePath) || EMAIL_PATH.test(filePath);
+}
+export function anyVisual(files) {
+    return files.some(isVisualPath);
+}
+export function formatAdvisory(message, cursor) {
+    if (cursor) {
+        return JSON.stringify({ additional_context: message, agentMessage: message });
+    }
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            additionalContext: message,
+        },
+        systemMessage: message,
+    });
+}
+function runGit(args, cwd, timeoutMs = 5_000) {
+    try {
+        return execFileSync("git", args, {
+            cwd,
+            encoding: "utf8",
+            timeout: timeoutMs,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function defaultGit(cwd) {
+    return {
+        isRepo: () => runGit(["rev-parse", "--is-inside-work-tree"], cwd) === "true",
+        branch: () => {
+            const b = runGit(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+            return !b || b === "HEAD" ? null : b;
+        },
+        changedFiles: () => {
+            const defaultBranch = runGit(["remote", "show", "origin"], cwd, 8_000)
+                .split("\n")
+                .map((l) => l.match(/HEAD branch:\s*(.+)/)?.[1]?.trim())
+                .find(Boolean) || "main";
+            const mergeBase = runGit(["merge-base", `origin/${defaultBranch}`, "HEAD"], cwd) ||
+                runGit(["merge-base", defaultBranch, "HEAD"], cwd);
+            const diff = mergeBase
+                ? runGit(["diff", "--name-only", mergeBase, "HEAD"], cwd)
+                : runGit(["diff", "--name-only", "HEAD"], cwd);
+            return diff ? diff.split("\n").filter(Boolean) : [];
+        },
+    };
+}
+async function defaultCountStaged(branch) {
+    try {
+        const config = resolveConfig({ requireToken: false });
+        if (!config.token)
+            return null;
+        const client = createUploadsClient(config);
+        const result = await Promise.race([
+            client.findFiles({ "gh.branch": branch.toLowerCase() }, { limit: 1 }),
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new Error("find timeout")), FIND_TIMEOUT_MS);
+            }),
+        ]);
+        return Array.isArray(result.items) ? result.items.length : 0;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultIsFork(cwd) {
+    try {
+        const out = execFileSync("gh", ["repo", "view", "--json", "isFork", "-q", ".isFork"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 3_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (out === "true")
+            return true;
+        if (out === "false")
+            return false;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns advisory JSON, or null when silent. Never throws for product paths. */
+export async function runPrePrScreenshot(deps) {
+    if (process.env.UPLOADS_HOOK_DISABLE === "1")
+        return null;
+    let raw;
+    try {
+        raw = deps.stdin.trim() ? JSON.parse(deps.stdin) : null;
+    }
+    catch {
+        return null;
+    }
+    const command = shellCommandFromHookInput(raw);
+    if (!command || !looksLikeGhPrCreate(command))
+        return null;
+    const cwd = deps.cwd ?? process.cwd();
+    const git = deps.git ?? defaultGit(cwd);
+    if (!git.isRepo())
+        return null;
+    const branch = git.branch();
+    if (!branch)
+        return null;
+    const testFiles = deps.testFiles ?? process.env.UPLOADS_HOOK_TEST_FILES;
+    const changed = testFiles ? testFiles.split("\n").filter(Boolean) : git.changedFiles();
+    if (!anyVisual(changed))
+        return null;
+    const staged = await (deps.countStaged ?? defaultCountStaged)(branch);
+    // null = error/unconfigured → fail open; >0 = already staged
+    if (staged === null || staged > 0)
+        return null;
+    const fork = (deps.isFork ?? (() => defaultIsFork(cwd)))();
+    const forkNote = fork === true
+        ? " Note: this looks like a fork branch, so staged screenshots won't auto-promote into the PR comment yet (see issue #317) — attach them manually if you use uploads."
+        : "";
+    const message = `This PR touches UI files (astro/tsx/jsx/vue/svelte/html/css/scss/less or an /email/ path) but no screenshots are staged for branch '${branch}' on uploads.sh. ` +
+        `Consider running \`uploads attach <shot.png> --branch --state after\` (and a --state before if useful) before or after opening the PR — the managed attachments comment assembles from staged files automatically.${forkNote}`;
+    return formatAdvisory(message, isCursorHookInput(raw));
+}
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function runHook(args, help = false) {
+    const name = args[0];
+    if (help || !name || name === "--help" || name === "-h") {
+        writeCommandHelp(HOOK_HELP);
+        return 0;
+    }
+    if (name !== HOOK_CMD) {
+        process.stderr.write(`unknown hook: ${name} (expected ${HOOK_CMD})\n`);
+        return 2;
+    }
+    try {
+        const out = await runPrePrScreenshot({ stdin: await readStdin() });
+        if (out)
+            process.stdout.write(out);
+    }
+    catch {
+        // fail-open
+    }
+    return 0;
+}

package/dist/commands/install.d.ts

@@ -13,4 +13,6 @@ export declare function runInstall(args: string[], opts: {
     globals: GlobalFlags;
     json?: boolean;
     runner?: CommandRunner;
+    /** Override home for hook installs (tests). */
+    home?: string;
 }, help?: boolean): Promise<number>;

package/dist/commands/install.js

@@ -2,28 +2,35 @@ import { flagBool, flagString, parseCommandArgs, UsageError, } from "../cli-args
 import { resolveConfig } from "../config.js";
 import { execRunner } from "../github-gh.js";
 import { writeCommandHelp } from "../cli-style.js";
+import { HOOK_COMMAND, installHookManifests } from "../hooks-install.js";
 export const DEFAULT_MCP_URL = "https://agents.uploads.sh/mcp";
 const SKILL_SOURCE = "buildinternet/uploads";
 const SKILL_NAMES = ["uploads-cli", "github-screenshots"];
-const INSTALL_HELP = `uploads install — set up agent integrations (skills + remote MCP)
+const INSTALL_HELP = `uploads install — set up agent integrations (skills + remote MCP + hooks)
 
-Installs the github-screenshots and uploads-cli agent skills and registers
-the hosted MCP server with Claude Code. The remote MCP endpoint infers your
-workspace from the bearer token, so only the token is needed.
+Installs the github-screenshots and uploads-cli agent skills, registers the
+hosted MCP server with Claude Code, and installs the PR screenshot reminder
+hook for Grok / Cursor when those tools are present. The remote MCP endpoint
+infers your workspace from the bearer token, so only the token is needed.
+
+Claude Code and Codex ship the same reminder via their plugins (same command:
+\`${HOOK_COMMAND}\`) — install those plugins instead of relying on this step.
 
 Usage:
-  uploads install [skill|mcp|all]     (default: all)
+  uploads install [skill|mcp|hooks|all]     (default: all)
 
 What it does:
   skill   Agent skills (via npx skills) — github-screenshots: visuals into
           PRs/issues; uploads-cli: full CLI reference
   mcp     Hosted MCP server in Claude Code — put, list, attach, galleries
+  hooks   PR screenshot reminder for Grok / Cursor (user-global manifests)
 
 What runs under the hood:
   skill   npx -y skills add ${SKILL_SOURCE} --skill <name> -g -y -a '*'
           (once per skill: ${SKILL_NAMES.join(", ")})
   mcp     claude mcp add --transport http uploads ${DEFAULT_MCP_URL} \\
             --header "Authorization: Bearer <token>"
+  hooks   write/merge ~/.grok/hooks/… and ~/.cursor/hooks.json when present
 
 Options:
   --url <endpoint>    Remote MCP endpoint (default: ${DEFAULT_MCP_URL})
@@ -35,6 +42,7 @@ Examples:
   uploads install
   uploads install skill
   uploads install mcp
+  uploads install hooks
   uploads install --dry-run
 `;
 /** Mask Bearer credentials and the configured token in any printed text. */
@@ -123,6 +131,18 @@ function printSuccessFooter(steps, signedIn) {
         process.stdout.write("\nNot signed in yet? Run `uploads login` once so put/attach/MCP can authenticate.\n");
     }
 }
+function printHookResults(writes) {
+    if (writes.length === 0) {
+        process.stdout.write("hooks: nothing to do (no ~/.grok or ~/.cursor; Claude/Codex use their plugins)\n");
+        return;
+    }
+    for (const w of writes) {
+        if (w.error)
+            process.stderr.write(`hooks:${w.path}: skipped — ${w.error}\n`);
+        else
+            process.stdout.write(`hooks:${w.path}: ${w.action}\n`);
+    }
+}
 export async function runInstall(args, opts, help = false) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
@@ -130,8 +150,8 @@ export async function runInstall(args, opts, help = false) {
         return 0;
     }
     const target = parsed.positionals[0] ?? "all";
-    if (!["skill", "mcp", "all"].includes(target)) {
-        throw new UsageError(`unknown install target: ${target} (expected skill, mcp, or all)`);
+    if (!["skill", "mcp", "hooks", "all"].includes(target)) {
+        throw new UsageError(`unknown install target: ${target} (expected skill, mcp, hooks, or all)`);
     }
     const url = flagString(parsed.flags, "--url") ?? DEFAULT_MCP_URL;
     const name = flagString(parsed.flags, "--name") ?? "uploads";
@@ -143,6 +163,7 @@ export async function runInstall(args, opts, help = false) {
     const signedIn = Boolean(token);
     const redact = redactor(token);
     const results = {};
+    let hookWrites = [];
     if (target === "skill" || target === "all") {
         if (human)
             process.stdout.write("Installing skills…\n");
@@ -169,6 +190,22 @@ export async function runInstall(args, opts, help = false) {
             results.mcp = dryRun ? { command, ok: true, skipped: "dry-run" } : runStep(run, command);
         }
     }
+    if (target === "hooks" || target === "all") {
+        if (human)
+            process.stdout.write("Installing agent hooks…\n");
+        hookWrites = installHookManifests({ home: opts.home, dryRun });
+        // Surface as a synthetic step so --json / failure accounting stay simple.
+        const hookErrors = hookWrites.filter((w) => w.error);
+        results.hooks = {
+            command: [HOOK_COMMAND],
+            ok: hookErrors.length === 0,
+            skipped: dryRun ? "dry-run" : undefined,
+            output: hookWrites
+                .map((w) => `${w.path}: ${w.action}${w.error ? ` (${w.error})` : ""}`)
+                .join("\n"),
+            error: hookErrors.length > 0 ? hookErrors.map((w) => w.error).join("; ") : undefined,
+        };
+    }
     const failed = Object.values(results).some((r) => !r.ok);
     if (opts.json) {
         const steps = Object.fromEntries(Object.entries(results).map(([key, r]) => [
@@ -185,6 +222,11 @@ export async function runInstall(args, opts, help = false) {
         return failed ? 1 : 0;
     }
     printHumanSteps(results, redact, verbose);
+    // Path-level detail for hooks (printHumanSteps only shows the synthetic step).
+    if ((target === "hooks" || target === "all") &&
+        (dryRun || (human && (verbose || hookWrites.some((w) => w.action !== "skipped"))))) {
+        printHookResults(hookWrites);
+    }
     const skillResults = Object.entries(results)
         .filter(([step]) => step.startsWith("skill:"))
         .map(([, r]) => r);

package/dist/hooks-install.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Install thin user-global hook manifests for Grok and Cursor.
+ *
+ * Claude and Codex ship the same PreToolUse hook via their plugins
+ * (`hooks/hooks.json` → `uploads hook pre-pr-screenshot`). Do not also write
+ * ~/.codex/hooks.json here, or the reminder would fire twice.
+ *
+ * Idempotent: skip when our command string is already present.
+ */
+export declare const HOOK_COMMAND = "uploads hook pre-pr-screenshot";
+export type HookWriteResult = {
+    path: string;
+    action: "wrote" | "merged" | "skipped" | "would-write" | "would-merge";
+    error?: string;
+};
+export type InstallHooksOptions = {
+    home?: string;
+    dryRun?: boolean;
+    targets?: Array<"grok" | "cursor">;
+};
+/** User-global manifests for Grok + Cursor only. */
+export declare function installHookManifests(opts?: InstallHooksOptions): HookWriteResult[];

package/dist/hooks-install.js

@@ -0,0 +1,112 @@
+/**
+ * Install thin user-global hook manifests for Grok and Cursor.
+ *
+ * Claude and Codex ship the same PreToolUse hook via their plugins
+ * (`hooks/hooks.json` → `uploads hook pre-pr-screenshot`). Do not also write
+ * ~/.codex/hooks.json here, or the reminder would fire twice.
+ *
+ * Idempotent: skip when our command string is already present.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const HOOK_COMMAND = "uploads hook pre-pr-screenshot";
+const TIMEOUT_SEC = 15;
+const GROK_PAYLOAD = {
+    description: "Advisory reminder to stage screenshots on uploads.sh before opening a PR that touches UI files.",
+    hooks: {
+        PreToolUse: [
+            {
+                matcher: "Bash",
+                hooks: [
+                    {
+                        type: "command",
+                        command: HOOK_COMMAND,
+                        timeout: TIMEOUT_SEC,
+                        statusMessage: "Checking staged screenshots",
+                    },
+                ],
+            },
+        ],
+    },
+};
+function containsCommand(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf8").includes(HOOK_COMMAND);
+    }
+    catch {
+        return false;
+    }
+}
+function writeJson(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+function commit(filePath, next, dryRun, existed) {
+    if (containsCommand(filePath))
+        return { path: filePath, action: "skipped" };
+    if (dryRun) {
+        return { path: filePath, action: existed ? "would-merge" : "would-write" };
+    }
+    writeJson(filePath, next);
+    return { path: filePath, action: existed ? "merged" : "wrote" };
+}
+function writeGrok(home, dryRun) {
+    const filePath = path.join(home, ".grok", "hooks", "uploads-pre-pr-screenshot.json");
+    return commit(filePath, GROK_PAYLOAD, dryRun, fs.existsSync(filePath));
+}
+function mergeCursor(home, dryRun) {
+    const filePath = path.join(home, ".cursor", "hooks.json");
+    const existed = fs.existsSync(filePath);
+    let existing = { version: 1, hooks: {} };
+    if (existed) {
+        try {
+            const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+            if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+                return { path: filePath, action: "skipped", error: "hooks.json is not an object" };
+            }
+            existing = raw;
+        }
+        catch (err) {
+            return {
+                path: filePath,
+                action: "skipped",
+                error: `could not parse existing hooks.json: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    const hooks = existing.hooks && typeof existing.hooks === "object"
+        ? { ...existing.hooks }
+        : {};
+    const list = Array.isArray(hooks.beforeShellExecution) ? [...hooks.beforeShellExecution] : [];
+    list.push({ command: HOOK_COMMAND, timeout: TIMEOUT_SEC });
+    hooks.beforeShellExecution = list;
+    existing.hooks = hooks;
+    if (existing.version === undefined)
+        existing.version = 1;
+    return commit(filePath, existing, dryRun, existed);
+}
+/** User-global manifests for Grok + Cursor only. */
+export function installHookManifests(opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const dryRun = Boolean(opts.dryRun);
+    const targets = opts.targets ??
+        [
+            fs.existsSync(path.join(home, ".grok")) && "grok",
+            fs.existsSync(path.join(home, ".cursor")) && "cursor",
+        ].filter(Boolean);
+    const results = [];
+    for (const t of targets) {
+        try {
+            results.push(t === "grok" ? writeGrok(home, dryRun) : mergeCursor(home, dryRun));
+        }
+        catch (err) {
+            results.push({
+                path: t,
+                action: "skipped",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return results;
+}

package/dist/telemetry.js

@@ -28,6 +28,7 @@ const NESTED_COMMANDS = new Set([
     "completions",
     "config",
     "gallery",
+    "hook",
     "install",
     "meta",
     "telemetry",

package/package.json

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