@refract9/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# @refract9/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line client for the refract9 HTTP API. Requires Node.js 24.15 or newer.
+
+```bash
+npm install -g @refract9/cli
+refract9 help
+```
+
+`REFRACT9_API_KEY` is required for API commands. `REFRACT9_API_URL` defaults to `http://localhost:3000`.

package/dist/main.js

@@ -0,0 +1,874 @@
+#!/usr/bin/env node
+
+// src/main.ts
+import { randomBytes } from "node:crypto";
+import { mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+import { completeMultipartUpload, createMultipartUpload, uploadPart } from "@vercel/blob/client";
+
+// src/config.ts
+var defaultApiUrl = "http://localhost:3000";
+var missingKey = "Set REFRACT9_API_KEY to call the refract9 API.";
+function readClientConfig(env) {
+  const apiKey = env.REFRACT9_API_KEY?.trim() ?? "";
+  if (apiKey.length === 0) return { ok: false, message: missingKey };
+  const configured = env.REFRACT9_API_URL?.trim() ?? "";
+  const apiUrl = (configured.length === 0 ? defaultApiUrl : configured).replace(/\/+$/, "");
+  return { ok: true, config: { apiKey, apiUrl } };
+}
+
+// src/help.ts
+function helpText(topic) {
+  if (topic === "entry") return entryHelp;
+  if (topic === "file") return fileHelp;
+  return overviewHelp;
+}
+var overviewHelp = `refract9 \u2014 command-line client for the refract9 API
+
+Usage:
+  refract9 <command> [arguments]
+  refract9 help [topic]
+  refract9 <command> --help
+
+Topics:
+  entry    Create, update, delete, and list entries
+  file     Upload and remove private entry files
+
+Environment:
+  REFRACT9_API_KEY    Bearer token. Required for every command except help.
+  REFRACT9_API_URL    API origin. Default: http://localhost:3000
+
+Commands:
+  entry create --manifest <json>
+  entry update <id> --manifest <json>
+  entry delete <id>
+  entry list
+  entry file put <id> --path <path> <file>
+  entry file rm <id> <path>
+
+Run \`refract9 help entry\` or \`refract9 help file\` for details.
+\`refract9 help file\` describes the 100 MB limit, retries, and resume.`;
+var entryHelp = `Entry commands manage entry metadata.
+
+Usage:
+  refract9 entry create --manifest <json>
+  refract9 entry update <id> --manifest <json>
+  refract9 entry delete <id>
+  refract9 entry list
+
+  --manifest <json>    Manifest object as JSON. Extra fields are sent as given.
+
+Create stores a new entry. Update replaces the manifest of one owned entry.
+Delete removes that entry and its private files. List prints the owned entries,
+newest first.
+
+Example:
+  refract9 entry create --manifest '{"type":"markdown","version":1,"path":"index.md"}'`;
+var fileHelp = `File commands upload and remove private entry files.
+
+Usage:
+  refract9 entry file put <id> --path <path> <file>
+  refract9 entry file rm <id> <path>
+
+  --path <path>    Entry path stored with the file, such as notes/a.md.
+  <file>           Local file to upload.
+
+Limit:
+  A single file must be 100 MB (104857600 bytes) or smaller.
+
+Retry:
+  Each token request, part upload, completion, registration, and file removal
+  tries 5 times. The wait is 200 ms and doubles after each failure.
+  Network errors and HTTP 408, 429, 500, 502, 503, and 504 are retried.
+  HTTP 400, 401, 403, and 404 stop immediately.
+
+Resume:
+  entry file put uploads the file in 8 MB (8388608 bytes) parts.
+  The last part can be smaller. After each part, progress is written to
+  ~/.refract9/uploads/<id>.json. The id is a hash of the API URL, the entry
+  id, the entry path, and the local file argument.
+  Run the same command to resume after the last completed part.
+  Registration is saved separately, so a finished upload is not sent again.
+  A file whose size or modification time changed starts a new upload.
+  Delete that progress file to discard a partial upload and start over.
+
+Examples:
+  REFRACT9_API_KEY=rf9_... refract9 entry file put entry-id --path notes/a.md ./note.md
+  REFRACT9_API_KEY=rf9_... refract9 entry file rm entry-id notes/a.md`;
+
+// src/parse.ts
+var usage = `Usage:
+  refract9 help
+  refract9 entry create --manifest <json>
+  refract9 entry update <id> --manifest <json>
+  refract9 entry delete <id>
+  refract9 entry list
+  refract9 entry file put <id> --path <path> <file>
+  refract9 entry file rm <id> <path>
+Run \`refract9 help\` for the manual.`;
+function fail(detail) {
+  return { ok: false, message: `${detail}
+${usage}` };
+}
+function succeed(command) {
+  return { ok: true, command };
+}
+function helpTopic(argv) {
+  const asked = argv.length === 0 || argv[0] === "help" || argv.includes("--help") || argv.includes("-h");
+  if (!asked) return null;
+  const args = argv.filter((arg) => arg !== "--help" && arg !== "-h");
+  const rest = args[0] === "help" ? args.slice(1) : args;
+  if (rest.length === 0) return "overview";
+  if (rest[0] === "file" && rest.length === 1) return "file";
+  if (rest[0] !== "entry") return "unknown";
+  if (rest.length === 1) return "entry";
+  if (rest[1] === "file") {
+    if (rest.length === 2) return "file";
+    if (rest.length === 3 && (rest[2] === "put" || rest[2] === "rm")) return "file";
+    return "unknown";
+  }
+  if (rest.length === 2 && ["create", "update", "delete", "list"].includes(rest[1] ?? "")) {
+    return "entry";
+  }
+  return "unknown";
+}
+function scan(args, knownFlags) {
+  const flags = /* @__PURE__ */ new Map();
+  const positionals = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index] ?? "";
+    if (token.startsWith("-")) {
+      if (!knownFlags.has(token)) return { ok: false, message: `Unexpected argument: ${token}.` };
+      const value = args[index + 1];
+      if (value === void 0 || value.startsWith("-")) {
+        return { ok: false, message: `Missing value for ${token}.` };
+      }
+      if (flags.has(token)) return { ok: false, message: `Duplicate ${token}.` };
+      flags.set(token, value);
+      index += 1;
+      continue;
+    }
+    positionals.push(token);
+  }
+  return { ok: true, flags, positionals };
+}
+function parsedManifest(raw) {
+  try {
+    return { ok: true, manifest: JSON.parse(raw) };
+  } catch {
+    return { ok: false, message: "Manifest must be JSON." };
+  }
+}
+function unexpected(positionals, count) {
+  const extra = positionals[count];
+  return extra === void 0 ? null : `Unexpected argument: ${extra}.`;
+}
+function parseList(args) {
+  const scanned = scan(args, /* @__PURE__ */ new Set());
+  if (!scanned.ok) return fail(scanned.message);
+  const extra = unexpected(scanned.positionals, 0);
+  if (extra) return fail(extra);
+  return succeed({ kind: "entry-list" });
+}
+function parseCreate(args) {
+  const scanned = scan(args, /* @__PURE__ */ new Set(["--manifest"]));
+  if (!scanned.ok) return fail(scanned.message);
+  const raw = scanned.flags.get("--manifest");
+  if (raw === void 0) return fail("Missing --manifest.");
+  const manifest = parsedManifest(raw);
+  if (!manifest.ok) return fail(manifest.message);
+  const extra = unexpected(scanned.positionals, 0);
+  if (extra) return fail(extra);
+  return succeed({ kind: "entry-create", manifest: manifest.manifest });
+}
+function parseUpdate(args) {
+  const scanned = scan(args, /* @__PURE__ */ new Set(["--manifest"]));
+  if (!scanned.ok) return fail(scanned.message);
+  const raw = scanned.flags.get("--manifest");
+  if (raw === void 0) return fail("Missing --manifest.");
+  const manifest = parsedManifest(raw);
+  if (!manifest.ok) return fail(manifest.message);
+  const id = scanned.positionals[0];
+  if (id === void 0) return fail("Missing entry id.");
+  const extra = unexpected(scanned.positionals, 1);
+  if (extra) return fail(extra);
+  return succeed({ kind: "entry-update", id, manifest: manifest.manifest });
+}
+function parseDelete(args) {
+  const scanned = scan(args, /* @__PURE__ */ new Set());
+  if (!scanned.ok) return fail(scanned.message);
+  const id = scanned.positionals[0];
+  if (id === void 0) return fail("Missing entry id.");
+  const extra = unexpected(scanned.positionals, 1);
+  if (extra) return fail(extra);
+  return succeed({ kind: "entry-delete", id });
+}
+function parseFilePut(args) {
+  const scanned = scan(args, /* @__PURE__ */ new Set(["--path"]));
+  if (!scanned.ok) return fail(scanned.message);
+  const path = scanned.flags.get("--path");
+  if (path === void 0) return fail("Missing --path.");
+  const id = scanned.positionals[0];
+  if (id === void 0) return fail("Missing entry id.");
+  const file = scanned.positionals[1];
+  if (file === void 0) return fail("Missing file.");
+  const extra = unexpected(scanned.positionals, 2);
+  if (extra) return fail(extra);
+  return succeed({ kind: "file-put", id, path, file });
+}
+function parseFileRm(args) {
+  const scanned = scan(args, /* @__PURE__ */ new Set());
+  if (!scanned.ok) return fail(scanned.message);
+  const id = scanned.positionals[0];
+  if (id === void 0) return fail("Missing entry id.");
+  const path = scanned.positionals[1];
+  if (path === void 0) return fail("Missing path.");
+  const extra = unexpected(scanned.positionals, 2);
+  if (extra) return fail(extra);
+  return succeed({ kind: "file-rm", id, path });
+}
+function parseFile(args) {
+  const action = args[0];
+  const rest = args.slice(1);
+  if (action === "put") return parseFilePut(rest);
+  if (action === "rm") return parseFileRm(rest);
+  return fail("Unknown command.");
+}
+function parseArgv(argv) {
+  const topic = helpTopic(argv);
+  if (topic === "overview" || topic === "entry" || topic === "file") {
+    const explicit = argv.length > 0 && (argv[0] === "help" || argv.includes("--help") || argv.includes("-h"));
+    const text = helpText(topic);
+    if (!explicit) return { ok: false, message: text };
+    return { ok: true, help: text };
+  }
+  if (topic === "unknown") return fail("Unknown help topic. Topics: entry, file.");
+  if (argv[0] !== "entry") return fail("Unknown command.");
+  const action = argv[1];
+  const args = argv.slice(2);
+  if (action === "list") return parseList(args);
+  if (action === "create") return parseCreate(args);
+  if (action === "update") return parseUpdate(args);
+  if (action === "delete") return parseDelete(args);
+  if (action === "file") return parseFile(args);
+  return fail("Unknown command.");
+}
+
+// src/plan.ts
+function authHeader(apiKey) {
+  return { Authorization: `Bearer ${apiKey}` };
+}
+function jsonHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`,
+    "Content-Type": "application/json"
+  };
+}
+function entryUrl(apiUrl, id) {
+  const base = `${apiUrl}/api/v1/entries`;
+  return id === void 0 ? base : `${base}/${encodeURIComponent(id)}`;
+}
+function planCommand(config, command, nonce) {
+  switch (command.kind) {
+    case "entry-list":
+      return {
+        kind: "http",
+        request: {
+          method: "GET",
+          url: entryUrl(config.apiUrl),
+          headers: authHeader(config.apiKey)
+        }
+      };
+    case "entry-create":
+      return {
+        kind: "http",
+        request: {
+          method: "POST",
+          url: entryUrl(config.apiUrl),
+          headers: jsonHeaders(config.apiKey),
+          body: JSON.stringify({ manifest: command.manifest })
+        }
+      };
+    case "entry-update":
+      return {
+        kind: "http",
+        request: {
+          method: "PATCH",
+          url: entryUrl(config.apiUrl, command.id),
+          headers: jsonHeaders(config.apiKey),
+          body: JSON.stringify({ manifest: command.manifest })
+        }
+      };
+    case "entry-delete":
+      return {
+        kind: "http",
+        request: {
+          method: "DELETE",
+          url: entryUrl(config.apiUrl, command.id),
+          headers: authHeader(config.apiKey)
+        }
+      };
+    case "file-rm":
+      return {
+        kind: "http",
+        request: {
+          method: "DELETE",
+          url: `${entryUrl(config.apiUrl, command.id)}/files`,
+          headers: jsonHeaders(config.apiKey),
+          body: JSON.stringify({ path: command.path })
+        }
+      };
+    case "file-put": {
+      const pathname = `entries/${command.id}/${nonce}/${command.path}`;
+      return {
+        kind: "file-put",
+        pathname,
+        access: "private",
+        handleUploadUrl: `${entryUrl(config.apiUrl, command.id)}/blob`,
+        clientPayload: JSON.stringify({ path: command.path }),
+        headers: authHeader(config.apiKey),
+        register: {
+          method: "POST",
+          url: `${entryUrl(config.apiUrl, command.id)}/files`,
+          headers: jsonHeaders(config.apiKey),
+          body: JSON.stringify({ path: command.path, pathname })
+        }
+      };
+    }
+  }
+}
+
+// src/transfer.ts
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+var maximumFileBytes = 100 * 1024 * 1024;
+var partSizeBytes = 8 * 1024 * 1024;
+var transferAttempts = 5;
+var TransferFailure = class extends Error {
+  status;
+  attempts;
+  constructor(message, status, attempts = 1) {
+    super(message);
+    this.name = "TransferFailure";
+    this.status = status;
+    this.attempts = attempts;
+  }
+};
+function fileSizeError(size) {
+  if (size <= maximumFileBytes) return null;
+  return `File is ${size} bytes. A single file must be 100 MB (${maximumFileBytes} bytes) or smaller.`;
+}
+function planParts(size, partSize = partSizeBytes) {
+  if (size === 0) return [{ partNumber: 1, start: 0, end: 0 }];
+  const parts = [];
+  let start = 0;
+  let partNumber = 1;
+  while (start < size) {
+    const end = Math.min(start + partSize, size);
+    parts.push({ partNumber, start, end });
+    start = end;
+    partNumber += 1;
+  }
+  return parts;
+}
+function retryDelayMs(attempt) {
+  return 200 * 2 ** (attempt - 1);
+}
+function checkpointId(input) {
+  return createHash("sha256").update(JSON.stringify([input.apiUrl, input.entryId, input.path, input.file])).digest("hex");
+}
+function checkpointFilePath(home, id) {
+  if (!/^[a-f0-9]{64}$/.test(id)) throw new Error("Invalid checkpoint id.");
+  return join(home, ".refract9", "uploads", `${id}.json`);
+}
+function parseCheckpoint(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isCheckpoint(value)) return null;
+  return value;
+}
+async function putFile(config, command, io) {
+  const notes = [];
+  let progressPath = null;
+  try {
+    const info = await io.stat(command.file);
+    const sizeError = fileSizeError(info.size);
+    if (sizeError) return { exitCode: 1, stdout: "", stderr: withNewline(sizeError) };
+    const id = checkpointId({
+      apiUrl: config.apiUrl,
+      entryId: command.id,
+      path: command.path,
+      file: command.file
+    });
+    const save = async (checkpoint2) => {
+      await io.writeCheckpoint(id, `${JSON.stringify(checkpoint2, null, 2)}
+`);
+      progressPath = io.checkpointPath(id);
+    };
+    let checkpoint = await loadCheckpoint(io, id, config, command, info, notes);
+    let sessionToken = null;
+    if (checkpoint) {
+      progressPath = io.checkpointPath(id);
+    } else {
+      const opened = await openUpload(io, config, command, info, notes, save);
+      checkpoint = opened.checkpoint;
+      sessionToken = opened.token;
+    }
+    const resumedRegistration = checkpoint.phase === "registering";
+    if (!resumedRegistration) {
+      const step = await uploadParts(io, config, command, checkpoint, sessionToken, notes, save);
+      if (step.done) return { exitCode: 0, stdout: step.stdout, stderr: noted(notes) };
+      checkpoint = step.checkpoint;
+    }
+    if (resumedRegistration) notes.push("Resuming file registration.");
+    const plan = filePlan(config, command, checkpoint.nonce);
+    const pathname = checkpoint.registerPathname ?? checkpoint.pathname;
+    const stdout = await registerFile(io, plan.register, command.path, pathname, (attempt) => {
+      notes.push(`Retrying file registration (attempt ${attempt + 1} of ${transferAttempts}).`);
+    });
+    await io.removeCheckpoint(id);
+    return { exitCode: 0, stdout, stderr: noted(notes) };
+  } catch (error) {
+    return failureResult(error, progressPath);
+  }
+}
+async function sendWithRetry(io, request) {
+  const notes = [];
+  try {
+    const response = await withRetry(
+      io,
+      async () => {
+        const result = await io.fetch(request.url, {
+          method: request.method,
+          headers: request.headers,
+          ...request.body === void 0 ? {} : { body: request.body }
+        });
+        if (result.status >= 400) {
+          const message = result.text.length > 0 ? result.text : `Request failed (${result.status}).`;
+          throw new TransferFailure(message, result.status);
+        }
+        return result;
+      },
+      (attempt) => {
+        notes.push(`Retrying request (attempt ${attempt + 1} of ${transferAttempts}).`);
+      }
+    );
+    return {
+      exitCode: 0,
+      stdout: response.text.length > 0 ? withNewline(response.text) : "",
+      stderr: noted(notes)
+    };
+  } catch (error) {
+    return failureResult(error, null);
+  }
+}
+async function loadCheckpoint(io, id, config, command, info, notes) {
+  const raw = await io.readCheckpoint(id);
+  if (raw === null) return null;
+  const parsed2 = parseCheckpoint(raw);
+  if (!parsed2) {
+    await io.removeCheckpoint(id);
+    return null;
+  }
+  if (!sameTarget(parsed2, config, command, info)) {
+    notes.push("Local file changed. Starting a new upload.");
+    await io.removeCheckpoint(id);
+    return null;
+  }
+  return parsed2;
+}
+async function openUpload(io, config, command, info, notes, save) {
+  const nonce = io.nonce();
+  const plan = filePlan(config, command, nonce);
+  const token = await issueToken(io, plan, (attempt) => {
+    notes.push(`Retrying upload (attempt ${attempt + 1} of ${transferAttempts}).`);
+  });
+  const opened = await withRetry(
+    io,
+    () => io.createUpload(plan.pathname, token),
+    (attempt) => {
+      notes.push(`Retrying upload (attempt ${attempt + 1} of ${transferAttempts}).`);
+    }
+  );
+  const checkpoint = {
+    version: 1,
+    apiUrl: config.apiUrl,
+    entryId: command.id,
+    path: command.path,
+    file: command.file,
+    size: info.size,
+    mtimeMs: info.mtimeMs,
+    nonce,
+    pathname: plan.pathname,
+    uploadId: opened.uploadId,
+    key: opened.key,
+    parts: [],
+    phase: "uploading",
+    registerPathname: null
+  };
+  await save(checkpoint);
+  return { checkpoint, token };
+}
+async function uploadParts(io, config, command, checkpoint, sessionToken, notes, save) {
+  const plan = filePlan(config, command, checkpoint.nonce);
+  const token = sessionToken ?? await issueToken(io, plan, (attempt) => {
+    notes.push(`Retrying upload (attempt ${attempt + 1} of ${transferAttempts}).`);
+  });
+  const planned = planParts(checkpoint.size);
+  const done = new Set(checkpoint.parts.map((part) => part.partNumber));
+  const pending = planned.filter((part) => !done.has(part.partNumber));
+  if (done.size > 0) {
+    const next = pending[0];
+    notes.push(
+      next ? `Resuming at part ${next.partNumber} of ${planned.length}.` : "Resuming upload completion."
+    );
+  }
+  let current = checkpoint;
+  for (const part of pending) {
+    const uploaded = await withRetry(
+      io,
+      async () => {
+        const body = await io.readRange(command.file, part.start, part.end);
+        return io.uploadPart({
+          pathname: current.pathname,
+          token,
+          key: current.key,
+          uploadId: current.uploadId,
+          partNumber: part.partNumber,
+          body
+        });
+      },
+      (attempt) => {
+        notes.push(
+          `Retrying part ${part.partNumber} (attempt ${attempt + 1} of ${transferAttempts}).`
+        );
+      }
+    );
+    current = {
+      ...current,
+      parts: [...current.parts, { partNumber: uploaded.partNumber, etag: uploaded.etag }]
+    };
+    await save(current);
+  }
+  try {
+    const completed = await withRetry(
+      io,
+      () => io.completeUpload({
+        pathname: current.pathname,
+        token,
+        key: current.key,
+        uploadId: current.uploadId,
+        parts: [...current.parts].sort((left, right) => left.partNumber - right.partNumber)
+      }),
+      (attempt) => {
+        notes.push(`Retrying upload (attempt ${attempt + 1} of ${transferAttempts}).`);
+      }
+    );
+    current = { ...current, phase: "registering", registerPathname: completed.pathname };
+    await save(current);
+    return { done: false, checkpoint: current };
+  } catch (error) {
+    if (!isPermanent(error)) throw error;
+    try {
+      const stdout = await registerFile(
+        io,
+        plan.register,
+        command.path,
+        current.pathname,
+        () => {
+        }
+      );
+      await io.removeCheckpoint(
+        checkpointId({
+          apiUrl: config.apiUrl,
+          entryId: command.id,
+          path: command.path,
+          file: command.file
+        })
+      );
+      return { done: true, stdout };
+    } catch {
+      throw error;
+    }
+  }
+}
+async function issueToken(io, plan, onRetry) {
+  const body = JSON.stringify({
+    type: "blob.generate-client-token",
+    payload: {
+      pathname: plan.pathname,
+      clientPayload: plan.clientPayload,
+      multipart: true
+    }
+  });
+  const text = await withRetry(
+    io,
+    async () => {
+      const result = await io.fetch(plan.handleUploadUrl, {
+        method: "POST",
+        headers: { ...plan.headers, "Content-Type": "application/json" },
+        body
+      });
+      if (result.status >= 400) {
+        const message = result.text.length > 0 ? result.text : `Request failed (${result.status}).`;
+        throw new TransferFailure(message, result.status);
+      }
+      return clientToken(result.text);
+    },
+    onRetry
+  );
+  return text;
+}
+function clientToken(text) {
+  let parsed2;
+  try {
+    parsed2 = JSON.parse(text);
+  } catch {
+    throw new TransferFailure("Client token response was invalid.", 502);
+  }
+  if (!parsed2 || typeof parsed2 !== "object" || !("clientToken" in parsed2)) {
+    throw new TransferFailure("Client token response was invalid.", 502);
+  }
+  const token = parsed2.clientToken;
+  if (typeof token !== "string" || token.length === 0) {
+    throw new TransferFailure("Client token response was invalid.", 502);
+  }
+  return token;
+}
+async function registerFile(io, request, path, pathname, onRetry) {
+  const response = await withRetry(
+    io,
+    async () => {
+      const result = await io.fetch(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body: JSON.stringify({ path, pathname })
+      });
+      if (result.status >= 400) {
+        const message = result.text.length > 0 ? result.text : `Request failed (${result.status}).`;
+        throw new TransferFailure(message, result.status);
+      }
+      return result;
+    },
+    onRetry
+  );
+  return response.text.length > 0 ? withNewline(response.text) : "";
+}
+function filePlan(config, command, nonce) {
+  const plan = planCommand(config, { kind: "file-put", ...command }, nonce);
+  if (plan.kind !== "file-put") throw new Error("Command failed.");
+  return plan;
+}
+function sameTarget(checkpoint, config, command, info) {
+  return checkpoint.apiUrl === config.apiUrl && checkpoint.entryId === command.id && checkpoint.path === command.path && checkpoint.file === command.file && checkpoint.size === info.size && checkpoint.mtimeMs === info.mtimeMs;
+}
+function isRetryableStatus(status) {
+  return status === 408 || status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+}
+function isPermanent(error) {
+  return error instanceof TransferFailure && error.status !== void 0 && !isRetryableStatus(error.status);
+}
+function canRetry(error) {
+  if (error instanceof TransferFailure) {
+    return error.status === void 0 || isRetryableStatus(error.status);
+  }
+  if (error instanceof Error && "code" in error) {
+    const code = String(error.code);
+    if (code === "ENOENT" || code === "EISDIR" || code === "EACCES") return false;
+  }
+  return error instanceof Error;
+}
+async function withRetry(io, run, onRetry) {
+  let last;
+  for (let attempt = 1; attempt <= transferAttempts; attempt += 1) {
+    try {
+      return await run();
+    } catch (error) {
+      last = error;
+      if (!canRetry(error) || attempt === transferAttempts) {
+        if (attempt > 1) {
+          const message = error instanceof Error ? error.message : "Command failed.";
+          const status = error instanceof TransferFailure ? error.status : void 0;
+          throw new TransferFailure(
+            `Failed after ${attempt} attempts: ${message}`,
+            status,
+            attempt
+          );
+        }
+        throw error;
+      }
+      onRetry(attempt);
+      await io.sleep(retryDelayMs(attempt));
+    }
+  }
+  throw last;
+}
+function failureResult(error, progressPath) {
+  const message = error instanceof Error ? error.message : "Command failed.";
+  const text = withNewline(message);
+  if (progressPath === null) return { exitCode: 1, stdout: "", stderr: text };
+  return { exitCode: 1, stdout: "", stderr: `${text}Progress file: ${progressPath}
+` };
+}
+function noted(notes) {
+  if (notes.length === 0) return "";
+  return `${notes.join("\n")}
+`;
+}
+function withNewline(text) {
+  return text.endsWith("\n") ? text : `${text}
+`;
+}
+function isCheckpoint(value) {
+  if (!value || typeof value !== "object") return false;
+  const checkpoint = value;
+  if (checkpoint.version !== 1) return false;
+  if (checkpoint.phase !== "uploading" && checkpoint.phase !== "registering") return false;
+  if (!Array.isArray(checkpoint.parts) || !checkpoint.parts.every(isCompletedPart)) return false;
+  const fields = [
+    "apiUrl",
+    "entryId",
+    "path",
+    "file",
+    "nonce",
+    "pathname",
+    "uploadId",
+    "key"
+  ];
+  for (const field of fields) {
+    if (typeof checkpoint[field] !== "string" || checkpoint[field].length === 0) return false;
+  }
+  if (!Number.isFinite(checkpoint.size) || checkpoint.size < 0) return false;
+  if (!Number.isFinite(checkpoint.mtimeMs)) return false;
+  if (checkpoint.registerPathname !== null && typeof checkpoint.registerPathname !== "string") {
+    return false;
+  }
+  if (checkpoint.phase === "registering" && (checkpoint.registerPathname === null || checkpoint.registerPathname.length === 0)) {
+    return false;
+  }
+  return true;
+}
+function isCompletedPart(value) {
+  if (!value || typeof value !== "object") return false;
+  const part = value;
+  return Number.isInteger(part.partNumber) && part.partNumber > 0 && typeof part.etag === "string" && part.etag.length > 0;
+}
+
+// src/run.ts
+function withNewline2(text) {
+  return text.endsWith("\n") ? text : `${text}
+`;
+}
+async function send(io, request) {
+  const response = await io.fetch(request.url, {
+    method: request.method,
+    headers: request.headers,
+    ...request.body === void 0 ? {} : { body: request.body }
+  });
+  if (response.status >= 400) {
+    const stderr = response.text.length > 0 ? withNewline2(response.text) : `Request failed (${response.status}).
+`;
+    return { exitCode: 1, stdout: "", stderr };
+  }
+  return {
+    exitCode: 0,
+    stdout: response.text.length > 0 ? withNewline2(response.text) : "",
+    stderr: ""
+  };
+}
+async function runCommand(config, command, io) {
+  try {
+    if (command.kind === "file-put") return await putFile(config, command, io);
+    const plan = planCommand(config, command, "");
+    if (plan.kind !== "http") throw new Error("Command failed.");
+    if (command.kind === "file-rm") return await sendWithRetry(io, plan.request);
+    return await send(io, plan.request);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Command failed.";
+    return { exitCode: 1, stdout: "", stderr: withNewline2(message) };
+  }
+}
+
+// src/main.ts
+var parsed = parseArgv(process.argv.slice(2));
+if (!parsed.ok) {
+  process.stderr.write(`${parsed.message}
+`);
+  process.exitCode = 1;
+} else if ("help" in parsed) {
+  process.stdout.write(`${parsed.help}
+`);
+} else {
+  const config = readClientConfig(process.env);
+  if (!config.ok) {
+    process.stderr.write(`${config.message}
+`);
+    process.exitCode = 1;
+  } else {
+    const home = homedir();
+    const io = {
+      nonce: () => randomBytes(16).toString("base64url"),
+      sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+      stat: async (path) => {
+        const info = await stat(path);
+        return { size: info.size, mtimeMs: info.mtimeMs };
+      },
+      readRange: async (path, start, end) => {
+        const handle = await open(path, "r");
+        try {
+          const length = end - start;
+          const buffer = Buffer.alloc(length);
+          const { bytesRead } = await handle.read(buffer, 0, length, start);
+          if (bytesRead !== length) throw new TransferFailure("File changed while reading.", 400);
+          return buffer;
+        } finally {
+          await handle.close();
+        }
+      },
+      readCheckpoint: async (id) => {
+        try {
+          return await readFile(checkpointFilePath(home, id), "utf8");
+        } catch (error) {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT") return null;
+          throw error;
+        }
+      },
+      writeCheckpoint: async (id, body) => {
+        const path = checkpointFilePath(home, id);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, body);
+      },
+      removeCheckpoint: async (id) => {
+        await rm(checkpointFilePath(home, id), { force: true });
+      },
+      checkpointPath: (id) => checkpointFilePath(home, id),
+      createUpload: (pathname, token) => createMultipartUpload(pathname, { access: "private", token }),
+      uploadPart: (part) => uploadPart(part.pathname, Buffer.from(part.body), {
+        access: "private",
+        token: part.token,
+        key: part.key,
+        uploadId: part.uploadId,
+        partNumber: part.partNumber
+      }),
+      completeUpload: (upload) => completeMultipartUpload(upload.pathname, upload.parts, {
+        access: "private",
+        token: upload.token,
+        key: upload.key,
+        uploadId: upload.uploadId
+      }),
+      fetch: async (url, init) => {
+        const response = await fetch(url, init);
+        return { status: response.status, text: await response.text() };
+      }
+    };
+    const result = await runCommand(config.config, parsed.command, io);
+    if (result.stdout.length > 0) process.stdout.write(result.stdout);
+    if (result.stderr.length > 0) process.stderr.write(result.stderr);
+    process.exitCode = result.exitCode;
+  }
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@refract9/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Command-line client for the refract9 HTTP API.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mengtaoxin/refract9.git",
+    "directory": "apps/cli"
+  },
+  "bin": {
+    "refract9": "./dist/main.js"
+  },
+  "files": [
+    "dist/main.js"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "node build.mts"
+  },
+  "dependencies": {
+    "@vercel/blob": "^2.8.2"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  }
+}