seedyn 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Ilie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# Seedyn CLI
+
+Upload any file to Seedyn and print its permanent public URL. The package has
+no runtime dependencies and requires Node.js 22.12 or newer.
+
+## Setup
+
+Create an API key in Seedyn with the scopes needed for the files you plan to
+upload, then save it using a hidden terminal prompt:
+
+```sh
+npx seedyn auth set
+```
+
+Credentials are written to `$XDG_CONFIG_HOME/seedyn/config.json`, or
+`~/.config/seedyn/config.json` when `XDG_CONFIG_HOME` is unset. The directory is
+mode `0700` and the file is mode `0600`. `SEEDYN_CONFIG_PATH` can select a
+different absolute file.
+
+For CI, keep credentials outside the repository:
+
+```sh
+export SEEDYN_API_KEY='sdn_live_…'
+```
+
+Authentication precedence is `--api-key`, then `SEEDYN_API_KEY`, then the
+owner-only config file. API URL precedence is `--api-url`, then
+`SEEDYN_API_URL`, then the config file, then `https://seedyn.dave.tips`.
+Passing a secret on the command line can expose it to shell history and process
+inspection; prefer the environment or `seedyn auth set`.
+
+## Upload
+
+The shortest form treats the first argument as a file:
+
+```sh
+npx seedyn ./report.pdf
+```
+
+The explicit form exposes all upload controls:
+
+```sh
+npx seedyn upload ./report.pdf --copy
+npx seedyn upload ./page.html --render-html --open
+npx seedyn upload ./image.png --slug launch-shot --domain gurt
+```
+
+`--render-html` is an explicit opt-in. Seedyn verifies a non-empty UTF-8 HTML
+document, stores it as `text/html`, and serves it inline only on a configured
+public media domain. Uploaded scripts, forms, frames, embedded objects, and
+network requests remain disabled by the response sandbox. Without the flag,
+HTML is an ordinary attachment.
+
+Agents can upload stdin by naming the resulting file:
+
+```sh
+generate-report | npx seedyn upload - --filename report.html --render-html
+```
+
+Useful options:
+
+- `--copy` copies the URL using the operating system clipboard command.
+- `--open` opens the URL using the operating system URL handler.
+- `--json` prints a machine-readable response.
+- `--quiet` prints only the URL.
+- `--slug <slug>` requests a readable public slug.
+- `--domain <id>` chooses a configured media-domain identifier.
+- `--kind <auto|image|file|text>` supplies the server classification hint.
+- `--language <language>` supplies the text-language hint.
+- `--api-url <origin>` targets a local or custom Seedyn instance.
+
+The server always classifies the uploaded bytes and enforces the API key scope.
+Files are limited to 64 MiB; rendered HTML, images, and text are limited to
+16 MiB.
+
+## Attribution
+
+The command workflow is inspired by the MIT-licensed
+[`postplan@0.0.4`](https://www.jsdelivr.com/package/npm/postplan). See
+[`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md) for attribution and the
+retained license.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,32 @@
+# Third-party notices
+
+The Seedyn CLI workflow was adapted from
+[`postplan@0.0.4`](https://www.jsdelivr.com/package/npm/postplan), particularly
+its low-step upload command, explicit API URL override, owner-only local
+credential storage, and optional Git/CI-friendly operation. Postplan is
+copyright 2026 t3dotgg and distributed under the following MIT license:
+
+> MIT License
+>
+> Copyright (c) 2026 t3dotgg
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+
+Seedyn uses its own API contract and implementation. It does not include or run
+the Postplan service.

package/bin/seedyn.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { run } from "../src/cli.mjs";
+import { CliError } from "../src/errors.mjs";
+
+process.stdout.on("error", (error) => {
+  if (error.code === "EPIPE") process.exit(0);
+  throw error;
+});
+
+try {
+  await run(process.argv.slice(2));
+} catch (error) {
+  if (error instanceof CliError) {
+    console.error(error.message);
+  } else {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "seedyn",
+  "version": "0.1.0",
+  "description": "Upload any file to Seedyn and receive its durable URL.",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "bin": {
+    "seedyn": "./bin/seedyn.mjs"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,293 @@
+import { createRequire } from "node:module";
+import { parseArgs } from "node:util";
+
+import {
+  configPath,
+  displayApiKey,
+  readConfig,
+  removeAuthentication,
+  resolveAuthentication,
+  saveAuthentication,
+  validateApiKey,
+  validateApiUrl,
+} from "./config.mjs";
+import { CliError } from "./errors.mjs";
+import { copyUrl, openUrl, uploadFile } from "./upload.mjs";
+
+const { version: VERSION } = createRequire(import.meta.url)("../package.json");
+
+export async function run(arguments_) {
+  const args = [...arguments_];
+  const first = args[0];
+  if (!first || first === "help" || first === "--help" || first === "-h") {
+    console.log(HELP);
+    return;
+  }
+  if (first === "version" || first === "--version" || first === "-V") {
+    console.log(VERSION);
+    return;
+  }
+  if (first === "auth") {
+    await authCommand(args.slice(1));
+    return;
+  }
+  await uploadCommand(first === "upload" ? args.slice(1) : args);
+}
+
+async function authCommand(args) {
+  const action = args[0] || "help";
+  if (action === "help" || action === "--help" || action === "-h") {
+    console.log(AUTH_HELP);
+    return;
+  }
+
+  if (action === "set") {
+    const { values, positionals } = parseArgs({
+      args: args.slice(1),
+      allowPositionals: true,
+      strict: true,
+      options: {
+        "api-key": { type: "string" },
+        "api-url": { type: "string" },
+        help: { type: "boolean", short: "h" },
+      },
+    });
+    if (values.help) {
+      console.log(AUTH_SET_HELP);
+      return;
+    }
+    if (positionals.length > 1)
+      throw new CliError("auth set accepts at most one API key.");
+    const key = validateApiKey(
+      values["api-key"] || positionals[0] || (await readSecret()),
+    );
+    const apiUrl = values["api-url"]
+      ? validateApiUrl(values["api-url"])
+      : undefined;
+    const result = await saveAuthentication({ apiKey: key, apiUrl });
+    console.log(`Seedyn credentials saved to ${result.file}`);
+    console.log(`API key: ${displayApiKey(key)}`);
+    console.log(
+      `API URL: ${result.value.apiUrl || "https://seedyn.dave.tips"}`,
+    );
+    return;
+  }
+
+  if (action === "remove") {
+    if (args.length > 1) throw new CliError("auth remove takes no arguments.");
+    console.log(
+      `Removed the stored API key from ${await removeAuthentication()}`,
+    );
+    return;
+  }
+
+  if (action === "status") {
+    if (args.length > 1) throw new CliError("auth status takes no arguments.");
+    const config = await readConfig();
+    console.log(`Config: ${configPath()}`);
+    console.log(`API URL: ${config.apiUrl || "https://seedyn.dave.tips"}`);
+    console.log(
+      `Stored API key: ${config.apiKey ? displayApiKey(config.apiKey) : "not configured"}`,
+    );
+    console.log(
+      `Environment API key: ${process.env.SEEDYN_API_KEY ? "configured" : "not configured"}`,
+    );
+    return;
+  }
+
+  throw new CliError(`Unknown auth command: ${action}`);
+}
+
+async function uploadCommand(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      "api-key": { type: "string" },
+      "api-url": { type: "string" },
+      copy: { type: "boolean", short: "c" },
+      domain: { type: "string", short: "d" },
+      filename: { type: "string" },
+      help: { type: "boolean", short: "h" },
+      json: { type: "boolean" },
+      kind: { type: "string", default: "auto" },
+      language: { type: "string" },
+      open: { type: "boolean", short: "o" },
+      quiet: { type: "boolean", short: "q" },
+      render: { type: "boolean" },
+      "render-html": { type: "boolean" },
+      slug: { type: "string", short: "s" },
+      timeout: { type: "string", default: "120" },
+    },
+  });
+  if (values.help) {
+    console.log(UPLOAD_HELP);
+    return;
+  }
+  if (positionals.length !== 1) {
+    throw new CliError("Choose exactly one file, or use - for stdin.");
+  }
+  const kind = values.kind;
+  if (!new Set(["auto", "image", "file", "text"]).has(kind)) {
+    throw new CliError("--kind must be auto, image, file, or text.");
+  }
+  const timeoutSeconds = Number(values.timeout);
+  if (
+    !Number.isInteger(timeoutSeconds) ||
+    timeoutSeconds < 1 ||
+    timeoutSeconds > 600
+  ) {
+    throw new CliError(
+      "--timeout must be a whole number from 1 to 600 seconds.",
+    );
+  }
+  if (values.json && values.quiet) {
+    throw new CliError("Choose either --json or --quiet, not both.");
+  }
+
+  const auth = await resolveAuthentication({
+    apiKey: values["api-key"],
+    apiUrl: values["api-url"],
+  });
+  const result = await uploadFile({
+    ...auth,
+    version: VERSION,
+    file: positionals[0],
+    filename: values.filename,
+    renderHtml: Boolean(values["render-html"] || values.render),
+    slug: values.slug,
+    domain: values.domain,
+    kind,
+    language: values.language,
+    timeoutMs: timeoutSeconds * 1000,
+  });
+
+  const notices = [];
+  if (values.copy)
+    notices.push(
+      copyUrl(result.url)
+        ? "Copied URL."
+        : "Could not access a clipboard command.",
+    );
+  if (values.open)
+    notices.push(
+      openUrl(result.url) ? "Opened URL." : "Could not open the URL handler.",
+    );
+
+  if (values.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (values.quiet) {
+    console.log(result.url);
+    return;
+  }
+  console.log(`Uploaded ${result.filename}`);
+  console.log(`URL: ${result.url}`);
+  if (result.renderedHtml) console.log("Mode: sandboxed HTML page");
+  for (const notice of notices) console.log(notice);
+}
+
+async function readSecret() {
+  if (!process.stdin.isTTY) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+      const value = Buffer.from(chunk);
+      bytes += value.byteLength;
+      if (bytes > 512) throw new CliError("The piped API key is too long.");
+      chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString("utf8").trim();
+  }
+
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const wasRaw = process.stdin.isRaw;
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      process.stdin.setRawMode(wasRaw);
+      process.stdin.pause();
+      process.stderr.write("\n");
+    };
+    const onData = (chunk) => {
+      for (const byte of Buffer.from(chunk)) {
+        if (byte === 3) {
+          cleanup();
+          reject(new CliError("Authentication setup cancelled."));
+          return;
+        }
+        if (byte === 4 && value.length === 0) {
+          cleanup();
+          reject(new CliError("No API key entered."));
+          return;
+        }
+        if (byte === 10 || byte === 13) {
+          cleanup();
+          resolve(value);
+          return;
+        }
+        if (byte === 8 || byte === 127) {
+          value = value.slice(0, -1);
+        } else if (byte >= 0x20 && byte <= 0x7e && value.length < 256) {
+          value += String.fromCharCode(byte);
+        }
+      }
+    };
+    process.stderr.write("Seedyn API key: ");
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}
+
+const HELP = `Seedyn ${VERSION}
+
+Upload any file and receive its durable URL.
+
+Usage:
+  seedyn <file> [options]
+  seedyn upload <file> [options]
+  seedyn auth <set|status|remove>
+
+Examples:
+  seedyn ./image.png --copy
+  seedyn ./page.html --render-html --open
+  seedyn upload - --filename report.html --render-html
+
+Run seedyn upload --help for every upload option.`;
+
+const UPLOAD_HELP = `Usage: seedyn upload <file|-> [options]
+
+Options:
+  -c, --copy                 Copy the resulting URL
+  -o, --open                 Open the resulting URL
+  --render-html, --render    Serve verified UTF-8 HTML as a sandboxed page
+  -s, --slug <slug>          Request a custom public slug
+  -d, --domain <id>          Choose a configured media-domain identifier
+  --kind <kind>              auto, image, file, or text (default: auto)
+  --language <language>      Text-language hint
+  --filename <name>          Override the uploaded filename; required for stdin
+  --json                     Print machine-readable JSON
+  -q, --quiet                Print only the URL
+  --timeout <seconds>        Upload timeout from 1 to 600 (default: 120)
+  --api-url <origin>         Override the Seedyn application origin
+  --api-key <key>            Override auth (prefer env/config; argv is visible)
+  -h, --help                 Show this help`;
+
+const AUTH_HELP = `Usage: seedyn auth <command>
+
+Commands:
+  set [api-key]              Store a key with owner-only permissions
+  status                     Show config and redacted credential status
+  remove                     Remove the stored API key
+
+Prefer bare "seedyn auth set" for a hidden prompt.`;
+
+const AUTH_SET_HELP = `Usage: seedyn auth set [api-key] [options]
+
+Options:
+  --api-url <origin>         Save a custom Seedyn application origin
+  --api-key <key>            Supply the key (prefer the hidden prompt)
+  -h, --help                 Show this help`;

package/src/config.mjs

@@ -0,0 +1,175 @@
+import { randomUUID } from "node:crypto";
+import {
+  chmod,
+  lstat,
+  mkdir,
+  readFile,
+  rename,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { CliError } from "./errors.mjs";
+
+export const DEFAULT_API_URL = "https://seedyn.dave.tips";
+const API_KEY_PATTERN = /^sdn_live_[A-Za-z0-9_-]{8}_[A-Za-z0-9_-]{43}$/u;
+
+export function validateApiKey(value) {
+  const key = typeof value === "string" ? value.trim() : "";
+  if (!API_KEY_PATTERN.test(key)) {
+    throw new CliError("That is not a valid Seedyn API key.");
+  }
+  return key;
+}
+
+export function displayApiKey(value) {
+  const key = validateApiKey(value);
+  return `${key.slice(0, "sdn_live_".length + 8)}_…`;
+}
+
+export function validateApiUrl(value) {
+  let url;
+  try {
+    url = new URL(String(value).trim());
+  } catch {
+    throw new CliError("The Seedyn API URL must be a valid origin.");
+  }
+
+  const local =
+    url.hostname === "localhost" ||
+    url.hostname.endsWith(".localhost") ||
+    url.hostname === "127.0.0.1" ||
+    url.hostname === "[::1]";
+  if (
+    (url.protocol !== "https:" && !(url.protocol === "http:" && local)) ||
+    url.username ||
+    url.password ||
+    url.pathname !== "/" ||
+    url.search ||
+    url.hash
+  ) {
+    throw new CliError(
+      "The Seedyn API URL must be an HTTPS origin (HTTP is allowed only on localhost).",
+    );
+  }
+  return url.origin;
+}
+
+export function configPath(environment = process.env) {
+  const explicit = environment.SEEDYN_CONFIG_PATH?.trim();
+  if (explicit) {
+    if (!path.isAbsolute(explicit)) {
+      throw new CliError("SEEDYN_CONFIG_PATH must be an absolute path.");
+    }
+    return explicit;
+  }
+  const xdg = environment.XDG_CONFIG_HOME?.trim();
+  const root =
+    xdg && path.isAbsolute(xdg) ? xdg : path.join(os.homedir(), ".config");
+  return path.join(root, "seedyn", "config.json");
+}
+
+export async function readConfig(environment = process.env) {
+  const file = configPath(environment);
+  try {
+    const status = await lstat(file);
+    if (!status.isFile() || status.isSymbolicLink()) {
+      throw new CliError(`Seedyn config is not a regular file: ${file}`);
+    }
+    if (process.platform !== "win32" && (status.mode & 0o077) !== 0) {
+      throw new CliError(
+        `Seedyn config permissions are too open: ${file}. Restrict it to mode 0600.`,
+      );
+    }
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("not an object");
+    }
+    return parsed;
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    if (error instanceof CliError) throw error;
+    throw new CliError(`Seedyn config is unreadable: ${file}`, {
+      cause: error,
+    });
+  }
+}
+
+export async function resolveAuthentication(
+  options = {},
+  environment = process.env,
+) {
+  const config = await readConfig(environment);
+  const apiUrl = validateApiUrl(
+    options.apiUrl ||
+      environment.SEEDYN_API_URL ||
+      config.apiUrl ||
+      DEFAULT_API_URL,
+  );
+  const candidate =
+    options.apiKey || environment.SEEDYN_API_KEY || config.apiKey;
+  if (!candidate) {
+    throw new CliError(
+      "Missing Seedyn API key. Run `seedyn auth set` or set SEEDYN_API_KEY.",
+    );
+  }
+  return { apiKey: validateApiKey(candidate), apiUrl };
+}
+
+export async function saveAuthentication(
+  { apiKey, apiUrl },
+  environment = process.env,
+) {
+  const existing = await readConfig(environment);
+  const next = {
+    ...existing,
+    apiKey: validateApiKey(apiKey),
+    ...(apiUrl ? { apiUrl: validateApiUrl(apiUrl) } : {}),
+    updatedAt: new Date().toISOString(),
+  };
+  await writeConfig(next, environment);
+  return { file: configPath(environment), value: next };
+}
+
+export async function removeAuthentication(environment = process.env) {
+  const existing = await readConfig(environment);
+  const { apiKey: _removed, ...next } = existing;
+  await writeConfig(
+    { ...next, updatedAt: new Date().toISOString() },
+    environment,
+  );
+  return configPath(environment);
+}
+
+async function writeConfig(value, environment) {
+  const file = configPath(environment);
+  const directory = path.dirname(file);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const directoryStatus = await lstat(directory);
+  if (!directoryStatus.isDirectory() || directoryStatus.isSymbolicLink()) {
+    throw new CliError(`Seedyn config directory is unsafe: ${directory}`);
+  }
+  await chmod(directory, 0o700);
+
+  const temporary = path.join(
+    directory,
+    `.config.${process.pid}.${randomUUID()}.tmp`,
+  );
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+    await chmod(temporary, 0o600);
+    await rename(temporary, file);
+    await chmod(file, 0o600);
+  } catch (error) {
+    await unlink(temporary).catch(() => undefined);
+    throw new CliError(`Could not write Seedyn config: ${file}`, {
+      cause: error,
+    });
+  }
+}

package/src/errors.mjs

@@ -0,0 +1,6 @@
+export class CliError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CliError";
+  }
+}

package/src/upload.mjs

@@ -0,0 +1,234 @@
+import { openAsBlob } from "node:fs";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { CliError } from "./errors.mjs";
+
+const MAX_UPLOAD_BYTES = 64 * 1024 * 1024;
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+
+export async function uploadFile(input) {
+  const source = await uploadSource(input.file, input.filename);
+  const form = new FormData();
+  form.append("file", source.blob, source.filename);
+  append(form, "kind", input.kind === "auto" ? undefined : input.kind);
+  append(form, "textLanguage", input.language);
+  append(form, "slug", input.slug);
+  append(form, "mediaDomain", input.domain);
+  if (input.renderHtml) form.append("renderHtml", "true");
+
+  const controller = new AbortController();
+  const timeout = setTimeout(
+    () => controller.abort("timeout"),
+    input.timeoutMs,
+  );
+  timeout.unref();
+  const interrupt = () => controller.abort("interrupt");
+  process.once("SIGINT", interrupt);
+
+  let response;
+  let body;
+  try {
+    response = await fetch(new URL("/api/upload", input.apiUrl), {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${input.apiKey}`,
+        "User-Agent": `seedyn-cli/${input.version}`,
+      },
+      body: form,
+      signal: controller.signal,
+    });
+    body = await readJsonResponse(response);
+  } catch (error) {
+    if (controller.signal.reason === "timeout") {
+      throw new CliError(
+        `Upload timed out after ${input.timeoutMs / 1000} seconds.`,
+      );
+    }
+    if (controller.signal.reason === "interrupt") {
+      throw new CliError("Upload cancelled.");
+    }
+    throw new CliError("Seedyn could not be reached.", { cause: error });
+  } finally {
+    clearTimeout(timeout);
+    process.removeListener("SIGINT", interrupt);
+  }
+
+  if (!response.ok) {
+    const message =
+      typeof body?.error?.message === "string"
+        ? body.error.message
+        : `Seedyn rejected the upload (HTTP ${response.status}).`;
+    const requestId =
+      typeof body?.error?.requestId === "string"
+        ? ` Request: ${body.error.requestId}`
+        : "";
+    throw new CliError(`${message}${requestId}`);
+  }
+  if (!body || typeof body.url !== "string") {
+    throw new CliError("Seedyn returned an unreadable upload response.");
+  }
+
+  let url;
+  try {
+    url = new URL(body.url);
+  } catch {
+    throw new CliError("Seedyn returned an invalid public URL.");
+  }
+  if (
+    (url.protocol !== "https:" && url.protocol !== "http:") ||
+    (url.protocol === "http:" && !isLocalHostname(url.hostname)) ||
+    url.username ||
+    url.password
+  ) {
+    throw new CliError("Seedyn returned an unsafe public URL.");
+  }
+
+  return {
+    id: typeof body.id === "string" ? body.id : null,
+    kind: typeof body.kind === "string" ? body.kind : null,
+    contentType: typeof body.contentType === "string" ? body.contentType : null,
+    disposition: typeof body.disposition === "string" ? body.disposition : null,
+    renderedHtml: body.renderedHtml === true,
+    url: url.toString(),
+    filename: source.filename,
+  };
+}
+
+function isLocalHostname(hostname) {
+  return (
+    hostname === "localhost" ||
+    hostname.endsWith(".localhost") ||
+    hostname === "127.0.0.1" ||
+    hostname === "[::1]"
+  );
+}
+
+export function copyUrl(value) {
+  const attempts =
+    process.platform === "darwin"
+      ? [["pbcopy", []]]
+      : process.platform === "win32"
+        ? [["clip.exe", []]]
+        : [
+            ["wl-copy", []],
+            ["xclip", ["-selection", "clipboard"]],
+            ["xsel", ["--clipboard", "--input"]],
+          ];
+  for (const [command, args] of attempts) {
+    const result = spawnSync(command, args, {
+      input: value,
+      encoding: "utf8",
+      stdio: ["pipe", "ignore", "ignore"],
+      timeout: 5_000,
+      windowsHide: true,
+    });
+    if (!result.error && result.status === 0) return true;
+  }
+  return false;
+}
+
+export function openUrl(value) {
+  const target = new URL(value);
+  let command;
+  let args;
+  if (process.platform === "darwin") {
+    command = "open";
+    args = [target.toString()];
+  } else if (process.platform === "win32") {
+    command = "rundll32.exe";
+    args = ["url.dll,FileProtocolHandler", target.toString()];
+  } else {
+    command = "xdg-open";
+    args = [target.toString()];
+  }
+  const result = spawnSync(command, args, {
+    stdio: "ignore",
+    timeout: 5_000,
+    windowsHide: true,
+  });
+  return !result.error && result.status === 0;
+}
+
+async function uploadSource(file, explicitFilename) {
+  if (file === "-") {
+    if (!explicitFilename) {
+      throw new CliError("Uploading stdin requires --filename <name>.");
+    }
+    const bytes = await readStdin();
+    return { blob: new Blob(bytes), filename: safeFilename(explicitFilename) };
+  }
+
+  const resolved = path.resolve(file);
+  let status;
+  try {
+    status = await stat(resolved);
+  } catch (error) {
+    throw new CliError(`File does not exist: ${resolved}`, { cause: error });
+  }
+  if (!status.isFile()) throw new CliError(`Not a regular file: ${resolved}`);
+  if (status.size > MAX_UPLOAD_BYTES) {
+    throw new CliError("That file exceeds Seedyn's 64 MiB upload limit.");
+  }
+  return {
+    blob: await openAsBlob(resolved),
+    filename: safeFilename(explicitFilename || path.basename(resolved)),
+  };
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    throw new CliError("No stdin data was provided.");
+  }
+  const chunks = [];
+  let received = 0;
+  for await (const chunk of process.stdin) {
+    const bytes = Buffer.from(chunk);
+    received += bytes.byteLength;
+    if (received > MAX_UPLOAD_BYTES) {
+      throw new CliError("Stdin exceeds Seedyn's 64 MiB upload limit.");
+    }
+    chunks.push(bytes);
+  }
+  return chunks;
+}
+
+function safeFilename(value) {
+  const filename = String(value).trim();
+  if (
+    !filename ||
+    filename === "." ||
+    filename === ".." ||
+    /[\\/\0\r\n]/u.test(filename)
+  ) {
+    throw new CliError(
+      "--filename must be a plain filename without path separators.",
+    );
+  }
+  if (Buffer.byteLength(filename, "utf8") > 255) {
+    throw new CliError("The filename is longer than 255 UTF-8 bytes.");
+  }
+  return filename;
+}
+
+function append(form, name, value) {
+  if (typeof value === "string" && value.length > 0) form.append(name, value);
+}
+
+async function readJsonResponse(response) {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+    throw new CliError("Seedyn returned an unexpectedly large response.");
+  }
+  const text = await response.text();
+  if (Buffer.byteLength(text, "utf8") > MAX_RESPONSE_BYTES) {
+    throw new CliError("Seedyn returned an unexpectedly large response.");
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}