dexto 1.14.4 → 2.0.0-beta.0

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

@@ -0,0 +1,223 @@
+// `cloud sites` and `cloud functions`: pack a project with its own packer, deploy, list and delete.
+import { access, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+import { argument, CommandFailure, flag, MissingScopeFailure, requireConsent, stringOption, UsageError, YES_OPTION, } from '../command.js';
+import { callV1 } from '../v1.js';
+const PACKER = path.join('.dexto', 'pack.mjs');
+const PROVIDERS = ['cloudflare-workers', 'aws-lambda'];
+const SiteSchema = z.object({
+    id: z.string(),
+    slug: z.string(),
+    url: z.string(),
+    visibility: z.string(),
+});
+const FunctionSchema = z.object({
+    access: z.string(),
+    id: z.string(),
+    slug: z.string(),
+    status: z.string(),
+    url: z.string().nullable(),
+});
+const DeployedSiteSchema = z.object({
+    deployment: z.object({ id: z.string() }),
+    promoted: z.boolean(),
+    site: z.object({ id: z.string(), slug: z.string() }),
+    url: z.string(),
+});
+const DeployedFunctionSchema = z.object({
+    deployment: z.object({ id: z.string(), preview_url: z.string() }),
+    dexto: z.object({ configured: z.boolean(), scopes: z.array(z.string()) }).nullable(),
+    function: z.object({ id: z.string(), slug: z.string() }),
+    promoted: z.boolean(),
+    url: z.string().nullable(),
+});
+const DEPLOY_OPTIONS = {
+    'no-promote': {
+        description: 'Deploy a preview to promote later, instead of making it live.',
+        type: 'boolean',
+    },
+    provider: {
+        description: `Where its Function runs: ${PROVIDERS.join(' or ')}. Omit for the default.`,
+        type: 'string',
+        valueName: 'PROVIDER',
+    },
+};
+const deploySite = {
+    arguments: '[dir]',
+    options: DEPLOY_OPTIONS,
+    path: ['cloud', 'sites', 'deploy'],
+    summary: 'Pack the Site in dir (default: here) with its packer and deploy it to the Cloud project; it goes live unless --no-promote.',
+    async run(context, input) {
+        await requireLoginScopes(context, ['sites:write', 'cloud:write']);
+        // Options are checked before packing, which can build and rewrite project files.
+        const query = deployQuery(input, {});
+        const packed = await pack(context, input.positionals[0], 'site');
+        const deployed = DeployedSiteSchema.parse(await callV1(context, 'POST', `/v1/sites/deployments?${query}`, packed));
+        context.output.result(deployed, deployed.promoted
+            ? `Deployed ${deployed.site.slug} to ${deployed.url} (deployment ${deployed.deployment.id}).`
+            : `Deployed a preview of ${deployed.site.slug} at ${deployed.url}. Make it live with: dexto cloud api POST /v1/sites/${deployed.site.id}/deployments/${deployed.deployment.id}/promote`);
+    },
+};
+const deployFunction = {
+    arguments: '[dir]',
+    options: {
+        ...DEPLOY_OPTIONS,
+        public: {
+            description: 'Let anyone on the internet reach it. Functions are private by default.',
+            type: 'boolean',
+        },
+    },
+    path: ['cloud', 'functions', 'deploy'],
+    summary: 'Pack the Function in dir (default: here) with its packer and deploy it to the Cloud project; it goes live unless --no-promote.',
+    async run(context, input) {
+        await requireLoginScopes(context, ['functions:write', 'cloud:write']);
+        // Options are checked before packing, which can build and rewrite project files.
+        const query = deployQuery(input, {
+            access: flag(input, 'public') ? 'public' : 'private',
+        });
+        const packed = await pack(context, input.positionals[0], 'function');
+        const deployed = DeployedFunctionSchema.parse(await callV1(context, 'POST', `/v1/functions/deployments?${query}`, packed));
+        const key = deployed.dexto === null || deployed.dexto.configured
+            ? ''
+            : ` Its Dexto key was not bound: your sign-in lacks ${deployed.dexto.scopes.join(', ')}.`;
+        context.output.result(deployed, deployed.promoted
+            ? `Deployed ${deployed.function.slug}${deployed.url === null ? '' : ` to ${deployed.url}`} (deployment ${deployed.deployment.id}).${key}`
+            : `Deployed ${deployed.function.slug} without making it live; preview at ${deployed.deployment.preview_url}. Make it live with: dexto cloud api POST /v1/functions/${deployed.function.id}/deployments/${deployed.deployment.id}/promote${key}`);
+    },
+};
+const SITE_COLUMNS = [
+    { header: 'id', value: (site) => site.id },
+    { header: 'slug', value: (site) => site.slug },
+    { header: 'visibility', value: (site) => site.visibility },
+    { header: 'url', value: (site) => site.url },
+];
+const FUNCTION_COLUMNS = [
+    { header: 'id', value: (deployed) => deployed.id },
+    { header: 'slug', value: (deployed) => deployed.slug },
+    { header: 'status', value: (deployed) => deployed.status },
+    { header: 'access', value: (deployed) => deployed.access },
+    { header: 'url', value: (deployed) => deployed.url },
+];
+const listSites = {
+    path: ['cloud', 'sites', 'list'],
+    summary: "List the Cloud project's Sites.",
+    async run(context) {
+        await requireLoginScopes(context, ['sites:read']);
+        const page = z
+            .object({ data: z.array(SiteSchema) })
+            .parse(await callV1(context, 'GET', '/v1/sites', null));
+        context.output.list(page, SITE_COLUMNS);
+    },
+};
+const deleteSite = {
+    arguments: '<site>',
+    options: YES_OPTION,
+    path: ['cloud', 'sites', 'delete'],
+    summary: 'Delete a Site of the Cloud project, by id or slug, with its deployments and data; its slug is free again. Asks first.',
+    async run(context, input) {
+        // The Site is found by listing, which takes sites:read, before it is deleted.
+        await requireLoginScopes(context, ['sites:read', 'sites:write', 'cloud:write']);
+        const wanted = argument(input, 0, 'site');
+        const sites = z
+            .object({ data: z.array(SiteSchema) })
+            .parse(await callV1(context, 'GET', '/v1/sites', null)).data;
+        const site = sites.find((each) => each.id === wanted || each.slug === wanted);
+        if (site === undefined)
+            throw new CommandFailure('not_found', `The Cloud project has no Site ${wanted}.`, 'dexto cloud sites list');
+        await requireConsent(context, flag(input, 'yes'), `This deletes ${site.slug} (${site.url}) with its deployments and data. It can't be undone.`);
+        await callV1(context, 'DELETE', `/v1/sites/${encodeURIComponent(site.id)}`, null);
+        context.output.result({ deleted: true, id: site.id, slug: site.slug }, `Deleted ${site.slug}. Its slug is free to deploy again.`);
+    },
+};
+const listFunctions = {
+    path: ['cloud', 'functions', 'list'],
+    summary: "List the Cloud project's Functions.",
+    async run(context) {
+        await requireLoginScopes(context, ['functions:read']);
+        const page = z
+            .object({ data: z.array(FunctionSchema) })
+            .parse(await callV1(context, 'GET', '/v1/functions', null));
+        context.output.list(page, FUNCTION_COLUMNS);
+    },
+};
+/**
+ * A person's sign-in needs the kind's permission, and to deploy also `cloud:write`, which the API
+ * checks first; asking for every missing one at once lets a single sign-in cover the command. A
+ * deploy spends credits, so running one is asking for `cloud:write`. At a terminal the CLI then
+ * offers to sign in again for them. A key's permissions are checked by the API.
+ */
+export async function requireLoginScopes(context, scopes) {
+    const connection = await context.connection();
+    if (connection.kind !== 'oauth')
+        return;
+    const missing = scopes.filter((scope) => !connection.login.scopes.includes(scope));
+    if (missing.length === 0)
+        return;
+    throw new MissingScopeFailure(context, missing.join(','), missing.length === 1
+        ? `This needs the ${missing[0]} permission, which your sign-in lacks.`
+        : `This needs the ${missing.join(' and ')} permissions, which your sign-in lacks.`);
+}
+function deployQuery(input, extra) {
+    const provider = stringOption(input, 'provider');
+    if (provider !== undefined && !PROVIDERS.some((each) => each === provider))
+        throw new UsageError(`--provider must be ${PROVIDERS.join(' or ')}.`);
+    return new URLSearchParams({
+        ...extra,
+        promote: flag(input, 'no-promote') ? 'false' : 'true',
+        ...(provider === undefined ? {} : { provider }),
+    });
+}
+/**
+ * Runs the project's own packer, `.dexto/pack.mjs`, or its `pack` script when it has none, into a
+ * temporary file, and returns the deploy request it wrote once it is the kind asked for.
+ */
+async function pack(context, dir, kind) {
+    const projectDir = path.resolve(dir ?? '.');
+    const outputDir = await mkdtemp(path.join(tmpdir(), 'dexto-pack-'));
+    const outputPath = path.join(outputDir, 'deploy-request.json');
+    try {
+        const ownPacker = await exists(path.join(projectDir, PACKER));
+        const [command, args] = ownPacker
+            ? ['node', [PACKER, '.', '--out', outputPath]]
+            : ['pnpm', ['run', 'pack', '.', '--out', outputPath]];
+        context.output.note(`Packing ${projectDir} with ${ownPacker ? PACKER : 'pnpm run pack'}…`);
+        const packed = await context.runtime.runProcess(command, args, { cwd: projectDir });
+        if (packed.exitCode !== 0)
+            throw new CommandFailure('invalid_input', `Packing failed:\n${packed.output.trim()}`, null);
+        const text = await readFile(outputPath, 'utf8').catch(() => {
+            throw new CommandFailure('failed', `The packer wrote no deploy request to ${outputPath}.`, null);
+        });
+        const packedKind = packageKind(text);
+        if (packedKind !== kind)
+            throw new UsageError(`${projectDir} packs a ${packedKind}. Deploy it with dexto cloud ${packedKind}s deploy.`);
+        return text;
+    }
+    finally {
+        await rm(outputDir, { force: true, recursive: true });
+    }
+}
+/** A Site's deploy request has pages (`assets`); a Function's has none. */
+function packageKind(text) {
+    const parsed = JSON.parse(text);
+    return typeof parsed === 'object' && parsed !== null && 'assets' in parsed
+        ? 'site'
+        : 'function';
+}
+async function exists(file) {
+    try {
+        await access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const deployCommands = [
+    deploySite,
+    listSites,
+    deleteSite,
+    deployFunction,
+    listFunctions,
+];

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

@@ -0,0 +1,12 @@
+import { type Command, type CommandContext } from '../command.js';
+/**
+ * Uploads one local file into an app's own Drive folder, which gives the app the file to refer to
+ * as `drive:<id>`.
+ */
+export declare function putAppFile(context: CommandContext, localPath: string, appId: string): Promise<{
+    id: string;
+    mimeType: string;
+    name: string;
+}>;
+export declare const driveCommands: readonly Command[];
+//# sourceMappingURL=drive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"drive.d.ts","sourceRoot":"","sources":["../../../../src/cli/cloud/commands/drive.ts"],"names":[],"mappings":"AASA,OAAO,EAKH,KAAK,OAAO,EACZ,KAAK,cAAc,EACtB,MAAM,eAAe,CAAC;AA4VvB;;;GAGG;AACH,wBAAsB,UAAU,CAC5B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAezD;AAwED,eAAO,MAAM,aAAa,EAAE,SAAS,OAAO,EAAU,CAAC"}

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

@@ -0,0 +1,320 @@
+// `drive put`: uploads local files and folder trees to Drive, versioning same-named files.
+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 { CommandFailure, 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":"AAOA,OAAO,EAA4B,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAWH,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"}