@orchestraworks/cli 0.8.0 → 0.9.0

package/dist/cli/api/execute.js

@@ -13,7 +13,7 @@ import { findCommand } from "../../generated/cli-commands.js";
 import { CLI_DISPATCH } from "../../generated/cli-dispatch.js";
 import { authFlagsFrom, platformTargetFrom, resolveAnonymousBaseUrl, resolveAuthWithWarnings, } from "../core/auth.js";
 import { readCredentialFromCommandLine, readCredentialFromEnv } from "../core/credential-input.js";
-import { contentSourceFieldsIn, uploadFile } from "../upload.js";
+import { contentSourceFieldsIn, inlineFileOf, storeInlineFile, uploadFile } from "../upload.js";
 import { readBodyDocument } from "../core/invocation.js";
 import { defaultIo, parseOutputMode, printResponse, printWarnings, } from "../core/output.js";
 import { createPlatformApis } from "../core/platform-client.js";
@@ -24,25 +24,6 @@ import { ensureWriteApproved, IMPERATIVE_APPROVAL_DEFAULT, managedResourceWarnin
 const ANONYMOUS_NOUN = "health";
 /** The item mutations that pre-read for the managed marker: neither carries it in request or response. */
 const MANAGED_WARNING_VERBS = new Set(["update", "delete"]);
-/**
- * Operations whose answer is a redirect to the bytes themselves. `fetch` follows it, so what this executor
- * reads back IS the content — but the operation declares a body of its own nowhere, and without this the
- * shared reader treats an unvouched byte body as material to withhold and prints a sentinel instead of the
- * file. Hand-maintained: every entry is an operation whose success response is a bare-content redirect.
- */
-const BARE_CONTENT_OPERATIONS = new Set(["getFileContent"]);
-/** What those operations effectively answer: the content itself, which streams raw and is never masked. */
-const BARE_CONTENT_SCHEMA = { kind: "scalar" };
-/**
- * The schema the reader and the redactor are both handed — `orchestra api` included, so the raw caller and the
- * typed command cannot disagree about which responses are the bare content.
- */
-export function responseSchemaOf(row) {
-    if (row === undefined) {
-        return undefined;
-    }
-    return BARE_CONTENT_OPERATIONS.has(row.operationId) ? BARE_CONTENT_SCHEMA : row.responseSchema;
-}
 /** Named so the error mapper prints the sentence and nothing else — no platform framing, no stack. */
 export class CommandUsageError extends Error {
     constructor(message) {
@@ -80,9 +61,7 @@ export async function executeCommand(row, invocation, deps = {}, ctx = {}) {
     }
     // The WHOLE target goes to the shared client, including the credential session, so a command that
     // outlives its access token renews it in flight instead of failing halfway through.
-    const apis = createPlatformApis(target, deps.fetchApi, {
-        warn: (lines) => printWarnings(lines, io),
-    });
+    const apis = createPlatformApis(target, invocation.conventions.markdown === true ? acceptingMarkdown(deps.fetchApi) : deps.fetchApi, { warn: (lines) => printWarnings(lines, io) });
     // (2, 3) Compose and validate the invocation.
     const composed = composeRequest(row, invocation, env, deps);
     refuseDoubledContentSource(row, invocation, composed);
@@ -105,8 +84,8 @@ export async function executeCommand(row, invocation, deps = {}, ctx = {}) {
     // file that does not exist yet. It runs after the gate because storing bytes is itself a write.
     const stored = await storeDeclaredFile(row, invocation, composed.body, apis, target, deps, io);
     if (stored !== undefined) {
-        // The upload already made this row's own create and completed it, so there is no second call to
-        // make: `--file` stores one file, and the command answers the one it stored.
+        // The store already made this row's own create, so there is no second call to make: `--file` stores
+        // one file, and the command answers the one it stored.
         writeOutputFile(invocation, stored.body, io);
         const storedRedaction = redactBody(stored.body, stored.schema, invocation.conventions.reveal === true);
         printResponse(storedRedaction === undefined ? stored.body : storedRedaction.rendered, {
@@ -133,7 +112,7 @@ export async function executeCommand(row, invocation, deps = {}, ctx = {}) {
         return;
     }
     const response = await dispatch(row.operationId)(apis, dispatchArgs);
-    const responseSchema = responseSchemaOf(row);
+    const responseSchema = row.responseSchema;
     const raw = await readRawBody(response.raw, responseSchema);
     if (writeOutputFile(invocation, raw, io) && raw instanceof Uint8Array) {
         return;
@@ -312,34 +291,69 @@ function refuseDoubledContentSource(row, invocation, composed) {
  * Nothing happens without `--file`.
  *
  * Where the row names a file by id, the create that follows is handed that id and this answers nothing.
- * Where the row DECLARES the upload itself — `sha256`, `sizeBytes` — the upload has already made exactly
- * that create and completed it, so this answers the stored row and the command prints it. Writing those
- * fields into a create that then runs again declared a SECOND file, which nothing completed and which
- * `--output json` printed: two rows for one `--file`, and the wrong one shown.
+ * Where the row DECLARES the upload itself — `sha256`, `sizeBytes` — the store IS that create, so this
+ * answers the stored row and the command prints it. Writing those fields into a create that then runs again
+ * declared a SECOND file, which nothing completed and which `--output json` printed: two rows for one
+ * `--file`, and the wrong one shown.
  */
 async function storeDeclaredFile(row, invocation, body, apis, target, deps, io) {
     const path = invocation.conventions.file;
     if (path === undefined || body === undefined) {
         return undefined;
     }
-    const uploaded = await uploadFile(path, {
+    const namesFile = row.flags.some((flag) => flag.name === "file-id");
+    // The one create describes one file: what it says about the name and the type governs the store too, so
+    // the bytes cannot land as something the create did not ask for.
+    const named = { filename: stringField(body, "filename"), contentType: stringField(body, "contentType") };
+    const inline = inlineFileOf(path, named);
+    if (inline !== undefined && !namesFile) {
+        Object.assign(body, inline);
+        return await createInline(row, invocation, body, apis, target);
+    }
+    const placement = {
         apis,
-        fetchApi: (deps.fetchApi ?? fetch),
         io,
         organizationId: target.organizationId,
-        teamId: stringField(body, "teamId") ??
-            (await ownerTeam(row, invocation, apis, target.organizationId)),
-        // The one create describes one file: what it says about the name and the type governs both calls, so
-        // the upload cannot land as something the create did not ask for.
-        filename: stringField(body, "filename"),
-        contentType: stringField(body, "contentType"),
+        teamId: stringField(body, "teamId") ?? (await ownerTeam(row, invocation, apis, target.organizationId)),
+    };
+    if (inline !== undefined) {
+        body["fileId"] = await storeInlineFile(inline, placement);
+        return undefined;
+    }
+    const uploaded = await uploadFile(path, {
+        ...placement,
+        ...named,
+        fetchApi: (deps.fetchApi ?? fetch),
+        ...(namesFile ? {} : { request: body }),
     });
-    if (row.flags.some((flag) => flag.name === "file-id")) {
+    if (namesFile) {
         body["fileId"] = uploaded.fileId;
         return undefined;
     }
+    if (stringField(body, "path") !== undefined && uploaded.completion !== undefined) {
+        // The complete saved the library file at the path and answered it, so there is nothing to read back.
+        const schema = findCommand(row.noun, "complete-upload")?.responseSchema;
+        return { body: await readRawBody(uploaded.completion, schema), schema };
+    }
     return await readStoredFile(row, invocation, apis, target, uploaded.fileId);
 }
+/** The row's own create, carrying the file's text as `content`; it answers `{file}`, and the file is printed. */
+async function createInline(row, invocation, body, apis, target) {
+    const response = await dispatch(row.operationId)(apis, {
+        pathParams: invocation.pathParams,
+        query: {},
+        body: toWireValue(body),
+        ...(target.organizationId !== undefined ? { organizationId: target.organizationId } : {}),
+    });
+    const answer = await readRawBody(response.raw, row.responseSchema);
+    const file = typeof answer === "object" && answer !== null && !Array.isArray(answer)
+        ? answer["file"]
+        : undefined;
+    if (file === undefined || row.responseSchema?.kind !== "object") {
+        return { body: answer, schema: row.responseSchema };
+    }
+    return { body: file, schema: row.responseSchema.fields["file"]?.schema };
+}
 /**
  * The stored row as this noun's own read answers it, printed bare as every other create prints what it
  * made, so `.id` names the new file. There is no upload locator to print beside it: the bytes are pushed.
@@ -354,7 +368,7 @@ async function readStoredFile(row, invocation, apis, target, fileId) {
         query: {},
         ...(target.organizationId !== undefined ? { organizationId: target.organizationId } : {}),
     });
-    const schema = responseSchemaOf(read);
+    const schema = read.responseSchema;
     return { body: await readRawBody(response.raw, schema), schema };
 }
 /**
@@ -505,6 +519,19 @@ function sameItemPath(sibling, row) {
     }
     return sibling.positionals.every((positional, index) => positional.param === row.positionals[index]?.param);
 }
+/**
+ * The platform answers an HTML or Markdown file's content as Markdown when the request accepts it, and the
+ * generated client sends no `Accept` of its own, so this one header is the whole of `--markdown`.
+ */
+function acceptingMarkdown(fetchApi) {
+    const inner = (fetchApi ?? fetch);
+    const wrapped = (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set("Accept", "text/markdown");
+        return inner(input, { ...init, headers });
+    };
+    return wrapped;
+}
 function dispatch(operationId) {
     const entry = CLI_DISPATCH[operationId];
     if (entry === undefined) {

package/dist/cli/api/raw.d.ts

@@ -57,7 +57,9 @@ export declare function assertPlatformOrigin(baseUrl: string, path: string): str
 /**
  * `undefined` when this build cannot resolve the path — an endpoint newer than the CLI, or one outside the
  * public document. Matching is method-sensitive and template-aware, with query string and fragment dropped
- * first: they select data, never an operation.
+ * first: they select data, never an operation. Where two templates match, a literal segment beats a
+ * parameter at the first place they differ, so `/files/matches` is the search and not a read of a file
+ * whose id is `matches`.
  */
 export declare function resolveRawCommand(method: string, path: string): CommandRow | undefined;
 /**

package/dist/cli/api/raw.js

@@ -17,7 +17,7 @@ import { sendRawPlatformRequest } from "../core/platform-client.js";
 import { redact, redactBinaryBody, writeResponseFile, } from "../core/redaction.js";
 import { resolveApprovalPolicy } from "../core/approval-policy.js";
 import { classifyWrite, ensureApproved, IMPERATIVE_APPROVAL_DEFAULT, printApprovalBypassNotice, } from "./approval.js";
-import { readRawBody, responseSchemaOf } from "./execute.js";
+import { readRawBody } from "./execute.js";
 /**
  * Deliberately the five that address resources: `OPTIONS`/`HEAD`/`TRACE` answer questions about the
  * transport rather than the platform, and accepting one only converts a typo into a confusing 405.
@@ -92,8 +92,8 @@ async function sendRawCall(method, path, options, deps, ctx) {
     });
     // The reader and {@link redactRawBody} have to agree about which responses are bare content, or the body
     // the redactor would stream raw is one the reader has already parsed into something else — so both are
-    // handed the SAME schema, the typed executor's bare-content exemptions included.
-    const responseSchema = responseSchemaOf(row);
+    // handed the SAME schema, the row's own, exactly as the typed executor is.
+    const responseSchema = row?.responseSchema;
     const body = await readRawBody(response, responseSchema);
     if (options.outputFile !== undefined) {
         writeResponseFile(options.outputFile, body, io);
@@ -189,11 +189,38 @@ function readRequestDocument(method, options, deps) {
 /**
  * `undefined` when this build cannot resolve the path — an endpoint newer than the CLI, or one outside the
  * public document. Matching is method-sensitive and template-aware, with query string and fragment dropped
- * first: they select data, never an operation.
+ * first: they select data, never an operation. Where two templates match, a literal segment beats a
+ * parameter at the first place they differ, so `/files/matches` is the search and not a read of a file
+ * whose id is `matches`.
  */
 export function resolveRawCommand(method, path) {
     const segments = pathSegments(path);
-    return CLI_COMMANDS.find((row) => row.method === method && matchesTemplate(row.path, segments));
+    let best;
+    for (const row of CLI_COMMANDS) {
+        if (row.method !== method || !matchesTemplate(row.path, segments)) {
+            continue;
+        }
+        if (best === undefined || moreLiteral(row.path, best.path)) {
+            best = row;
+        }
+    }
+    return best;
+}
+/** True when `template` has a literal segment where `other`, of the same length, first has a parameter. */
+function moreLiteral(template, other) {
+    const parts = pathSegments(template);
+    const otherParts = pathSegments(other);
+    for (let index = 0; index < parts.length; index += 1) {
+        const literal = !isParameter(parts[index] ?? "");
+        const otherLiteral = !isParameter(otherParts[index] ?? "");
+        if (literal !== otherLiteral) {
+            return literal;
+        }
+    }
+    return false;
+}
+function isParameter(segment) {
+    return segment.startsWith("{") && segment.endsWith("}");
 }
 function pathSegments(path) {
     const withoutQuery = path.split(/[?#]/)[0] ?? "";
@@ -205,7 +232,7 @@ function matchesTemplate(template, segments) {
     if (parts.length !== segments.length) {
         return false;
     }
-    return parts.every((part, index) => part.startsWith("{") && part.endsWith("}") ? true : part === segments[index]);
+    return parts.every((part, index) => isParameter(part) || part === segments[index]);
 }
 /**
  * Reported as FULL paths, so the refusal names a property a reader can find in their file.

package/dist/cli/api/register.js

@@ -49,6 +49,7 @@ function registerRow(group, row, options) {
                 reveal: values["reveal"] === true,
                 outputFile: optional(values["outputFile"]),
                 file: optional(values["file"]),
+                markdown: values["markdown"] === true,
                 approveSecrets: values["approveSecrets"] === true ? true : undefined,
                 requireApproval: optional(values["requireApproval"]),
                 profile: optional(values["profile"]),
@@ -99,11 +100,15 @@ function registerConventionFlags(command, row) {
     command.option("--reveal", "print credential material in full instead of masking it");
     command.option("--output-file <path>", "write the full raw response to <path> (mode 0600; JSON, or the bytes for file content)");
     if (rowTakesFileOption(row)) {
-        command.option("--file <path>", "upload the bytes at <path> and let this create name them, instead of saying where they are");
+        command.option("--file <path>", "store the file at <path> (text up to 256 KiB inline, anything else uploaded) and let this create " +
+            "name it, instead of saying where its bytes are");
     }
     if (row.pageWindow !== undefined) {
         command.option("--all-pages", "follow every page and concatenate the items");
     }
+    if (row.markdownResponse === true) {
+        command.option("--markdown", "ask for the content as Markdown (sends Accept: text/markdown)");
+    }
     if (row.method !== "GET") {
         command.option("--approve-secrets", "pre-approve the sensitive-write confirmation");
         // A read verb gets NEITHER of these: it has no approval to configure, so the flag is an unknown option

package/dist/cli/preview.d.ts

@@ -39,8 +39,9 @@ export declare function previewCommand(file: string, options?: PreviewCommandOpt
 /**
  * The policy the artifacts host serves a published page under, mirrored here so a page that reaches for
  * something production forbids — an outbound fetch, a script from an unlisted source, a nested frame —
- * fails in the rehearsal rather than after it is published. The one substitution is the frame ancestor:
- * the console's origin there, the preview's own here. `test/cli/preview.test.ts` reads the platform's
- * own source and fails when the two drift.
+ * fails in the rehearsal rather than after it is published. Two substitutions: the frame ancestor is the
+ * console's origin there and the preview's own here, and the store origin, where the host points what a page
+ * loads by a relative path, is blank here, as a rehearsal has no store and points nothing at one.
+ * `test/cli/preview.test.ts` reads the platform's own source and fails when the two drift.
  */
-export declare function pageContentSecurityPolicy(consoleOrigin: string): string;
+export declare function pageContentSecurityPolicy(consoleOrigin: string, storeOrigin?: string): string;

package/dist/cli/preview.js

@@ -180,12 +180,15 @@ const OPENING_BYTES = 1024;
 /**
  * The policy the artifacts host serves a published page under, mirrored here so a page that reaches for
  * something production forbids — an outbound fetch, a script from an unlisted source, a nested frame —
- * fails in the rehearsal rather than after it is published. The one substitution is the frame ancestor:
- * the console's origin there, the preview's own here. `test/cli/preview.test.ts` reads the platform's
- * own source and fails when the two drift.
+ * fails in the rehearsal rather than after it is published. Two substitutions: the frame ancestor is the
+ * console's origin there and the preview's own here, and the store origin, where the host points what a page
+ * loads by a relative path, is blank here, as a rehearsal has no store and points nothing at one.
+ * `test/cli/preview.test.ts` reads the platform's own source and fails when the two drift.
  */
-export function pageContentSecurityPolicy(consoleOrigin) {
+export function pageContentSecurityPolicy(consoleOrigin, storeOrigin = "") {
     const ancestor = consoleOrigin.trim() === "" ? "'none'" : consoleOrigin.trim();
+    const store = storeOrigin.trim();
+    const media = store === "" ? "'none'" : store;
     return [
         "default-src 'none'",
         "sandbox allow-scripts allow-popups",
@@ -194,11 +197,14 @@ export function pageContentSecurityPolicy(consoleOrigin) {
         "frame-src 'none'",
         `frame-ancestors ${ancestor}`,
         "script-src 'self' 'unsafe-inline' https://cdnjs.cloudflare.com https://cdn.jsdelivr.net" +
-            " https://cdn.tailwindcss.com https://code.jquery.com",
-        "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
-        "img-src 'self' data:",
-        "font-src https://fonts.gstatic.com",
-    ].join("; ");
+            ` https://cdn.tailwindcss.com https://code.jquery.com ${store}`,
+        `style-src 'self' 'unsafe-inline' https://fonts.googleapis.com ${store}`,
+        `img-src 'self' data: ${store}`,
+        `media-src ${media}`,
+        `font-src https://fonts.gstatic.com ${store}`,
+    ]
+        .map((directive) => directive.trim())
+        .join("; ");
 }
 function originOf(server, host) {
     return `http://${host ?? "127.0.0.1"}:${server.address().port}`;

package/dist/cli/upload.d.ts

@@ -1,6 +1,8 @@
 import type { CommandRow } from "../generated/cli-commands.js";
 import type { CliApis } from "../generated/cli-dispatch.js";
 import type { CliIo } from "./core/output.js";
+/** The most `content` the platform takes inline, counted in UTF-8 bytes. */
+export declare const INLINE_LIMIT_BYTES: number;
 /**
  * A row `--file` attaches to, decided by what the ROW declares rather than by its noun and verb, because
  * this file has no business knowing either.
@@ -21,6 +23,14 @@ export interface UploadedFile {
     readonly filename: string;
     /** True when the platform already held these bytes, so this call stored nothing. */
     readonly alreadyStored: boolean;
+    /** The complete call's unread answer, when one was sent: for a save by path, the library file it saved. */
+    readonly completion?: Response;
+}
+/** A local file a create can carry as its own `content`, with the name and type the create gives it. */
+export interface InlineFile {
+    readonly content: string;
+    readonly filename: string;
+    readonly contentType: string;
 }
 export interface UploadOptions {
     /**
@@ -36,7 +46,23 @@ export interface UploadOptions {
     readonly teamId?: string | undefined;
     readonly filename?: string | undefined;
     readonly contentType?: string | undefined;
+    /**
+     * The create's own fields when the upload is that create. A `path` among them makes the declare an upload
+     * intent, which is completed even when the platform answers no plan, since only the complete saves it.
+     */
+    readonly request?: Readonly<Record<string, unknown>> | undefined;
 }
+/**
+ * The file's text when a create can carry it inline, unchanged: at most {@link INLINE_LIMIT_BYTES} of UTF-8,
+ * with no NUL, which the platform cannot store as text, and not blank. A byte order mark stays in the text,
+ * so the stored bytes are the file's own.
+ */
+export declare function inlineFileOf(path: string, named?: {
+    filename?: string | undefined;
+    contentType?: string | undefined;
+}): InlineFile | undefined;
+/** Stores the text as a fixed file in one create, for a create that names it by id next. */
+export declare function storeInlineFile(file: InlineFile, options: Pick<UploadOptions, "apis" | "io" | "organizationId" | "teamId">): Promise<string>;
 export declare function uploadFile(path: string, options: UploadOptions): Promise<UploadedFile>;
 /**
  * What the file is, read off its name. The store keeps whatever it is told, and the console decides how to

package/dist/cli/upload.js

@@ -1,14 +1,15 @@
-// The whole behaviour of `--file`: bytes on disk become a stored platform file, in the four steps the
-// platform's upload contract names — declare the address, push the bytes the answer authorizes, complete,
-// and hand the caller the file id the create then names.
+// The whole behaviour of `--file`: bytes on disk become a stored platform file. A small text travels inline
+// as the create's own `content`; anything else takes the four steps the platform's upload contract names —
+// declare the address, push the bytes the answer authorizes, complete, and hand the caller the file id the
+// create then names.
 //
-// Two rules here are not style. The bytes are STREAMED from disk in both shapes, so a file larger than
-// memory uploads exactly like a small one. And a presigned request is sent through the BARE fetch rather
-// than the platform client: the signed headers travel verbatim, the platform bearer never reaches the
-// object store, and the CLI's 60-second request bound — right for an API call, wrong for a long transfer —
-// does not apply.
+// Two rules here are not style. A declared upload's bytes are STREAMED from disk in both shapes, so a file
+// larger than memory uploads exactly like a small one. And a presigned request is sent through the BARE
+// fetch rather than the platform client: the signed headers travel verbatim, the platform bearer never
+// reaches the object store, and the CLI's 60-second request bound — right for an API call, wrong for a long
+// transfer — does not apply.
 import { createHash } from "node:crypto";
-import { createReadStream, statSync } from "node:fs";
+import { createReadStream, readFileSync, statSync } from "node:fs";
 import { basename, extname } from "node:path";
 import { Readable } from "node:stream";
 /** Parts in flight at once. */
@@ -24,6 +25,13 @@ const DECLARE_ATTEMPTS = 2;
 const CONTENT_SOURCE_FIELDS = ["content", "fileId", "url"];
 /** The platform's own default for a declared upload that named no type. */
 const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/** The most `content` the platform takes inline, counted in UTF-8 bytes. */
+export const INLINE_LIMIT_BYTES = 256 * 1024;
+/**
+ * Blank as the platform judges `content`, widened to JavaScript's own whitespace, so a text the platform
+ * would refuse as blank goes through a declared upload instead.
+ */
+const BLANK = /^[\s\u001c-\u001f]*$/;
 /**
  * A row `--file` attaches to, decided by what the ROW declares rather than by its noun and verb, because
  * this file has no business knowing either.
@@ -50,19 +58,52 @@ class UploadError extends Error {
 /** Raised by a push whose signature the store no longer honours; the only failure a fresh declare repairs. */
 class PlanExpiredError extends Error {
 }
+/**
+ * The file's text when a create can carry it inline, unchanged: at most {@link INLINE_LIMIT_BYTES} of UTF-8,
+ * with no NUL, which the platform cannot store as text, and not blank. A byte order mark stays in the text,
+ * so the stored bytes are the file's own.
+ */
+export function inlineFileOf(path, named = {}) {
+    if (statOf(path).size > INLINE_LIMIT_BYTES) {
+        return undefined;
+    }
+    const bytes = readFileSync(path);
+    if (bytes.byteLength > INLINE_LIMIT_BYTES) {
+        return undefined;
+    }
+    let content;
+    try {
+        content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+    if (content.includes("\u0000") || BLANK.test(content)) {
+        return undefined;
+    }
+    const filename = named.filename ?? basename(path);
+    return { content, filename, contentType: named.contentType ?? contentTypeOf(filename) };
+}
+/** Stores the text as a fixed file in one create, for a create that names it by id next. */
+export async function storeInlineFile(file, options) {
+    const stored = await options.apis.files.createFile({
+        createFileRequest: { ...file, ...(options.teamId !== undefined ? { teamId: options.teamId } : {}) },
+        ...(options.organizationId !== undefined ? { xOrganizationId: options.organizationId } : {}),
+    });
+    options.io.err(`note: stored ${file.filename} (${Buffer.byteLength(file.content, "utf8")} bytes) inline as ${stored.file.id}.`);
+    return stored.file.id;
+}
 export async function uploadFile(path, options) {
     const stats = statOf(path);
-    if (stats.size === 0) {
-        throw new UploadError(`--file ${path} is empty; there are no bytes to upload.`);
-    }
     const filename = options.filename ?? basename(path);
     const contentType = options.contentType ?? contentTypeOf(filename);
     const sha256 = await sha256Of(path);
+    const intent = typeof options.request?.["path"] === "string";
     for (let attempt = 1;; attempt += 1) {
         const declared = await declare(path, { ...options, filename, contentType }, sha256, stats.size);
         try {
             const parts = await push(declared, path, stats.size, options);
-            await complete(declared, parts, options);
+            const completion = await complete(declared, intent ? (parts ?? []) : parts, options);
             report(declared, parts, filename, stats.size, options.io);
             return {
                 fileId: declared.file.id,
@@ -71,6 +112,7 @@ export async function uploadFile(path, options) {
                 contentType,
                 filename,
                 alreadyStored: parts === undefined,
+                ...(completion !== undefined ? { completion } : {}),
             };
         }
         catch (failure) {
@@ -106,6 +148,7 @@ async function sha256Of(path) {
 async function declare(path, options, sha256, sizeBytes) {
     return await options.apis.files.createFile({
         createFileRequest: {
+            ...options.request,
             sha256,
             sizeBytes,
             filename: options.filename,
@@ -185,7 +228,10 @@ async function putRange(locator, path, start, end, length, options) {
     for (const [name, value] of Object.entries(locator.headers)) {
         headers.set(name, value);
     }
-    const body = Readable.toWeb(createReadStream(path, { start, end }));
+    // A read stream refuses an empty range, so an empty file pushes an empty body.
+    const body = length === 0
+        ? new Uint8Array(0)
+        : Readable.toWeb(createReadStream(path, { start, end }));
     let response;
     try {
         response = await options.fetchApi(locator.url, {
@@ -213,14 +259,15 @@ async function putRange(locator, path, start, end, length, options) {
 }
 async function complete(declared, parts, options) {
     if (parts === undefined) {
-        return;
+        return undefined;
     }
     // `files complete-upload` generates no flags of its own, so this is the one caller of the SDK method.
-    await options.apis.files.completeFileUpload({
+    const response = await options.apis.files.completeFileUploadRaw({
         id: declared.file.id,
         completeFileUploadRequest: { parts },
         ...(options.organizationId !== undefined ? { xOrganizationId: options.organizationId } : {}),
     });
+    return response.raw;
 }
 /** One line for the whole transfer, whatever it took — a line per part would bury the command's own output. */
 function report(declared, parts, filename, sizeBytes, io) {
@@ -241,6 +288,7 @@ export function contentTypeOf(filename) {
     return CONTENT_TYPES[extname(filename).toLowerCase()] ?? DEFAULT_CONTENT_TYPE;
 }
 const CONTENT_TYPES = {
+    ".uri": "text/uri-list",
     ".html": "text/html",
     ".htm": "text/html",
     ".css": "text/css",

package/dist/generated/cli-commands.d.ts

@@ -55,6 +55,11 @@ export interface CommandRow {
         readonly kind: "page" | "cursor";
         readonly param: string;
     };
+    /**
+     * Present when a success response declares `text/markdown`, so the command takes `--markdown`, which sends
+     * `Accept: text/markdown`.
+     */
+    readonly markdownResponse?: true;
 }
 /** One flag. A credential field registers the `-from-env`/`-from-command-line` PAIR and no plain flag. */
 export interface FlagSpec {