@buildinternet/uploads 0.1.0 → 0.2.0

package/dist/commands/install.js

@@ -0,0 +1,133 @@
+import { flagBool, flagString, parseCommandArgs, UsageError, } from "../cli-args.js";
+import { resolveConfig } from "../config.js";
+import { execRunner } from "../github-gh.js";
+export const DEFAULT_MCP_URL = "https://agents.uploads.sh/mcp";
+const SKILL_SOURCE = "buildinternet/uploads";
+const SKILL_NAME = "uploads-cli";
+const INSTALL_HELP = `uploads install — set up agent integrations (skill + remote MCP)
+
+Installs the uploads-cli agent skill 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.
+
+Usage:
+  uploads install [skill|mcp|all]     (default: all)
+
+What runs:
+  skill   npx -y skills add ${SKILL_SOURCE} --skill ${SKILL_NAME}
+  mcp     claude mcp add --transport http uploads ${DEFAULT_MCP_URL} \\
+            --header "Authorization: Bearer <token>"
+
+Options:
+  --url <endpoint>    Remote MCP endpoint (default: ${DEFAULT_MCP_URL})
+  --name <name>       MCP server name in the client (default: uploads)
+  --dry-run           Print the commands without running them
+
+Examples:
+  uploads install
+  uploads install skill
+  uploads install mcp --dry-run
+`;
+/**
+ * Masks the configured token (and any Bearer credential) in text destined
+ * for stdout/stderr/JSON — command echoes, child-process output, and error
+ * messages can all embed it.
+ */
+function redactor(token) {
+    return (text) => {
+        let out = text.replace(/Bearer \S+/g, "Bearer ***");
+        if (token)
+            out = out.split(token).join("***");
+        return out;
+    };
+}
+function runStep(run, command) {
+    try {
+        const output = run(command[0], command.slice(1)).trim();
+        return { command, ok: true, output: output || undefined };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // execFileSync's ENOENT means the binary itself is missing.
+        const hint = err.code === "ENOENT"
+            ? `${command[0]} not found on PATH — run manually: ${command.join(" ")}`
+            : message;
+        return { command, ok: false, error: hint };
+    }
+}
+export async function runInstall(args, opts, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        process.stderr.write(INSTALL_HELP);
+        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)`);
+    }
+    const url = flagString(parsed.flags, "--url") ?? DEFAULT_MCP_URL;
+    const name = flagString(parsed.flags, "--name") ?? "uploads";
+    const dryRun = flagBool(parsed.flags, "--dry-run");
+    const run = opts.runner ?? execRunner;
+    const results = {};
+    let redact = redactor(undefined);
+    if (target === "skill" || target === "all") {
+        const command = ["npx", "-y", "skills", "add", SKILL_SOURCE, "--skill", SKILL_NAME];
+        results.skill = dryRun ? { command, ok: true, skipped: "dry-run" } : runStep(run, command);
+    }
+    if (target === "mcp" || target === "all") {
+        const config = resolveConfig({
+            apiUrl: opts.globals.apiUrl,
+            workspace: opts.globals.workspace,
+            token: opts.globals.token,
+            envFile: opts.globals.envFile,
+            requireToken: !dryRun,
+        });
+        const bearer = config.token || "<token>";
+        redact = redactor(config.token || undefined);
+        const command = [
+            "claude",
+            "mcp",
+            "add",
+            "--transport",
+            "http",
+            name,
+            url,
+            "--header",
+            `Authorization: Bearer ${bearer}`,
+        ];
+        results.mcp = dryRun ? { command, ok: true, skipped: "dry-run" } : runStep(run, command);
+    }
+    const failed = Object.values(results).some((r) => !r.ok);
+    if (opts.json) {
+        // Never echo the token in structured output — commands, child output,
+        // and error text can all embed it.
+        const redacted = Object.fromEntries(Object.entries(results).map(([key, r]) => [
+            key,
+            {
+                ...r,
+                command: r.command.map(redact),
+                output: r.output === undefined ? undefined : redact(r.output),
+                error: r.error === undefined ? undefined : redact(r.error),
+            },
+        ]));
+        process.stdout.write(JSON.stringify({ ok: !failed, steps: redacted }, null, 2) + "\n");
+        return failed ? 1 : 0;
+    }
+    for (const [step, r] of Object.entries(results)) {
+        const shown = redact(r.command.join(" "));
+        if (r.skipped)
+            process.stdout.write(`${step}: would run — ${shown}\n`);
+        else if (r.ok) {
+            process.stdout.write(`${step}: ok — ${shown}\n`);
+            if (r.output)
+                process.stdout.write(`  ${redact(r.output).split("\n").join("\n  ")}\n`);
+        }
+        else
+            process.stderr.write(`${step}: failed — ${redact(r.error ?? "")}\n`);
+    }
+    if (!failed && !dryRun) {
+        process.stderr.write("hint: restart your agent session to pick up the new skill/server\n");
+    }
+    return failed ? 1 : 0;
+}

package/dist/commands/login.d.ts

@@ -0,0 +1,11 @@
+import { parseCommandArgs } from "../cli-args.js";
+export declare function validateEnrollmentCode(raw: string): string;
+export declare function resolveEnrollmentCode(parsed: ReturnType<typeof parseCommandArgs>, io?: {
+    isTTY: boolean;
+    readLine: () => Promise<string>;
+    hiddenPrompt: () => Promise<string>;
+}): Promise<string>;
+export declare function runLogin(args: string[], opts: {
+    json?: boolean;
+    apiUrl?: string;
+}, help?: boolean): Promise<number>;

package/dist/commands/login.js

@@ -0,0 +1,160 @@
+import { stdin, stdout } from "node:process";
+import { loadConfigFile, redactToken, resolveConfigPath, writeConfigKeys, workspaceFromToken, } from "../config.js";
+import { exchangeEnrollment, createUploadsClient } from "../client.js";
+import { flagBool, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+const HELP = `uploads login [options]
+
+Exchange a one-time enrollment code for workspace credentials, save them, and
+verify access. Ask your uploads.sh administrator for an enrollment code.
+
+Options:
+  --code <code>       Code in argv (may be visible in shell history/process lists)
+  --code-stdin        Read one line from stdin
+  --non-interactive   Never prompt
+  --api-url <url>     API base (default: https://api.uploads.sh)
+  --path <file>       Config destination
+  --force             Replace existing saved credentials
+  --no-check          Skip doctor verification
+`;
+export function validateEnrollmentCode(raw) {
+    const code = raw.trim();
+    if (!/^upe_[A-Za-z0-9_-]{20,}$/.test(code))
+        throw new UsageError("invalid enrollment code");
+    return code;
+}
+async function readLine() {
+    let out = "";
+    for await (const chunk of stdin) {
+        out += String(chunk);
+        if (out.includes("\n"))
+            break;
+    }
+    return out.split(/\r?\n/, 1)[0] ?? "";
+}
+async function hiddenPrompt() {
+    if (!stdin.isTTY || typeof stdin.setRawMode !== "function")
+        return readLine();
+    stdout.write("Enrollment code: ");
+    stdin.setRawMode(true);
+    stdin.resume();
+    return new Promise((resolve, reject) => {
+        let value = "";
+        let settled = false;
+        const done = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            stdin.off("data", onData);
+            stdin.off("error", onError);
+            try {
+                stdin.setRawMode(false);
+            }
+            finally {
+                stdin.pause();
+                stdout.write("\n");
+            }
+            if (err)
+                reject(err);
+            else
+                resolve(value);
+        };
+        const onData = (chunk) => {
+            for (const char of chunk.toString("utf8")) {
+                if (char === "\r" || char === "\n")
+                    return done();
+                if (char === "\u0003")
+                    return done(new UsageError("login cancelled"));
+                if (char === "\u007f")
+                    value = value.slice(0, -1);
+                else
+                    value += char;
+            }
+        };
+        const onError = (err) => done(err);
+        stdin.on("data", onData);
+        stdin.on("error", onError);
+    });
+}
+export async function resolveEnrollmentCode(parsed, io = {
+    isTTY: Boolean(stdin.isTTY),
+    readLine,
+    hiddenPrompt,
+}) {
+    const direct = flagString(parsed.flags, "--code");
+    const env = process.env.UPLOADS_ENROLLMENT_CODE;
+    const fromStdin = flagBool(parsed.flags, "--code-stdin");
+    const sources = [Boolean(direct), Boolean(env), fromStdin].filter(Boolean).length;
+    if (sources > 1)
+        throw new UsageError("provide enrollment code through only one source");
+    if (direct)
+        return validateEnrollmentCode(direct);
+    if (env)
+        return validateEnrollmentCode(env);
+    if (fromStdin)
+        return validateEnrollmentCode(await io.readLine());
+    if (flagBool(parsed.flags, "--non-interactive"))
+        throw new UsageError("enrollment code required in non-interactive mode");
+    if (!io.isTTY)
+        return validateEnrollmentCode(await io.readLine());
+    return validateEnrollmentCode(await io.hiddenPrompt());
+}
+export async function runLogin(args, opts, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        process.stderr.write(HELP);
+        return 0;
+    }
+    const apiUrl = flagString(parsed.flags, "--api-url") ?? opts.apiUrl ?? "https://api.uploads.sh";
+    const path = flagString(parsed.flags, "--path") ?? resolveConfigPath();
+    const force = flagBool(parsed.flags, "--force");
+    const existing = loadConfigFile(path);
+    if (existing.UPLOADS_TOKEN && !force)
+        throw new UsageError(`credentials already exist in ${path}; use --force to replace them`);
+    if (process.env.UPLOADS_TOKEN && !force)
+        throw new UsageError("UPLOADS_TOKEN is already set in the environment; unset it or use --force");
+    const code = await resolveEnrollmentCode(parsed);
+    const result = await exchangeEnrollment(apiUrl, code);
+    const encoded = workspaceFromToken(result.token);
+    if (!encoded || encoded !== result.workspace || /[\r\n]/.test(result.token))
+        throw new UsageError("enrollment returned invalid credentials");
+    const savedApiUrl = result.apiUrl ?? apiUrl;
+    const write = writeConfigKeys(path, {
+        UPLOADS_API_URL: savedApiUrl,
+        UPLOADS_WORKSPACE: result.workspace,
+        UPLOADS_TOKEN: result.token,
+    }, { force });
+    if (!["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN"].every((key) => write.updated.includes(key)))
+        throw new UsageError("credentials were not fully written; retry with --force");
+    const checked = !flagBool(parsed.flags, "--no-check");
+    let doctor = { ok: true, error: undefined };
+    if (checked) {
+        try {
+            const client = createUploadsClient({
+                apiUrl: savedApiUrl,
+                workspace: result.workspace,
+                token: result.token,
+            });
+            const health = await client.health();
+            if (!health.ok)
+                throw new Error("API unhealthy");
+            await client.list({ limit: 1 });
+        }
+        catch (err) {
+            doctor = { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    const payload = {
+        ok: doctor.ok,
+        configPath: path,
+        workspace: result.workspace,
+        token: redactToken(result.token),
+        doctor: checked ? doctor : { skipped: true },
+    };
+    if (opts.json)
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    else {
+        process.stdout.write(`saved credentials to ${path}\nworkspace: ${result.workspace}\ntoken: ${redactToken(result.token)}\n`);
+        process[doctor.ok ? "stdout" : "stderr"].write(`doctor: ${checked ? (doctor.ok ? "ok" : `failed — ${doctor.error}`) : "skipped"}\n`);
+    }
+    return doctor.ok ? 0 : 1;
+}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,4 @@
+import { type GlobalFlags } from "../cli-args.js";
+export declare function runMcp(args: string[], opts: {
+    globals: GlobalFlags;
+}, help?: boolean): Promise<number>;

package/dist/commands/mcp.js

@@ -0,0 +1,39 @@
+import { createRequire } from "node:module";
+import { parseCommandArgs } from "../cli-args.js";
+import { createMcpServer } from "../mcp/server.js";
+import { serveStdio } from "../mcp/stdio.js";
+import { createUploadsMcpTools } from "../mcp/tools.js";
+const MCP_HELP = `uploads [globals] mcp
+
+Serve the Model Context Protocol (MCP) over stdio for agent clients. Tools
+mirror the CLI commands: put, attach, list, delete, usage, reconcile,
+purge_expired, comment, health, doctor.
+Global flags before "mcp" (--api-url, --token, --workspace, --env-file)
+configure every tool call; a per-call "workspace" argument overrides
+--workspace, like the CLI's per-command flag.
+
+Example MCP client config:
+  {
+    "command": "uploads",
+    "args": ["--env-file", "/path/.env", "mcp"]
+  }
+
+Examples:
+  uploads --env-file .env mcp
+  uploads --token up_default_… mcp
+`;
+// Same relative depth from src/commands/ and dist/commands/, so this works
+// both under vitest (src) and at runtime (dist).
+const { version } = createRequire(import.meta.url)("../../package.json");
+export async function runMcp(args, opts, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(MCP_HELP);
+        return 0;
+    }
+    const server = createMcpServer({
+        serverInfo: { name: "uploads", version },
+        tools: createUploadsMcpTools({ globals: opts.globals }),
+    });
+    await serveStdio(server);
+    return 0;
+}

package/dist/commands/setup.js

@@ -13,7 +13,7 @@ With flags: saves provided values, then optionally verifies with doctor.
 Options:
   --api-url <url>       API base (default: ${DEFAULT_API_URL})
   --workspace, -w <name>
-  --token <token>       Bearer token (mint via admin endpoint — see below)
+  --token <token>       Existing bearer token (or use uploads login)
   --prefix <path>       Default key prefix for put/list (default: screenshots)
   --repo <owner/repo>   Default repo segment for put
   --ref <id>            Default ref segment for put (PR/issue/branch/date)
@@ -41,15 +41,6 @@ function buildStatus(envFile) {
         sources: describeConfigSources({ envFile }),
     };
 }
-function mintTokenCommand(apiUrl, workspace) {
-    const body = workspace && workspace !== DEFAULT_WORKSPACE
-        ? ` \\\n  -H "Content-Type: application/json" \\\n  -d '{"workspace":"${workspace}","label":"cli"}'`
-        : "";
-    return [
-        `curl -XPOST ${apiUrl}/admin/tokens \\`,
-        `  -H "Authorization: Bearer $ADMIN_TOKEN"${body}`,
-    ].join("\n");
-}
 function formatWizard(status) {
     const lines = ["uploads setup", ""];
     lines.push(`Config file: ${status.configPath}`);
@@ -72,11 +63,10 @@ function formatWizard(status) {
     }
     lines.push("");
     if (!status.token) {
-        lines.push("Step 1 — Mint a token");
-        lines.push("  You need ADMIN_TOKEN for the API (ask your uploads.sh admin, or set it locally in apps/api/.dev.vars).");
-        lines.push("  Mint:");
-        lines.push(`    ${mintTokenCommand(status.apiUrl, status.workspace)}`);
-        lines.push("  Save:");
+        lines.push("Step 1 — Sign in");
+        lines.push("  Ask your uploads.sh administrator for a one-time enrollment code, then run:");
+        lines.push("    uploads login");
+        lines.push("  If you already have a bearer token:");
         lines.push("    uploads setup --token up_<workspace>_…");
         lines.push("");
     }
@@ -217,7 +207,7 @@ export async function runSetup(args, opts, help = false) {
         process.stderr.write("hint: run uploads doctor to verify\n");
     }
     else {
-        process.stderr.write("hint: run uploads setup to see minting instructions\n");
+        process.stderr.write("hint: run uploads login with an admin-provided enrollment code\n");
     }
     return doctorOk === false ? 1 : 0;
 }

package/dist/commands.d.ts

@@ -1,5 +1,6 @@
 import { type UploadsClient } from "./client.js";
 import { type ResolvedConfig } from "./config.js";
+import { type GhTarget } from "./github.js";
 import { type CommandRunner } from "./github-gh.js";
 export interface CliContext {
     config: ResolvedConfig;
@@ -8,12 +9,58 @@ export interface CliContext {
     quiet: boolean;
     envFile?: string;
 }
+/**
+ * Turns a pr/issue pair (+ optional repo) into a GhTarget; undefined when
+ * neither is present. Shared by the CLI flags and the MCP tool arguments.
+ */
+export declare function makeGhTarget(pr: number | undefined, issue: number | undefined, repoArg: string | undefined, run: CommandRunner): GhTarget | undefined;
+/**
+ * List every attachment under the target's prefix and create/update the
+ * managed comment. Throws on gh failure — callers decide whether that is
+ * fatal (`comment` command) or a warning (`put --comment`).
+ */
+export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner): Promise<{
+    action: "created" | "updated" | "skipped";
+    count: number;
+}>;
 export declare function runAttach(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runPut(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runList(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runDelete(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runComment(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
+export declare function runUsage(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
+export declare function runReconcile(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
+export declare function runPurgeExpired(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runHealth(ctx: Pick<CliContext, "json"> & {
     apiUrl: string;
 }, args: string[], help?: boolean): Promise<number>;
+export interface DoctorReport {
+    ok: boolean;
+    apiUrl: string;
+    workspace: string;
+    workspaceSource: ResolvedConfig["workspaceSource"];
+    workspaceFromToken: string | undefined;
+    configPath: string;
+    configExists: boolean;
+    health: {
+        ok: boolean;
+    };
+    auth: {
+        ok: boolean;
+        error: string | undefined;
+    };
+    /** Usage snapshot when auth works (optional fields when the endpoint fails). */
+    usage?: {
+        ok: boolean;
+        bytes?: number;
+        objects?: number;
+        uploadsInPeriod?: number;
+        error?: string;
+    };
+    /** Workspace/token mismatch warning (also present in hints). */
+    warning?: string;
+    hints: string[];
+}
+/** Doctor's health + auth + workspace checks, shared by the CLI and the MCP tool. */
+export declare function buildDoctorReport(config: ResolvedConfig, client: UploadsClient): Promise<DoctorReport>;
 export declare function runDoctor(ctx: CliContext, args: string[], help?: boolean): Promise<number>;