dexto 1.14.6 → 2.0.0-beta.1

package/dist/cli/cloud/commands/drive.js

@@ -0,0 +1,321 @@
+// `drive put`: uploads local files and folder trees to Drive, versioning same-named files.
+import { CommandFailure } from '../../failure.js';
+import { randomUUID } from 'node:crypto';
+import { openAsBlob } from 'node:fs';
+import { lstat, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { isJsonObject, stringOption, UsageError, } from '../command.js';
+import { sendBytes } from '../transfer.js';
+import { contentTypeFor, formatBytes, hashFile } from './files.js';
+import { queryWorkspaceTool } from './workspace.js';
+/** How many files upload at once. */
+const CONCURRENCY = 4;
+/** How many times a part, or the completion, is sent before a network failure gives it up. */
+const PART_ATTEMPTS = 3;
+/** How long giving an upload up may take, even after the command was cancelled. */
+const ABORT_TIMEOUT_MS = 10_000;
+/** A Drive item as a list describes it. */
+const ItemSchema = z
+    .object({
+    id: z.string(),
+    kind: z.string(),
+    name: z.string(),
+    parentId: z.string().nullable(),
+    revision: z.number(),
+    sha256: z.string().nullable().default(null),
+    size: z.number().nullable().default(null),
+    trashedAt: z.string().nullable().default(null),
+})
+    .passthrough();
+const UsageSchema = z.object({ limits: z.object({ fileBytes: z.number() }) });
+const PageSchema = z.object({ items: z.array(ItemSchema), nextOffset: z.number().nullable() });
+const FolderSchema = z.object({ item: z.object({ id: z.string() }).passthrough() });
+const Endpoint = z.object({ method: z.string(), url: z.string() });
+/** Where a reserved upload goes: one URL, or, for a large file, its parts and their completion. */
+const ReservedSchema = z.object({
+    upload: z.union([
+        z.object({
+            multipart: z.object({
+                abort: Endpoint,
+                complete: Endpoint,
+                partCount: z.number().int().positive(),
+                partSize: z.number().int().positive(),
+                parts: Endpoint,
+            }),
+        }),
+        Endpoint,
+    ]),
+});
+const put = {
+    arguments: '<paths...>',
+    options: {
+        to: {
+            description: 'The Drive folder to put them in, by id (default: the top of your Drive).',
+            type: 'string',
+            valueName: 'FOLDER_ID',
+        },
+    },
+    path: ['workspace', 'drive', 'put'],
+    summary: 'Upload local files and folders (dotfiles left out) to your Drive; a file already there by name gets a new version, unless its bytes are the same.',
+    async run(context, input) {
+        const to = stringOption(input, 'to') ?? null;
+        const { files, folders } = await collect(input.positionals);
+        const usage = UsageSchema.parse(await queryWorkspaceTool(context, 'dexto_drive', { action: 'usage' }));
+        const limit = usage.limits.fileBytes;
+        const tooLarge = files.filter((file) => file.size > limit);
+        if (tooLarge.length > 0)
+            throw new CommandFailure('invalid_input', `Drive takes files up to ${formatBytes(limit)}, and ${tooLarge
+                .map((file) => `${file.localPath} is ${formatBytes(file.size)}`)
+                .join(', ')}. Leave ${tooLarge.length === 1 ? 'it' : 'them'} out and run it again.`, null);
+        // Listing the destination first fails the run at once when it isn't a folder you can use.
+        const listed = new Map();
+        await listFolder(context, listed, to);
+        // Parents come before their children, so each folder's parent is there by the time it is.
+        const folderIds = new Map();
+        const putFolders = [];
+        for (const folder of folders) {
+            const parentId = folder.parent === null ? to : (folderIds.get(folder.parent) ?? null);
+            const name = path.basename(path.resolve(folder.localPath));
+            const existing = await findItem(context, listed, parentId, 'folder', name);
+            const item = existing ??
+                FolderSchema.parse(await queryWorkspaceTool(context, 'dexto_drive', {
+                    action: 'folder',
+                    name,
+                    parentId,
+                    requestId: randomUUID(),
+                })).item;
+            // A folder made just now has nothing in it to list.
+            if (existing === null)
+                listed.set(item.id, Promise.resolve([]));
+            folderIds.set(folder.localPath, item.id);
+            putFolders.push({
+                item,
+                path: folder.localPath,
+                status: existing === null ? 'created' : 'existing',
+            });
+        }
+        const saved = [];
+        const failed = [];
+        // Files bound for one name in one folder go one after another, each a version of the last.
+        const bound = new Map();
+        for (const file of files) {
+            const parentId = file.folder === null ? to : (folderIds.get(file.folder) ?? null);
+            const key = `${parentId ?? ''}/${path.basename(file.localPath)}`;
+            bound.set(key, [...(bound.get(key) ?? []), file]);
+        }
+        await eachAtOnce([...bound.values()], async (sameName) => {
+            for (const file of sameName) {
+                const parentId = file.folder === null ? to : (folderIds.get(file.folder) ?? null);
+                try {
+                    const existing = await findItem(context, listed, parentId, 'file', path.basename(file.localPath));
+                    const sha256 = await hashFile(file.localPath);
+                    // Drive already has these bytes under this name: nothing to send.
+                    if (existing?.sha256 === sha256 && existing.size === file.size) {
+                        saved.push({ item: existing, path: file.localPath, status: 'unchanged' });
+                        if (!context.output.json)
+                            context.runtime.writeOutput(`Unchanged ${file.localPath} (${formatBytes(file.size)}, ${existing.id})\n`);
+                        continue;
+                    }
+                    const item = await putFile(context, file, parentId, existing, sha256, null);
+                    await remember(listed, parentId, item);
+                    const status = existing === null ? 'created' : 'updated';
+                    saved.push({ item, path: file.localPath, status });
+                    if (!context.output.json)
+                        context.runtime.writeOutput(`${status === 'created' ? 'Created' : 'Updated'} ${file.localPath} (${formatBytes(file.size)}, ${String(item.id)})\n`);
+                }
+                catch (error) {
+                    // A sign-in that can't write fails every file the same way: stop, say so once.
+                    if (error instanceof CommandFailure &&
+                        (error.kind === 'needs_sign_in' || error.kind === 'needs_permission'))
+                        throw error;
+                    const message = error instanceof Error ? error.message : String(error);
+                    failed.push({ error: message, path: file.localPath });
+                    context.runtime.writeError(`Couldn't upload ${file.localPath}: ${message}\n`);
+                }
+            }
+        });
+        const created = saved.filter((each) => each.status === 'created').length;
+        const updated = saved.filter((each) => each.status === 'updated').length;
+        const unchanged = saved.length - created - updated;
+        const madeFolders = putFolders.filter((each) => each.status === 'created').length;
+        context.output.result({
+            created,
+            failed,
+            files: saved,
+            folders: putFolders,
+            unchanged,
+            updated,
+        }, `Uploaded ${created + updated} of ${files.length} file${files.length === 1 ? '' : 's'}: ${created} created, ${updated} updated with a new version${unchanged === 0 ? '' : `, ${unchanged} already up to date`}.${putFolders.length === 0
+            ? ''
+            : ` Folders: ${madeFolders} created, ${putFolders.length - madeFolders} already there.`}`);
+        if (failed.length > 0)
+            throw new CommandFailure('failed', `${failed.length} file${failed.length === 1 ? '' : 's'} didn't upload: ${failed.map((each) => each.path).join(', ')}.`, null);
+    },
+};
+/**
+ * The files and folders the paths name. A folder brings what's in it, except names starting with a
+ * dot and links, which are left out; a path named on its own is taken as it is.
+ */
+async function collect(paths) {
+    const files = [];
+    const folders = [];
+    const visit = async (localPath, parent, named) => {
+        const stats = await (named ? stat(localPath) : lstat(localPath)).catch(() => null);
+        if (stats?.isFile() === true) {
+            files.push({ folder: parent, localPath, size: stats.size });
+            return;
+        }
+        if (stats?.isDirectory() !== true) {
+            if (named)
+                throw new UsageError(`${localPath} is not a file or folder.`);
+            return;
+        }
+        folders.push({ localPath, parent });
+        const names = (await readdir(localPath)).filter((name) => !name.startsWith('.')).sort();
+        for (const name of names)
+            await visit(path.join(localPath, name), localPath, false);
+    };
+    for (const localPath of paths)
+        await visit(localPath, null, true);
+    return { files, folders };
+}
+/** The item of this kind and name in a Drive folder (null for the top), listing it once a run. */
+async function findItem(context, listed, parentId, kind, name) {
+    const items = await listFolder(context, listed, parentId);
+    return items.find((item) => item.kind === kind && item.name === name) ?? null;
+}
+/** Puts what an upload saved in its folder's listing, so the next file of that name versions it. */
+async function remember(listed, parentId, saved) {
+    const item = ItemSchema.safeParse(saved);
+    if (!item.success)
+        return;
+    const key = parentId ?? '';
+    const items = (await listed.get(key)) ?? [];
+    listed.set(key, Promise.resolve([...items.filter((each) => each.id !== item.data.id), item.data]));
+}
+/** Every item in a Drive folder, page by page, trash left out; each folder is listed once. */
+function listFolder(context, listed, parentId) {
+    const known = listed.get(parentId ?? '');
+    if (known !== undefined)
+        return known;
+    const listing = (async () => {
+        const items = [];
+        for (let offset = 0; offset !== null;) {
+            const page = PageSchema.parse(await queryWorkspaceTool(context, 'dexto_drive', {
+                action: 'list',
+                offset,
+                parentId,
+            }));
+            items.push(...page.items.filter((item) => item.trashedAt === null));
+            offset = page.nextOffset;
+        }
+        return items;
+    })();
+    listed.set(parentId ?? '', listing);
+    return listing;
+}
+/**
+ * Reserves one file in Drive under a new request id, as a new version of `existing` when there is
+ * one, then sends its bytes to the URL Drive returns. A file too large for one request would be
+ * sent in parts here, once Drive takes them.
+ */
+async function putFile(context, file, parentId, existing, sha256, 
+/** The app whose own folder the file goes into instead, which gives the app the file. */
+appId) {
+    const mimeType = contentTypeFor(file.localPath);
+    const reserved = ReservedSchema.safeParse(await queryWorkspaceTool(context, 'dexto_drive', {
+        action: 'upload',
+        ...(appId === null ? {} : { appId }),
+        mimeType,
+        name: path.basename(file.localPath),
+        requestId: randomUUID(),
+        sha256,
+        size: file.size,
+        ...(existing === null
+            ? { parentId }
+            : {
+                expectedRevision: existing.revision,
+                parentId: existing.parentId,
+                targetId: existing.id,
+            }),
+    }));
+    if (!reserved.success)
+        throw new CommandFailure('failed', "Drive didn't say where to send the file.", null);
+    const { upload } = reserved.data;
+    const bytes = await openAsBlob(file.localPath);
+    const reply = 'multipart' in upload
+        ? await sendParts(context, upload.multipart, bytes)
+        : await sendBytes(context, { headers: { 'content-type': mimeType }, method: upload.method, url: upload.url }, bytes);
+    return isJsonObject(reply) && isJsonObject(reply.item) ? reply.item : {};
+}
+/**
+ * Uploads one local file into an app's own Drive folder, which gives the app the file to refer to
+ * as `drive:<id>`.
+ */
+export async function putAppFile(context, localPath, appId) {
+    const info = await stat(localPath).catch(() => null);
+    if (info === null || !info.isFile())
+        throw new UsageError(`Can't read ${localPath}: give a file's path, or a link.`);
+    const item = await putFile(context, { folder: null, localPath, size: info.size }, null, null, await hashFile(localPath), appId);
+    if (typeof item.id !== 'string')
+        throw new CommandFailure('failed', `Drive didn't return ${localPath}'s file.`, null);
+    return { id: item.id, mimeType: contentTypeFor(localPath), name: path.basename(localPath) };
+}
+/**
+ * Sends a large file in the exact parts Drive asked for, a few at once, then completes it. A part
+ * or completion the network drops is sent again; one that still fails, or is refused, gives the
+ * upload up at once, so it holds no quota until it expires, even when the command was cancelled.
+ */
+async function sendParts(context, plan, bytes) {
+    const numbers = Array.from({ length: plan.partCount }, (_, index) => index + 1);
+    try {
+        await eachAtOnce(numbers, async (number) => {
+            await sendRetrying(context, { headers: {}, method: plan.parts.method, url: `${plan.parts.url}/${number}` }, bytes.slice((number - 1) * plan.partSize, number * plan.partSize), 1);
+        });
+        return await sendRetrying(context, { headers: {}, method: plan.complete.method, url: plan.complete.url }, new globalThis.Blob([]), 1);
+    }
+    catch (error) {
+        // Its own signal: the command's is already aborted when Ctrl-C ended the upload.
+        await context.runtime
+            .fetch(plan.abort.url, {
+            method: plan.abort.method,
+            signal: AbortSignal.timeout(ABORT_TIMEOUT_MS),
+        })
+            .catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * Sends a part or the completion, again after a second and then two when the network drops it.
+ * Drive keeps the last copy of a part sent twice and completes an upload once; a refusal stands.
+ */
+async function sendRetrying(context, target, body, attempt) {
+    try {
+        return await sendBytes(context, target, body);
+    }
+    catch (error) {
+        // fetch rejects with a TypeError when the request never got a response.
+        if (!(error instanceof TypeError) || attempt === PART_ATTEMPTS)
+            throw error;
+        await context.runtime.sleep(1000 * attempt);
+        return await sendRetrying(context, target, body, attempt + 1);
+    }
+}
+/** Runs `run` over the items, a few at once; the first error it throws stops the rest. */
+async function eachAtOnce(items, run) {
+    let next = 0;
+    const worker = async () => {
+        for (let item = items[next++]; item !== undefined; item = items[next++]) {
+            try {
+                await run(item);
+            }
+            catch (error) {
+                next = items.length;
+                throw error;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, items.length) }, worker));
+}
+export const driveCommands = [put];

package/dist/cli/cloud/commands/files.d.ts

@@ -0,0 +1,24 @@
+import { type V1Response } from '@dexto/cloud-client';
+import { type Command, type CommandContext } from '../command.js';
+type CloudFile = V1Response<'/v1/files/{file_id}', 'get'>;
+export interface FileUpload {
+    readonly body: globalThis.Blob;
+    readonly contentType: string;
+    readonly expiresAt: string | null;
+    readonly overwrite: boolean;
+    readonly path: string;
+    readonly sha256: string;
+}
+/**
+ * Uploads a file: in one request up to 80 MiB, otherwise in parts through an upload session,
+ * aborted when a part fails.
+ */
+export declare function uploadFile(context: CommandContext, upload: FileUpload): Promise<CloudFile>;
+/** A local file's SHA-256, hex, read as a stream. */
+export declare function hashFile(localPath: string): Promise<string>;
+/** The media type for a local file, by its extension. */
+export declare function contentTypeFor(localPath: string): string;
+export declare function formatBytes(bytes: number): string;
+export declare const fileCommands: readonly Command[];
+export {};
+//# sourceMappingURL=files.d.ts.map

package/dist/cli/cloud/commands/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../../src/cli/cloud/commands/files.ts"],"names":[],"mappings":"AAUA,OAAO,EAA4B,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EASH,KAAK,OAAO,EACZ,KAAK,cAAc,EACtB,MAAM,eAAe,CAAC;AAIvB,KAAK,SAAS,GAAG,UAAU,CAAC,qBAAqB,EAAE,KAAK,CAAC,CAAC;AAgL1D,MAAM,WAAW,UAAU;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CA4DhG;AA2BD,qDAAqD;AACrD,wBAAsB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAIjE;AAwBD,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjD;AAED,eAAO,MAAM,YAAY,EAAE,SAAS,OAAO,EAA+C,CAAC"}

package/dist/cli/cloud/commands/files.js

@@ -0,0 +1,284 @@
+// `cloud files`: upload, download, share and delete the project's files.
+import { CommandFailure } from '../../failure.js';
+import { requireConsent } from '../../interaction.js';
+import { createHash } from 'node:crypto';
+import { createReadStream, createWriteStream, openAsBlob } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { Writable } from 'node:stream';
+import { unwrap } from '@dexto/cloud-client';
+import { argument, flag, integerOption, PAGE_OPTIONS, pageQuery, stringOption, UsageError, YES_OPTION, } from '../command.js';
+import { sendV1, v1Failure } from '../v1.js';
+/** Larger files go up in parts, through an upload session. */
+const ONE_REQUEST_MAX_BYTES = 80 * 1024 * 1024;
+const COLUMNS = [
+    { header: 'id', value: (file) => file.id },
+    { header: 'path', value: (file) => file.path },
+    { header: 'size', value: (file) => formatBytes(file.size_bytes) },
+    { header: 'type', value: (file) => file.content_type },
+    { header: 'updated', value: (file) => file.updated_at },
+];
+const list = {
+    options: {
+        ...PAGE_OPTIONS,
+        contains: { description: 'Only paths containing this text.', type: 'string' },
+        prefix: { description: 'Only paths starting with this, such as reports/.', type: 'string' },
+    },
+    path: ['cloud', 'files', 'list'],
+    summary: "List the project's files.",
+    async run(context, input) {
+        const prefix = stringOption(input, 'prefix');
+        const contains = stringOption(input, 'contains');
+        const page = await unwrap(await (await context.client()).GET('/v1/files', {
+            params: {
+                query: {
+                    ...pageQuery(input),
+                    ...(prefix === undefined ? {} : { prefix }),
+                    ...(contains === undefined ? {} : { contains }),
+                },
+            },
+        }));
+        context.output.list(page, COLUMNS);
+    },
+};
+const get = {
+    arguments: '<file>',
+    path: ['cloud', 'files', 'get'],
+    summary: 'Show a file by id or path.',
+    async run(context, input) {
+        const client = await context.client();
+        context.output.record(await getFile(client, await resolveFileId(client, argument(input, 0, 'file'))));
+    },
+};
+const upload = {
+    arguments: '<local_path> [path]',
+    options: {
+        'content-type': {
+            description: 'The media type (default from the extension).',
+            type: 'string',
+        },
+        'expires-at': {
+            description: 'Delete the file at this ISO 8601 time.',
+            type: 'string',
+            valueName: 'TIME',
+        },
+        overwrite: { description: 'Replace a file already at the path.', type: 'boolean' },
+    },
+    path: ['cloud', 'files', 'upload'],
+    summary: 'Upload a local file to a project path (default: its file name).',
+    async run(context, input) {
+        const localPath = argument(input, 0, 'local_path');
+        if (!(await stat(localPath).catch(() => null))?.isFile())
+            throw new UsageError(`${localPath} is not a file.`);
+        const body = await openAsBlob(localPath).catch((error) => {
+            throw new UsageError(`Cannot read ${localPath}: ${error instanceof Error ? error.message : 'unknown error'}.`);
+        });
+        const expiresAt = stringOption(input, 'expires-at');
+        const file = await uploadFile(context, {
+            body,
+            contentType: stringOption(input, 'content-type') ?? contentTypeFor(localPath),
+            expiresAt: expiresAt ?? null,
+            overwrite: flag(input, 'overwrite'),
+            path: input.positionals[1] ?? path.basename(localPath),
+            sha256: await hashFile(localPath),
+        });
+        context.output.result(file, `Uploaded ${file.path} (${formatBytes(file.size_bytes)}, ${file.id}).`);
+    },
+};
+const download = {
+    arguments: '<file> [local_path]',
+    path: ['cloud', 'files', 'download'],
+    summary: 'Download a file by id or path to a local path (default: its file name), or - for stdout.',
+    async run(context, input) {
+        const client = await context.client();
+        const fileId = await resolveFileId(client, argument(input, 0, 'file'));
+        const file = await getFile(client, fileId);
+        const target = input.positionals[1] ?? path.basename(file.path);
+        const { data, response } = await client.GET('/v1/files/{file_id}/content', {
+            params: { path: { file_id: fileId } },
+            parseAs: 'stream',
+        });
+        if (!response.ok || data === undefined || data === null)
+            throw v1Failure(context, response.status, await response.text().catch(() => ''));
+        if (target === '-') {
+            const reader = data.getReader();
+            for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read())
+                await context.runtime.writeBytes(chunk.value);
+            return;
+        }
+        await data.pipeTo(Writable.toWeb(createWriteStream(target)));
+        context.output.result({ ...file, local_path: target }, `Saved ${file.path} to ${target}.`);
+    },
+};
+const url = {
+    arguments: '<file>',
+    options: {
+        'expires-in': {
+            description: 'Seconds the URL works, up to 86400 (default 3600).',
+            type: 'string',
+            valueName: 'SECONDS',
+        },
+    },
+    path: ['cloud', 'files', 'url'],
+    summary: 'Create a URL anyone can read the file from until it expires.',
+    async run(context, input) {
+        const client = await context.client();
+        const expiresIn = integerOption(input, 'expires-in');
+        const result = await unwrap(await client.POST('/v1/files/{file_id}/url', {
+            params: {
+                path: { file_id: await resolveFileId(client, argument(input, 0, 'file')) },
+            },
+            body: expiresIn === undefined ? {} : { expires_in: expiresIn },
+        }));
+        context.output.result(result, result.url);
+    },
+};
+const remove = {
+    arguments: '<file>',
+    options: YES_OPTION,
+    path: ['cloud', 'files', 'delete'],
+    summary: 'Delete a file by id or path.',
+    async run(context, input) {
+        await requireConsent(context, flag(input, 'yes'), `Deleting ${argument(input, 0, 'file')} can't be undone.`);
+        const client = await context.client();
+        const result = await unwrap(await client.DELETE('/v1/files/{file_id}', {
+            params: {
+                path: { file_id: await resolveFileId(client, argument(input, 0, 'file')) },
+            },
+        }));
+        context.output.result(result, `Deleted file ${result.id}.`);
+    },
+};
+async function getFile(client, fileId) {
+    return await unwrap(await client.GET('/v1/files/{file_id}', { params: { path: { file_id: fileId } } }));
+}
+/**
+ * Uploads a file: in one request up to 80 MiB, otherwise in parts through an upload session,
+ * aborted when a part fails.
+ */
+export async function uploadFile(context, upload) {
+    if (upload.body.size <= ONE_REQUEST_MAX_BYTES) {
+        const query = new URLSearchParams({ path: upload.path });
+        if (upload.overwrite)
+            query.set('overwrite', 'true');
+        if (upload.expiresAt !== null)
+            query.set('expires_at', upload.expiresAt);
+        const response = await sendV1(context, 'POST', `/v1/files?${query}`, {
+            body: upload.body,
+            headers: {
+                accept: 'application/json',
+                'content-type': upload.contentType,
+                'content-length': String(upload.body.size),
+                'x-content-sha256': upload.sha256,
+            },
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw v1Failure(context, response.status, text);
+        return JSON.parse(text);
+    }
+    const client = await context.client();
+    const session = await unwrap(await client.POST('/v1/files/uploads', {
+        body: {
+            content_type: upload.contentType,
+            overwrite: upload.overwrite,
+            path: upload.path,
+            sha256: upload.sha256,
+            size_bytes: upload.body.size,
+            ...(upload.expiresAt === null ? {} : { expires_at: upload.expiresAt }),
+        },
+    }));
+    const params = { params: { path: { upload_id: session.id } } };
+    try {
+        if (session.upload_url === null)
+            throw new CommandFailure('failed', 'The upload session has no upload URL.', null);
+        // `parts` lists the parts already uploaded; send every other one of `part_count`.
+        const uploaded = new Set(session.parts.map((part) => part.part_number));
+        for (let partNumber = 1; partNumber <= session.part_count; partNumber += 1) {
+            if (uploaded.has(partNumber))
+                continue;
+            const start = (partNumber - 1) * session.part_size_bytes;
+            const response = await context.runtime.fetch(`${session.upload_url}/${partNumber}`, {
+                body: upload.body.slice(start, Math.min(start + session.part_size_bytes, session.size_bytes)),
+                method: 'PUT',
+                signal: context.runtime.signal,
+            });
+            if (!response.ok)
+                throw new CommandFailure('failed', `Part ${partNumber} of the upload was refused (HTTP ${response.status}).`, null);
+        }
+        return await unwrap(await client.POST('/v1/files/uploads/{upload_id}/complete', params));
+    }
+    catch (error) {
+        await client.POST('/v1/files/uploads/{upload_id}/abort', params).catch(() => undefined);
+        throw error;
+    }
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+/**
+ * A file id as given, or the id of the file at a path. The API addresses files only by id, so a
+ * path is found by listing its prefix.
+ */
+async function resolveFileId(client, file) {
+    if (UUID.test(file))
+        return file;
+    let after;
+    for (;;) {
+        const page = await unwrap(await client.GET('/v1/files', {
+            params: {
+                query: { limit: 1000, prefix: file, ...(after === undefined ? {} : { after }) },
+            },
+        }));
+        const match = page.data.find((each) => each.path === file);
+        if (match !== undefined)
+            return match.id;
+        if (!page.has_more || page.next_after === null)
+            break;
+        after = page.next_after;
+    }
+    throw new CommandFailure('not_found', `No file at ${file}.`, null);
+}
+/** A local file's SHA-256, hex, read as a stream. */
+export async function hashFile(localPath) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(localPath))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+const CONTENT_TYPES = {
+    '.csv': 'text/csv',
+    '.gif': 'image/gif',
+    '.html': 'text/html',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.json': 'application/json',
+    '.m4v': 'video/mp4',
+    '.md': 'text/markdown',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.txt': 'text/plain',
+    '.wav': 'audio/wav',
+    '.webm': 'video/webm',
+    '.webp': 'image/webp',
+    '.zip': 'application/zip',
+};
+/** The media type for a local file, by its extension. */
+export function contentTypeFor(localPath) {
+    return CONTENT_TYPES[path.extname(localPath).toLowerCase()] ?? 'application/octet-stream';
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KiB', 'MiB', 'GiB'];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value.toFixed(1)} ${units[unit]}`;
+}
+export const fileCommands = [list, get, upload, download, url, remove];

package/dist/cli/cloud/commands/find.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from '../command.js';
+export declare const findCommands: readonly Command[];
+//# sourceMappingURL=find.d.ts.map

package/dist/cli/cloud/commands/find.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../../src/cli/cloud/commands/find.ts"],"names":[],"mappings":"AAEA,OAAO,EAA2C,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAmFtF,eAAO,MAAM,YAAY,EAAE,SAAS,OAAO,EAAW,CAAC"}