@buildinternet/uploads 0.1.0

package/dist/commands.js

@@ -0,0 +1,451 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { createUploadsClient } from "./client.js";
+import { parseCommandArgs, flagString, flagBool, flagInt, UsageError, } from "./cli-args.js";
+import { resolvePutDefaults, workspaceMismatch, workspaceFromToken, } from "./config.js";
+import { buildMarkdown } from "./embed.js";
+import { UploadsError } from "./errors.js";
+import { ghAttachmentKey, ghKeyPrefix, attachmentsCommentBody, } from "./github.js";
+import { resolveRepo, resolveCurrentPullRequest, execRunner, upsertAttachmentsComment, } from "./github-gh.js";
+async function writeStdout(text) {
+    if (!process.stdout.write(text)) {
+        await new Promise((resolve) => process.stdout.once("drain", resolve));
+    }
+}
+async function writeJson(value) {
+    await writeStdout(JSON.stringify(value, null, 2) + "\n");
+}
+// --- put ---
+const PUT_HELP = `uploads put <file> [options]
+
+Upload an image for GitHub embeds. Use "-" for stdin.
+
+Options:
+  --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>)
+  --prefix <path>       Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX)
+  --repo <owner/repo>   Repo segment (default: git remote, or UPLOADS_DEFAULT_REPO)
+  --ref <id>            PR/issue/branch segment (default: today, or UPLOADS_DEFAULT_REF)
+  --alt <text>          Alt text (default: filename)
+  --width <px>          <img width=…> markdown (or UPLOADS_DEFAULT_WIDTH)
+  --content-type <mime> Override Content-Type
+  --no-git              Don't derive --repo from git (or UPLOADS_NO_GIT=1)
+  --workspace, -w <name>  Override workspace (wins over UPLOADS_WORKSPACE and token inference)
+  --format human|url|markdown|json
+  --pr <num>            Attach to a pull request: key gh/<owner>/<repo>/pull/<num>/<name> (stable URL, no hash)
+  --issue <num>         Attach to an issue: key gh/<owner>/<repo>/issues/<num>/<name>
+  --comment             With --pr/--issue: create/update the attachments comment via your local gh auth
+
+Examples:
+  uploads put ./shot.png --repo myorg/myapp --ref 1722 --alt "New cards" --width 700
+  uploads --env-file .env put ./shot.png
+  uploads --env-file .env put ./after.png --pr 123 --comment
+`;
+/** Reads --pr/--issue (+ --repo) into a GhTarget; undefined when neither flag is present. */
+function ghTargetFromFlags(flags, run) {
+    const pr = flagInt(flags, "--pr", "--pr");
+    const issue = flagInt(flags, "--issue", "--issue");
+    if (pr === undefined && issue === undefined)
+        return undefined;
+    if (pr !== undefined && issue !== undefined) {
+        throw new UsageError("--pr and --issue are mutually exclusive");
+    }
+    const repo = resolveRepo(flagString(flags, "--repo"), run);
+    return { repo, kind: pr !== undefined ? "pull" : "issues", num: (pr ?? issue) };
+}
+/**
+ * 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`).
+ */
+async function syncAttachmentsComment(ctx, target, run) {
+    const items = [];
+    let cursor;
+    do {
+        const page = await ctx.client.list({ prefix: ghKeyPrefix(target), cursor });
+        items.push(...page.items.map(({ key, url }) => ({ key, url })));
+        cursor = page.cursor ?? undefined;
+    } while (cursor);
+    if (items.length === 0)
+        return { action: "skipped", count: 0 };
+    const body = attachmentsCommentBody(items);
+    const { created } = upsertAttachmentsComment(target, body, run);
+    return { action: created ? "created" : "updated", count: items.length };
+}
+// --- attach ---
+const ATTACH_HELP = `uploads attach <file...> [options]
+
+Upload one or more stable PR/issue attachments and maintain a single GitHub
+comment. With no target, uses the pull request for the current branch.
+
+Options:
+  --pr <num>            Attach to this pull request
+  --issue <num>         Attach to this issue
+  --repo <owner/repo>   Repository (default: gh/git inference)
+  --no-comment          Upload only; don't create/update the managed comment
+  --content-type <mime> Override Content-Type (applied to every file)
+  --workspace, -w <name>  Override workspace
+
+Examples:
+  uploads attach ./before.png ./after.png
+  uploads attach ./shot.png --pr 123 --repo myorg/myapp
+  uploads attach ./artifact.zip --issue 45 --no-comment
+`;
+export async function runAttach(ctx, args, help = false, run = execRunner) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        process.stderr.write(ATTACH_HELP);
+        return 0;
+    }
+    if (parsed.positionals.length === 0) {
+        process.stderr.write(ATTACH_HELP);
+        return 2;
+    }
+    if (parsed.flags.has("--no-comment") && typeof parsed.flags.get("--no-comment") === "string") {
+        throw new UsageError("--no-comment takes no value — place it after the file arguments");
+    }
+    const explicitTarget = ghTargetFromFlags(parsed.flags, run);
+    const target = explicitTarget ??
+        resolveCurrentPullRequest(resolveRepo(flagString(parsed.flags, "--repo"), run), run);
+    const results = [];
+    for (const file of parsed.positionals) {
+        if (file === "-")
+            throw new UsageError("attach does not support stdin; pass one or more file paths");
+        const filename = basename(file);
+        if (!ctx.quiet && !ctx.json)
+            process.stderr.write(`>> uploading ${file}\n`);
+        const result = await ctx.client.put(new Uint8Array(readFileSync(file)), {
+            filename,
+            key: ghAttachmentKey(target, filename),
+            contentType: flagString(parsed.flags, "--content-type"),
+        });
+        results.push({ ...result, markdown: buildMarkdown(result.url, { alt: filename }) });
+    }
+    let comment;
+    let commentError;
+    if (!parsed.flags.has("--no-comment")) {
+        try {
+            comment = await syncAttachmentsComment(ctx, target, run);
+        }
+        catch (err) {
+            commentError = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`warning: uploads succeeded but the GitHub comment failed (is gh installed and authenticated?): ${commentError}\n`);
+        }
+    }
+    if (ctx.json) {
+        await writeJson({ target, uploads: results, comment, commentError });
+    }
+    else {
+        for (const result of results) {
+            await writeStdout(`URL: ${result.url}\nMARKDOWN: ${result.markdown}\n`);
+        }
+        if (!ctx.quiet && comment)
+            process.stderr.write(`>> attachments comment ${comment.action}\n`);
+    }
+    return 0;
+}
+export async function runPut(ctx, args, help = false, run = execRunner) {
+    if (help) {
+        process.stderr.write(PUT_HELP);
+        return 0;
+    }
+    const parsed = parseCommandArgs(args);
+    if (parsed.help) {
+        process.stderr.write(PUT_HELP);
+        return 0;
+    }
+    const fileArg = parsed.positionals[0];
+    if (!fileArg) {
+        process.stderr.write(PUT_HELP);
+        return 2;
+    }
+    const keyHint = flagString(parsed.flags, "--key");
+    const ghTarget = ghTargetFromFlags(parsed.flags, run);
+    const wantComment = parsed.flags.has("--comment");
+    if (wantComment && typeof parsed.flags.get("--comment") === "string") {
+        throw new UsageError("--comment takes no value — place it after the file argument");
+    }
+    if (wantComment && !ghTarget)
+        throw new UsageError("--comment requires --pr or --issue");
+    if (ghTarget) {
+        if (keyHint)
+            throw new UsageError("--key cannot be combined with --pr/--issue");
+        if (flagString(parsed.flags, "--ref")) {
+            throw new UsageError("--ref cannot be combined with --pr/--issue");
+        }
+        if (flagString(parsed.flags, "--prefix")) {
+            throw new UsageError("--prefix cannot be combined with --pr/--issue");
+        }
+    }
+    const bytes = fileArg === "-" ? new Uint8Array(readFileSync(0)) : new Uint8Array(readFileSync(fileArg));
+    const filename = fileArg === "-" ? (keyHint ? basename(keyHint) : "stdin.bin") : basename(fileArg);
+    const format = ctx.json
+        ? "json"
+        : (() => {
+            const raw = flagString(parsed.flags, "--format");
+            if (!raw || raw === "human")
+                return "human";
+            if (raw === "url" || raw === "markdown" || raw === "json")
+                return raw;
+            throw new UsageError(`invalid --format: ${raw}`);
+        })();
+    const defaults = resolvePutDefaults({ envFile: ctx.envFile });
+    const alt = flagString(parsed.flags, "--alt") ?? basename(filename);
+    const widthRaw = flagString(parsed.flags, "--width");
+    const width = widthRaw && /^\d+$/.test(widthRaw) && Number(widthRaw) > 0
+        ? Number.parseInt(widthRaw, 10)
+        : widthRaw
+            ? (() => {
+                throw new UsageError(`invalid --width: ${widthRaw}`);
+            })()
+            : defaults.width;
+    if (!ctx.quiet && format === "human") {
+        process.stderr.write(`>> uploading ${fileArg === "-" ? "stdin" : fileArg}\n`);
+    }
+    const noGit = flagBool(parsed.flags, "--no-git") || defaults.noGit === true;
+    const result = await ctx.client.put(bytes, {
+        filename,
+        key: ghTarget ? ghAttachmentKey(ghTarget, filename) : keyHint,
+        prefix: flagString(parsed.flags, "--prefix") ?? defaults.prefix,
+        repo: flagString(parsed.flags, "--repo") ?? defaults.repo,
+        ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
+        contentType: flagString(parsed.flags, "--content-type"),
+        deriveRepoFromGit: !noGit,
+    });
+    const markdown = buildMarkdown(result.url, { alt, width });
+    if (!ctx.quiet && format === "human") {
+        process.stderr.write(`>> key: ${result.key}\n\n`);
+    }
+    switch (format) {
+        case "json":
+            await writeJson({ ...result, markdown });
+            break;
+        case "url":
+            await writeStdout(`${result.url}\n`);
+            break;
+        case "markdown":
+            await writeStdout(`${markdown}\n`);
+            break;
+        default:
+            await writeStdout(`URL: ${result.url}\nMARKDOWN: ${markdown}\n`);
+    }
+    if (wantComment && ghTarget) {
+        try {
+            const sync = await syncAttachmentsComment(ctx, ghTarget, run);
+            if (!ctx.quiet && format === "human") {
+                process.stderr.write(`>> attachments comment ${sync.action}\n`);
+            }
+        }
+        catch (err) {
+            // Upload already succeeded; the comment is best-effort by design.
+            process.stderr.write(`warning: upload succeeded but the GitHub comment failed (is gh installed and authenticated?): ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    return 0;
+}
+// --- list ---
+const LIST_HELP = `uploads list [--prefix <p>] [--pr <num> | --issue <num>] [--repo <owner/name>] [--limit <n>] [--cursor <c>] [--all] [--workspace <name>]
+
+Default prefix: UPLOADS_DEFAULT_PREFIX (screenshots if unset).
+
+Examples:
+  uploads list --prefix screenshots/
+  uploads list --pr 123
+  uploads list --all --json
+`;
+export async function runList(ctx, args, help = false, run = execRunner) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        process.stderr.write(LIST_HELP);
+        return 0;
+    }
+    const defaults = resolvePutDefaults({ envFile: ctx.envFile });
+    const prefixFlag = flagString(parsed.flags, "--prefix");
+    let prefix = prefixFlag ?? (defaults.prefix ? `${defaults.prefix}/` : undefined);
+    const ghTarget = ghTargetFromFlags(parsed.flags, run);
+    if (ghTarget) {
+        if (prefixFlag)
+            throw new UsageError("--prefix cannot be combined with --pr/--issue");
+        prefix = ghKeyPrefix(ghTarget);
+    }
+    const limit = flagInt(parsed.flags, "--limit", "--limit");
+    const cursor = flagString(parsed.flags, "--cursor");
+    if (flagBool(parsed.flags, "--all")) {
+        const items = [];
+        let next = cursor;
+        do {
+            const page = await ctx.client.list({ prefix, limit, cursor: next ?? undefined });
+            items.push(...page.items);
+            next = page.cursor;
+        } while (next);
+        if (ctx.json)
+            await writeJson({ items, cursor: null });
+        else
+            for (const item of items)
+                await writeStdout(`${item.key}${item.url ? `  ${item.url}` : ""}\n`);
+        return 0;
+    }
+    const result = await ctx.client.list({ prefix, limit, cursor });
+    if (ctx.json)
+        await writeJson(result);
+    else {
+        for (const item of result.items)
+            await writeStdout(`${item.key}${item.url ? `  ${item.url}` : ""}\n`);
+        if (result.cursor)
+            process.stderr.write(`cursor: ${result.cursor}\n`);
+    }
+    return 0;
+}
+// --- delete ---
+const DELETE_HELP = `uploads delete <key> [--dry-run] [--workspace <name>]
+
+Examples:
+  uploads delete screenshots/myapp/42/shot-a1b2c3.png
+`;
+export async function runDelete(ctx, args, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        process.stderr.write(DELETE_HELP);
+        return 0;
+    }
+    const key = parsed.positionals[0];
+    if (!key) {
+        process.stderr.write(DELETE_HELP);
+        return 2;
+    }
+    if (flagBool(parsed.flags, "--dry-run")) {
+        if (ctx.json)
+            await writeJson({ key, deleted: false, dryRun: true });
+        else
+            process.stderr.write(`dry-run: would delete ${key}\n`);
+        return 0;
+    }
+    const result = await ctx.client.delete(key);
+    if (ctx.json)
+        await writeJson(result);
+    else if (!ctx.quiet)
+        process.stderr.write(`deleted ${result.key}\n`);
+    return 0;
+}
+// --- comment ---
+const COMMENT_HELP = `uploads comment (--pr <num> | --issue <num>) [--repo <owner/name>] [--workspace <name>]
+
+Create or update the managed attachments comment on a GitHub PR or issue,
+listing everything uploaded for it. Uses your local gh auth. Finds its own
+prior comment via a hidden marker and edits it in place; never touches other
+comments or the description.
+
+Examples:
+  uploads --env-file .env comment --pr 123
+  uploads comment --issue 45 --repo buildinternet/uploads
+`;
+export async function runComment(ctx, args, help = false, run = execRunner) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        process.stderr.write(COMMENT_HELP);
+        return 0;
+    }
+    const target = ghTargetFromFlags(parsed.flags, run);
+    if (!target)
+        throw new UsageError("comment requires --pr or --issue");
+    const result = await syncAttachmentsComment(ctx, target, run);
+    if (ctx.json) {
+        await writeJson({ ...target, ...result });
+    }
+    else if (!ctx.quiet) {
+        process.stderr.write(result.action === "skipped"
+            ? `no attachments under ${ghKeyPrefix(target)} — nothing to do\n`
+            : `${result.action} attachments comment on ${target.repo}#${target.num} (${result.count} file${result.count === 1 ? "" : "s"})\n`);
+    }
+    return 0;
+}
+// --- health & doctor ---
+const HEALTH_HELP = `uploads health
+
+API liveness (no auth).
+
+Examples:
+  uploads health
+  uploads --api-url http://localhost:8787 health
+`;
+export async function runHealth(ctx, args, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(HEALTH_HELP);
+        return 0;
+    }
+    const result = await createUploadsClient({
+        apiUrl: ctx.apiUrl,
+        workspace: "default",
+        token: "",
+    }).health();
+    if (ctx.json)
+        await writeJson({ ...result, apiUrl: ctx.apiUrl });
+    else
+        await writeStdout(result.ok ? `ok (${ctx.apiUrl})\n` : `unhealthy (${ctx.apiUrl})\n`);
+    return result.ok ? 0 : 1;
+}
+const DOCTOR_HELP = `uploads doctor [--workspace <name>]
+
+Checks API health, token auth, and workspace/token alignment.
+
+Examples:
+  uploads --env-file .env doctor
+  uploads --workspace acme --env-file .env doctor
+`;
+export async function runDoctor(ctx, args, help = false) {
+    if (help || parseCommandArgs(args).help) {
+        process.stderr.write(DOCTOR_HELP);
+        return 0;
+    }
+    const mismatch = workspaceMismatch(ctx.config);
+    const hints = [];
+    if (mismatch)
+        hints.push(mismatch);
+    if (ctx.config.apiUrl.includes("localhost") || ctx.config.apiUrl.includes("127.0.0.1")) {
+        hints.push("local API uses dev KV — prod tokens won't work unless minted with --local");
+    }
+    const health = await ctx.client.health();
+    let authOk = false;
+    let authError;
+    try {
+        await ctx.client.list({ limit: 1 });
+        authOk = true;
+    }
+    catch (err) {
+        authError = err instanceof UploadsError ? err.message : String(err);
+        if (err instanceof UploadsError && err.code === "UNAUTHORIZED") {
+            hints.push("if this token works on api.uploads.sh, set UPLOADS_API_URL=https://api.uploads.sh");
+        }
+    }
+    if (!ctx.config.configExists && !ctx.config.token) {
+        hints.push(`run uploads setup to configure ${ctx.config.configPath}`);
+    }
+    const report = {
+        ok: health.ok && authOk,
+        apiUrl: ctx.config.apiUrl,
+        workspace: ctx.config.workspace,
+        workspaceSource: ctx.config.workspaceSource,
+        workspaceFromToken: workspaceFromToken(ctx.config.token),
+        configPath: ctx.config.configPath,
+        configExists: ctx.config.configExists,
+        health,
+        auth: { ok: authOk, error: authError },
+        hints,
+    };
+    if (ctx.json) {
+        await writeJson(report);
+        return report.ok ? 0 : 1;
+    }
+    const lines = [
+        `config:    ${ctx.config.configPath}${ctx.config.configExists ? "" : " (missing)"}`,
+        `api:       ${ctx.config.apiUrl} (${health.ok ? "ok" : "failed"})`,
+        `workspace: ${ctx.config.workspace}`,
+        `auth:      ${authOk ? "ok" : `failed — ${authError ?? "no token"}`}`,
+    ];
+    if (mismatch)
+        lines.push(`warning:   ${mismatch}`);
+    for (const h of hints)
+        if (h !== mismatch)
+            lines.push(`hint:      ${h}`);
+    await writeStdout(lines.join("\n") + "\n");
+    return report.ok ? 0 : 1;
+}

package/dist/config-file.d.ts

@@ -0,0 +1,37 @@
+import type { UploadsClientConfig } from "./config.js";
+export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_DEFAULT_PREFIX", "UPLOADS_DEFAULT_REPO", "UPLOADS_DEFAULT_REF", "UPLOADS_DEFAULT_WIDTH", "UPLOADS_NO_GIT"];
+export type UploadsConfigKey = (typeof UPLOADS_CONFIG_KEYS)[number];
+export type UploadsConfigValues = Partial<Record<UploadsConfigKey, string>>;
+export interface PutDefaults {
+    prefix?: string;
+    repo?: string;
+    ref?: string;
+    width?: number;
+    noGit?: boolean;
+}
+declare const PUT_DEFAULT_KEY_MAP: Record<keyof PutDefaults, UploadsConfigKey>;
+export declare function putDefaultsToConfigValues(defaults: PutDefaults): UploadsConfigValues;
+/** XDG default shared across buildinternet skills (github-screenshots, uploads, …). */
+export declare function defaultConfigPath(): string;
+/** Resolved config file path: explicit --env-file, then $BUILDINTERNET_CONFIG, then XDG default. */
+export declare function resolveConfigPath(flags?: {
+    envFile?: string;
+}): string;
+/** Parse UPLOADS_* keys from a dotenv-style file. Missing file → empty object. */
+export declare function loadConfigFile(path: string): UploadsConfigValues;
+export declare function mergePutDefaults(...layers: PutDefaults[]): PutDefaults;
+/** Put defaults from env, optional env-file, and user config (same precedence as client config). */
+export declare function resolvePutDefaults(flags?: {
+    envFile?: string;
+}): PutDefaults;
+export declare function redactToken(token: string | undefined): string;
+/** Create or update UPLOADS_* keys in the shared config file. Preserves other keys. */
+export declare function writeConfigKeys(path: string, keys: UploadsConfigValues, opts?: {
+    force?: boolean;
+}): {
+    path: string;
+    created: boolean;
+    updated: string[];
+};
+export declare function configValuesFromClient(config: Partial<UploadsClientConfig>, defaults?: PutDefaults): UploadsConfigValues;
+export { PUT_DEFAULT_KEY_MAP };

package/dist/config-file.js

@@ -0,0 +1,204 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { homedir } from "node:os";
+export const UPLOADS_CONFIG_KEYS = [
+    "UPLOADS_API_URL",
+    "UPLOADS_WORKSPACE",
+    "UPLOADS_TOKEN",
+    "UPLOADS_DEFAULT_PREFIX",
+    "UPLOADS_DEFAULT_REPO",
+    "UPLOADS_DEFAULT_REF",
+    "UPLOADS_DEFAULT_WIDTH",
+    "UPLOADS_NO_GIT",
+];
+const PUT_DEFAULT_KEY_MAP = {
+    prefix: "UPLOADS_DEFAULT_PREFIX",
+    repo: "UPLOADS_DEFAULT_REPO",
+    ref: "UPLOADS_DEFAULT_REF",
+    width: "UPLOADS_DEFAULT_WIDTH",
+    noGit: "UPLOADS_NO_GIT",
+};
+export function putDefaultsToConfigValues(defaults) {
+    const out = {};
+    if (defaults.prefix)
+        out.UPLOADS_DEFAULT_PREFIX = defaults.prefix;
+    if (defaults.repo)
+        out.UPLOADS_DEFAULT_REPO = defaults.repo;
+    if (defaults.ref)
+        out.UPLOADS_DEFAULT_REF = defaults.ref;
+    if (defaults.width != null)
+        out.UPLOADS_DEFAULT_WIDTH = String(defaults.width);
+    if (defaults.noGit)
+        out.UPLOADS_NO_GIT = "1";
+    return out;
+}
+function parsePutDefaultsFromRaw(raw) {
+    const out = {};
+    if (raw.UPLOADS_DEFAULT_PREFIX)
+        out.prefix = raw.UPLOADS_DEFAULT_PREFIX;
+    if (raw.UPLOADS_DEFAULT_REPO)
+        out.repo = raw.UPLOADS_DEFAULT_REPO;
+    if (raw.UPLOADS_DEFAULT_REF)
+        out.ref = raw.UPLOADS_DEFAULT_REF;
+    if (raw.UPLOADS_DEFAULT_WIDTH) {
+        const n = Number.parseInt(raw.UPLOADS_DEFAULT_WIDTH, 10);
+        if (Number.isFinite(n) && n > 0)
+            out.width = n;
+    }
+    if (raw.UPLOADS_NO_GIT === "1" || raw.UPLOADS_NO_GIT?.toLowerCase() === "true") {
+        out.noGit = true;
+    }
+    return out;
+}
+function parsePutDefaultsFromEnv() {
+    const raw = {};
+    if (process.env.UPLOADS_DEFAULT_PREFIX)
+        raw.UPLOADS_DEFAULT_PREFIX = process.env.UPLOADS_DEFAULT_PREFIX;
+    if (process.env.UPLOADS_DEFAULT_REPO)
+        raw.UPLOADS_DEFAULT_REPO = process.env.UPLOADS_DEFAULT_REPO;
+    if (process.env.UPLOADS_DEFAULT_REF)
+        raw.UPLOADS_DEFAULT_REF = process.env.UPLOADS_DEFAULT_REF;
+    if (process.env.UPLOADS_DEFAULT_WIDTH)
+        raw.UPLOADS_DEFAULT_WIDTH = process.env.UPLOADS_DEFAULT_WIDTH;
+    if (process.env.UPLOADS_NO_GIT)
+        raw.UPLOADS_NO_GIT = process.env.UPLOADS_NO_GIT;
+    return parsePutDefaultsFromRaw(raw);
+}
+/** XDG default shared across buildinternet skills (github-screenshots, uploads, …). */
+export function defaultConfigPath() {
+    const xdg = process.env.XDG_CONFIG_HOME ?? `${homedir()}/.config`;
+    return `${xdg}/buildinternet/config`;
+}
+/** Resolved config file path: explicit --env-file, then $BUILDINTERNET_CONFIG, then XDG default. */
+export function resolveConfigPath(flags) {
+    if (flags?.envFile)
+        return flags.envFile;
+    if (process.env.BUILDINTERNET_CONFIG)
+        return process.env.BUILDINTERNET_CONFIG;
+    return defaultConfigPath();
+}
+function parseEnvLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#"))
+        return undefined;
+    const exportPrefix = trimmed.startsWith("export ") ? trimmed.slice(7) : trimmed;
+    const eq = exportPrefix.indexOf("=");
+    if (eq === -1)
+        return undefined;
+    const key = exportPrefix.slice(0, eq).trim();
+    let value = exportPrefix.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+    }
+    else {
+        const comment = value.search(/\s#/);
+        if (comment !== -1)
+            value = value.slice(0, comment).trimEnd();
+    }
+    return { key, value };
+}
+function isUploadsConfigKey(key) {
+    return UPLOADS_CONFIG_KEYS.includes(key);
+}
+/** Parse UPLOADS_* keys from a dotenv-style file. Missing file → empty object. */
+export function loadConfigFile(path) {
+    if (!existsSync(path))
+        return {};
+    const out = {};
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+        const parsed = parseEnvLine(line);
+        if (!parsed || !isUploadsConfigKey(parsed.key))
+            continue;
+        out[parsed.key] = parsed.value;
+    }
+    return out;
+}
+export function mergePutDefaults(...layers) {
+    const out = {};
+    for (const layer of layers) {
+        if (layer.prefix)
+            out.prefix = layer.prefix;
+        if (layer.repo)
+            out.repo = layer.repo;
+        if (layer.ref)
+            out.ref = layer.ref;
+        if (layer.width != null)
+            out.width = layer.width;
+        if (layer.noGit != null)
+            out.noGit = layer.noGit;
+    }
+    return out;
+}
+/** Put defaults from env, optional env-file, and user config (same precedence as client config). */
+export function resolvePutDefaults(flags) {
+    const fromEnv = parsePutDefaultsFromEnv();
+    const fromEnvFile = flags?.envFile ? parsePutDefaultsFromRaw(loadConfigFile(flags.envFile)) : {};
+    const fromUser = flags?.envFile
+        ? {}
+        : parsePutDefaultsFromRaw(loadConfigFile(resolveConfigPath(flags)));
+    return mergePutDefaults(fromUser, fromEnvFile, fromEnv);
+}
+export function redactToken(token) {
+    if (!token)
+        return "unset";
+    if (token.length <= 12)
+        return "set (redacted)";
+    return `set (${token.slice(0, 12)}…)`;
+}
+const INIT_HEADER = `# uploads.sh CLI — shared buildinternet config
+# Other skills (e.g. github-screenshots) use this same file with their own prefixed keys.
+#
+# Resolution order (first match wins, per key):
+#   1. CLI flags (--api-url, --token, --workspace)
+#   2. environment variables
+#   3. --env-file <path>
+#   4. $BUILDINTERNET_CONFIG
+#   5. ~/.config/buildinternet/config
+#
+# Mint a token: uploads setup
+# Put defaults (optional): UPLOADS_DEFAULT_PREFIX, UPLOADS_DEFAULT_REPO, UPLOADS_DEFAULT_REF
+`;
+/** Create or update UPLOADS_* keys in the shared config file. Preserves other keys. */
+export function writeConfigKeys(path, keys, opts) {
+    const entries = Object.entries(keys).filter(([, v]) => v !== undefined && v !== "");
+    if (entries.length === 0) {
+        throw new Error("no config values to write");
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    const existed = existsSync(path);
+    let lines = existed ? readFileSync(path, "utf8").split("\n") : [];
+    if (!existed) {
+        lines = INIT_HEADER.trimEnd().split("\n");
+    }
+    const updated = [];
+    for (const [key, value] of entries) {
+        const re = new RegExp(`^(?:export\\s+)?${key}=`);
+        const idx = lines.findIndex((line) => re.test(line.trim()));
+        const line = `${key}=${value}`;
+        if (idx === -1) {
+            if (lines.length > 0 && lines[lines.length - 1] !== "")
+                lines.push("");
+            lines.push(line);
+            updated.push(key);
+        }
+        else if (opts?.force || !parseEnvLine(lines[idx])?.value) {
+            lines[idx] = line;
+            updated.push(key);
+        }
+    }
+    writeFileSync(path, lines.join("\n").replace(/\n*$/, "\n"), "utf8");
+    return { path, created: !existed, updated };
+}
+export function configValuesFromClient(config, defaults) {
+    const out = {};
+    if (config.apiUrl)
+        out.UPLOADS_API_URL = config.apiUrl;
+    if (config.workspace)
+        out.UPLOADS_WORKSPACE = config.workspace;
+    if (config.token)
+        out.UPLOADS_TOKEN = config.token;
+    Object.assign(out, putDefaultsToConfigValues(defaults ?? {}));
+    return out;
+}
+export { PUT_DEFAULT_KEY_MAP };