disk 0.8.18 → 0.8.19

package/README.md

@@ -1,6 +1,6 @@
 # disk
 
-Node.js client and CLI for [Archil](https://archil.com) disks. Create disks, list and inspect them, manage who can mount them, and run commands against them — all from scripts, CI, or an interactive terminal.
+SDK and CLI for [Archil](https://archil.com) disks. Create disks, list and inspect them, manage who can mount them, and run commands against them — all from scripts, CI, or an interactive terminal. It also ships **drop-in [filesystem tools](#filesystem-tools)** for AI SDK, Mastra, and Langchain.
 
 `disk` talks to the Archil control plane over HTTPS and has no native dependencies. If you also want to mount a disk's data plane from Node (rare — most users want `disk exec` or the `archil` CLI), install [`@archildata/native`](https://www.npmjs.com/package/@archildata/native) alongside `disk`.
 
@@ -41,7 +41,7 @@ npx disk api-keys delete key-abc123
 
 ## Library
 
-The recommended pattern is a module-namespace import:
+Setup:
 
 ```ts
 import * as archil from "disk";
@@ -213,14 +213,6 @@ console.log(url); // https://control.…/api/shared/<token>
 const weekLink = await d.share("reports/2026-01/summary.pdf", { expiresIn: 604800 });
 ```
 
-### Named imports
-
-If you prefer named imports over the namespace style, they work the same way:
-
-```ts
-import { createDisk, getDisk, listDisks, configure } from "disk";
-```
-
 ### Multiple accounts or regions
 
 For multi-tenant scripts, instantiate `Archil` directly instead of using the module-level `configure`:
@@ -235,6 +227,61 @@ const prodDisks = await prod.disks.list();
 const stagingDisks = await staging.disks.list();
 ```
 
+## Filesystem tools
+
+Support for providing agents with a set of tools for using an Archil disk live in their own `@archildata/*` packages.
+| Package | Framework |
+| --- | --- |
+| `@archildata/ai-sdk` | AI SDK |
+| `@archildata/eve` | eve |
+| `@archildata/mastra` | Mastra |
+| `@archildata/langchain` | LangChain / LangGraph |
+
+## Workspaces
+For usage with multiple disks, you can create a workspace, which acts as a virtual disk where each mounted disk appears as a top-level directory:
+
+```ts
+import { Archil } from "disk";
+
+const archil = new Archil();
+const source = await archil.disks.get(process.env.ARCHIL_SOURCE_DISK_ID!);
+const output = await archil.disks.get(process.env.ARCHIL_OUTPUT_DISK_ID!);
+
+const workspace = archil.workspace({
+  source: { disk: source, readOnly: true },
+  output,
+});
+```
+
+Workspace paths route to the right disk by their first segment. `readOnly` mounts
+return an error from operations that mutate the disk.
+
+Workspace mounts can also request delegations:
+
+```ts
+const workspace = archil.workspace({
+  repo: {
+    disk: repoDisk,
+    checkoutPaths: ["src", "tmp/cache"],
+    queueMs: 5_000,
+  },
+});
+```
+
+When `queueMs` is set without `checkoutPaths`, the mount root is acquired
+during mount setup instead.
+
+A `Workspace` is a full filesystem in its own right — it has the same object API
+a `Disk` does (`getObject` / `putObject` / `deleteObject` / `listObjects` /
+`grep` / `exec`; both implement the `FileSystem` interface), so you can use it
+directly, and add or remove disks at runtime. A
+workspace's keys carry the disk name as their first segment:
+
+```ts
+const data = await ws.getObject("data/reports/q1.csv"); // routes to the "data" disk
+ws.addDisk("scratch", diskTmp); // mount another disk live; ws.removeDisk("scratch")
+```
+
 ## Connecting to a disk's data plane
 
 To run a command against a disk, use `Disk.exec()` — it returns stdout, stderr, and an exit code from an Archil-managed container with the disk pre-mounted. No local filesystem involved.

package/dist/cli.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+import { c as listDisks, i as deleteApiKey, n as createApiKey, o as getDisk, r as createDisk, s as listApiKeys, t as configure, y as ArchilApiError } from "./src--b7LHPh_.mjs";
+import { createRequire } from "node:module";
+import { Command, Option } from "commander";
+//#region bin/cli.ts
+const pkg = createRequire(import.meta.url)("../package.json");
+const program = new Command();
+program.name("disk").description("Manage Archil disks from the command line").version(pkg.version).addOption(new Option("-k, --api-key <key>", "Archil API key").env("ARCHIL_API_KEY")).addOption(new Option("-r, --region <region>", "Archil region").env("ARCHIL_REGION")).addOption(new Option("--base-url <url>", "Override control-plane base URL")).hook("preAction", () => {
+	const opts = program.opts();
+	try {
+		configure({
+			apiKey: opts.apiKey,
+			region: opts.region,
+			baseUrl: opts.baseUrl
+		});
+	} catch (err) {
+		fail(err);
+	}
+});
+function fail(err) {
+	if (err instanceof ArchilApiError) console.error(`Error (${err.status}): ${err.message}`);
+	else console.error(err instanceof Error ? err.message : String(err));
+	process.exit(1);
+}
+function isDiskId(s) {
+	return /^(dsk-|fs-)[0-9a-fA-F]+$/.test(s);
+}
+async function resolveDisk(idOrName) {
+	if (isDiskId(idOrName)) return getDisk(idOrName);
+	const matches = await listDisks({ name: idOrName });
+	if (matches.length === 0) throw new ArchilApiError(`No disk found with name '${idOrName}'`, 404);
+	if (matches.length > 1) throw new ArchilApiError(`Multiple disks match name '${idOrName}' — pass a disk id (dsk-...) instead`, 400);
+	return matches[0];
+}
+function formatBytes(n) {
+	if (n === void 0 || n === null) return void 0;
+	if (n < 1024) return `${n} B`;
+	const units = [
+		"KB",
+		"MB",
+		"GB",
+		"TB",
+		"PB"
+	];
+	let v = n / 1024;
+	let i = 0;
+	while (v >= 1024 && i < units.length - 1) {
+		v /= 1024;
+		i++;
+	}
+	return `${v.toFixed(v >= 100 ? 0 : v >= 10 ? 1 : 2)} ${units[i]}`;
+}
+function renderTable(rows, headers) {
+	const all = headers ? [headers, ...rows] : rows;
+	if (all.length === 0) return "";
+	const cols = Math.max(...all.map((r) => r.length));
+	const widths = [];
+	for (let i = 0; i < cols; i++) widths[i] = Math.max(...all.map((r) => (r[i] ?? "").length));
+	const bar = (l, m, r) => l + widths.map((w) => "─".repeat(w + 2)).join(m) + r;
+	const line = (r) => "│ " + widths.map((w, i) => (r[i] ?? "").padEnd(w)).join(" │ ") + " │";
+	const out = [bar("╭", "┬", "╮")];
+	if (headers) {
+		out.push(line(headers));
+		out.push(bar("├", "┼", "┤"));
+	}
+	for (const r of rows) out.push(line(r));
+	out.push(bar("╰", "┴", "╯"));
+	return out.join("\n");
+}
+function section(title, body) {
+	console.log("");
+	console.log(title);
+	console.log(body);
+}
+function printDisk(d) {
+	console.log(`${d.organization}/${d.name}  (${d.id})`);
+	const visible = [
+		["status", d.status],
+		["provider", d.provider],
+		["region", d.region],
+		["created", d.createdAt],
+		["last accessed", d.lastAccessed],
+		["data size", formatBytes(d.dataSize)],
+		["monthly usage", d.monthlyUsage]
+	].filter(([, v]) => v !== void 0 && v !== null && v !== "").map(([k, v]) => [k, String(v)]);
+	console.log("");
+	console.log(renderTable(visible));
+	if (d.mounts && d.mounts.length > 0) section("Mounts", renderTable(d.mounts.map((m) => [
+		m.type ?? "?",
+		m.name ?? m.path ?? "",
+		m.accessMode ?? ""
+	]), [
+		"type",
+		"location",
+		"mode"
+	]));
+	if (d.authorizedUsers && d.authorizedUsers.length > 0) section("Authorized users", renderTable(d.authorizedUsers.map((u) => {
+		if (u.type === "token") return [
+			"token",
+			u.nickname ?? "(no name)",
+			u.tokenSuffix ? `-${u.tokenSuffix}` : ""
+		];
+		return [
+			u.type ?? "?",
+			u.identifier ?? u.principal ?? "",
+			""
+		];
+	}), [
+		"type",
+		"name / identifier",
+		"suffix"
+	]));
+	if (d.connectedClients && d.connectedClients.length > 0) section("Connected clients", renderTable(d.connectedClients.map((c) => [
+		c.id ?? "",
+		c.ipAddress ?? "",
+		c.connectedAt ?? ""
+	]), [
+		"id",
+		"ip",
+		"connected at"
+	]));
+}
+program.command("list").description("List disks in the current region").option("--limit <n>", "Maximum number of disks to return", (v) => parseInt(v, 10)).option("-o, --output <format>", "Output format: table | json", "table").action(async (opts) => {
+	try {
+		const disks = await listDisks({ limit: opts.limit });
+		if (opts.output === "json") {
+			console.log(JSON.stringify(disks, null, 2));
+			return;
+		}
+		if (disks.length === 0) {
+			console.log("No disks found.");
+			return;
+		}
+		const rows = disks.map((d) => [
+			d.id,
+			`${d.organization}/${d.name}`,
+			d.status
+		]);
+		console.log(renderTable(rows, [
+			"id",
+			"name",
+			"status"
+		]));
+	} catch (err) {
+		fail(err);
+	}
+});
+program.command("get <id|name>").description("Show details for a disk (accepts a disk id or name)").option("-o, --output <format>", "Output format: table | json", "table").action(async (idOrName, opts) => {
+	try {
+		const d = await resolveDisk(idOrName);
+		if (opts.output === "json") console.log(JSON.stringify(d, null, 2));
+		else printDisk(d);
+	} catch (err) {
+		fail(err);
+	}
+});
+program.command("create <name>").description("Create a new disk").action(async (name) => {
+	try {
+		const result = await createDisk({ name });
+		console.log(`Created disk ${result.disk.organization}/${result.disk.name}`);
+		console.log(`  id:     ${result.disk.id}`);
+		console.log(`  status: ${result.disk.status}`);
+		if (result.token) {
+			console.log("");
+			console.log("Disk token (save this — it cannot be retrieved again):");
+			console.log(`  ${result.token}`);
+			if (result.tokenIdentifier) console.log(`  identifier: ${result.tokenIdentifier}`);
+		}
+	} catch (err) {
+		fail(err);
+	}
+});
+program.command("delete <id|name>").description("Delete a disk (accepts a disk id or name)").action(async (idOrName) => {
+	try {
+		const d = await resolveDisk(idOrName);
+		await d.delete();
+		console.log(`Deleted ${d.organization}/${d.name} (${d.id})`);
+	} catch (err) {
+		fail(err);
+	}
+});
+program.command("exec <id|name> <command...>").description("Run a command in a container with the disk mounted, return stdout/stderr/exit code (accepts a disk id or name)").action(async (idOrName, cmd) => {
+	try {
+		const result = await (await resolveDisk(idOrName)).exec(cmd.join(" "));
+		if (result.stdout) process.stdout.write(result.stdout);
+		if (result.stderr) process.stderr.write(result.stderr);
+		process.exit(result.exitCode);
+	} catch (err) {
+		fail(err);
+	}
+});
+program.command("grep <pattern> <target>").description("Constant-time parallel server-side grep across a disk. <target> is <id|name>[/<path>] — the path after the first '/' is the directory to search (defaults to the disk root). Accepts a disk id or name.").option("--no-recursive", "Search only the given directory, not its subdirectories (recursive is the default)").option("--max-duration <seconds>", "Wall-clock deadline for the whole search", (v) => parseInt(v, 10)).option("--concurrency <n>", "Max parallel grep workers (clamped to fleet capacity)", (v) => parseInt(v, 10)).option("--max-results <n>", "Stop once this many matches are collected", (v) => parseInt(v, 10)).option("-o, --output <format>", "Output format: text | json", "text").action(async (pattern, target, opts) => {
+	try {
+		const slash = target.indexOf("/");
+		const idOrName = slash === -1 ? target : target.slice(0, slash);
+		const directory = slash === -1 ? "" : target.slice(slash + 1);
+		const res = await (await resolveDisk(idOrName)).grep({
+			directory,
+			pattern,
+			recursive: opts.recursive !== false,
+			maxDurationSeconds: opts.maxDuration,
+			concurrency: opts.concurrency,
+			maxResults: opts.maxResults
+		});
+		if (opts.output === "json") console.log(JSON.stringify(res, null, 2));
+		else {
+			for (const m of res.matches) console.log(`${m.file}:${m.line}:${m.text}`);
+			console.error(`${res.matches.length} match${res.matches.length === 1 ? "" : "es"} · ${res.filesScanned} files scanned · ${res.containersDispatched} containers · ${res.durationMs}ms · ${res.stoppedReason}`);
+			if (res.stoppedReason !== "completed") console.error(`warning: search did not complete (${res.stoppedReason}); results may be partial`);
+		}
+		process.exit(res.matches.length > 0 ? 0 : 1);
+	} catch (err) {
+		fail(err);
+	}
+});
+const keys = program.command("api-keys").description("Manage Archil API keys (account-level credentials)");
+keys.command("list").description("List API keys").option("--limit <n>", "Maximum number of keys to return", (v) => parseInt(v, 10)).action(async (opts) => {
+	try {
+		const ks = await listApiKeys({ limit: opts.limit });
+		if (ks.length === 0) {
+			console.log("No API keys found.");
+			return;
+		}
+		for (const k of ks) console.log(`${k.id ?? "-"}\t${k.name ?? "-"}\t${k.createdAt ?? ""}`);
+	} catch (err) {
+		fail(err);
+	}
+});
+keys.command("create <name>").description("Create a new API key (the key value is shown once)").option("--description <description>", "Optional description").action(async (name, opts) => {
+	try {
+		const k = await createApiKey({
+			name,
+			description: opts.description
+		});
+		console.log(`Created API key ${name} (${k.id ?? "?"})`);
+		if (k.token) {
+			console.log("");
+			console.log("API key value (save this — it cannot be retrieved again):");
+			console.log(`  ${k.token}`);
+		}
+	} catch (err) {
+		fail(err);
+	}
+});
+keys.command("delete <id>").description("Delete an API key").action(async (id) => {
+	try {
+		await deleteApiKey(id);
+		console.log(`Deleted API key ${id}`);
+	} catch (err) {
+		fail(err);
+	}
+});
+function rewriteSugar(argv) {
+	const known = /* @__PURE__ */ new Set([
+		"list",
+		"get",
+		"create",
+		"delete",
+		"exec",
+		"grep",
+		"api-keys",
+		"help",
+		"--help",
+		"-h",
+		"--version",
+		"-V"
+	]);
+	const head = argv[2];
+	const next = argv[3];
+	if (head && next === "exec" && !known.has(head) && !head.startsWith("-")) return [
+		...argv.slice(0, 2),
+		"exec",
+		head,
+		...argv.slice(4)
+	];
+	return argv;
+}
+program.parseAsync(rewriteSugar(process.argv));
+//#endregion
+export {};