@agfs/cli 0.1.0

package/src/commands/fs.ts

@@ -0,0 +1,96 @@
+import { Command } from "commander";
+import { AgfsClient } from "../lib/client";
+import { renderEntries, renderTree } from "../lib/format";
+
+export function registerFsCommands(program: Command) {
+  program
+    .command("ls")
+    .description("List the direct children at a remote path")
+    .argument("[path]", "Remote path", "/")
+    .action(async (pathname: string) => {
+      const client = await AgfsClient.fromConfig();
+      const result = await client.list(pathname);
+      console.log(renderEntries(result.entries));
+    });
+
+  program
+    .command("tree")
+    .description("Render a tree view of a remote folder")
+    .argument("[path]", "Remote path", "/")
+    .action(async (pathname: string) => {
+      const client = await AgfsClient.fromConfig();
+      const result = await client.tree(pathname);
+      console.log(renderTree(result.tree));
+    });
+
+  program
+    .command("mkdir")
+    .description("Create a folder path")
+    .argument("<path>", "Remote path")
+    .action(async (pathname: string) => {
+      const client = await AgfsClient.fromConfig();
+      await client.mkdir(pathname);
+      console.log(`Created ${pathname}`);
+    });
+
+  program
+    .command("mv")
+    .description("Move or rename a file or folder")
+    .argument("<from>", "Current path")
+    .argument("<to>", "Destination path")
+    .action(async (from: string, to: string) => {
+      const client = await AgfsClient.fromConfig();
+      await client.move(from, to);
+      console.log(`Moved ${from} -> ${to}`);
+    });
+
+  program
+    .command("rm")
+    .description("Delete a file or folder")
+    .argument("<path>", "Remote path")
+    .option("--recursive", "Delete folders recursively")
+    .action(async (pathname: string, options: { recursive?: boolean }) => {
+      const client = await AgfsClient.fromConfig();
+      await client.remove(pathname, Boolean(options.recursive));
+      console.log(`Removed ${pathname}`);
+    });
+
+  program
+    .command("upload")
+    .description("Upload a local file into AGFS")
+    .argument("<localPath>", "Local file path")
+    .argument("[remotePath]", "Remote destination path")
+    .option("--share <ttl>", "Create a preview link after upload")
+    .action(async (localPath: string, remotePath: string | undefined, options: { share?: string }) => {
+      const client = await AgfsClient.fromConfig();
+      const destination = remotePath ?? `/${localPath.split("/").at(-1)}`;
+      await client.upload(localPath, destination);
+      console.log(`Uploaded ${destination}`);
+      if (options.share) {
+        const share = await client.share(destination, options.share);
+        console.log(`Share URL: ${share.share.url}`);
+      }
+    });
+
+  program
+    .command("download")
+    .description("Download a file or folder from AGFS")
+    .argument("<remotePath>", "Remote file or folder path")
+    .argument("[localPath]", "Destination path on disk")
+    .action(async (remotePath: string, localPath?: string) => {
+      const client = await AgfsClient.fromConfig();
+      const destination = await client.download(remotePath, localPath);
+      console.log(`Saved ${destination}`);
+    });
+
+  program
+    .command("share")
+    .description("Generate a preview URL for a file")
+    .argument("<remotePath>", "Remote file path")
+    .option("--ttl <ttl>", "Link lifetime", "15m")
+    .action(async (remotePath: string, options: { ttl: string }) => {
+      const client = await AgfsClient.fromConfig();
+      const result = await client.share(remotePath, options.ttl);
+      console.log(result.share.url);
+    });
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerAuthCommands } from "./commands/auth";
+import { registerFsCommands } from "./commands/fs";
+
+const program = new Command()
+  .name("agfs")
+  .description("AgentFilesystem CLI")
+  .version("0.1.0");
+
+registerAuthCommands(program);
+registerFsCommands(program);
+
+program.parseAsync(process.argv).catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : "Command failed");
+  process.exitCode = 1;
+});

package/src/lib/client.ts

@@ -0,0 +1,307 @@
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { Transform } from "node:stream";
+import { lookup as lookupMime } from "mime-types";
+import {
+  devicePollResponseSchema,
+  deviceStartResponseSchema,
+  listEntriesResponseSchema,
+  shareCreateResponseSchema,
+  shareListResponseSchema,
+  successResponseSchema,
+  tokenCreateResponseSchema,
+  tokenListResponseSchema,
+  treeEntriesResponseSchema,
+  uploadIntentSchema,
+  whoAmIResponseSchema,
+} from "@agfs/contracts";
+import { getResolvedBaseUrl, getResolvedToken, readConfig } from "./config";
+import { flattenTree, getRemoteLeafName, joinRelativeDestination, resolveFileDestination, resolveFolderDestination } from "./download";
+import { summarizeFolderDownload, TransferProgress } from "./progress";
+
+async function parseError(response: Response) {
+  try {
+    const payload = await response.json();
+    return payload.error ?? response.statusText;
+  } catch {
+    return response.statusText;
+  }
+}
+
+export class AgfsClient {
+  constructor(
+    readonly baseUrl: string,
+    readonly token: string | null,
+  ) {}
+
+  static async fromConfig() {
+    const config = await readConfig();
+    return new AgfsClient(getResolvedBaseUrl(config), getResolvedToken(config));
+  }
+
+  private async request(pathname: string, init?: RequestInit) {
+    const headers = new Headers(init?.headers);
+    if (this.token) {
+      headers.set("authorization", `Bearer ${this.token}`);
+    }
+
+    const response = await fetch(`${this.baseUrl}${pathname}`, {
+      ...init,
+      headers,
+    });
+
+    if (!response.ok) {
+      throw new Error(await parseError(response));
+    }
+
+    return response;
+  }
+
+  async whoAmI() {
+    const response = await this.request("/api/v1/whoami");
+    return whoAmIResponseSchema.parse(await response.json());
+  }
+
+  async startDeviceLogin(clientName = "agfs cli") {
+    const response = await this.request("/api/v1/device/start", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ clientName }),
+    });
+    return deviceStartResponseSchema.parse(await response.json());
+  }
+
+  async pollDeviceLogin(deviceCode: string) {
+    const response = await this.request("/api/v1/device/poll", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ deviceCode }),
+    });
+    return devicePollResponseSchema.parse(await response.json());
+  }
+
+  async list(pathname: string) {
+    const response = await this.request(`/api/v1/fs/list?path=${encodeURIComponent(pathname)}`);
+    return listEntriesResponseSchema.parse(await response.json());
+  }
+
+  async tree(pathname: string) {
+    const response = await this.request(`/api/v1/fs/tree?path=${encodeURIComponent(pathname)}`);
+    return treeEntriesResponseSchema.parse(await response.json());
+  }
+
+  async mkdir(pathname: string) {
+    const response = await this.request("/api/v1/fs/mkdir", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ path: pathname }),
+    });
+    return successResponseSchema.parse(await response.json());
+  }
+
+  async move(from: string, to: string) {
+    const response = await this.request("/api/v1/fs/move", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ from, to }),
+    });
+    return successResponseSchema.parse(await response.json());
+  }
+
+  async remove(pathname: string, recursive = false) {
+    const response = await this.request("/api/v1/fs/delete", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ path: pathname, recursive }),
+    });
+    return successResponseSchema.parse(await response.json());
+  }
+
+  async upload(localPath: string, remotePath: string) {
+    const fileStat = await stat(localPath);
+    const fileSize = fileStat.size;
+    const contentType = lookupMime(localPath) || "application/octet-stream";
+    const intentResponse = await this.request("/api/v1/fs/upload-intents", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        path: remotePath,
+        contentType,
+        size: fileSize,
+      }),
+    });
+    const intent = uploadIntentSchema.parse(await intentResponse.json());
+    const progress = new TransferProgress(`Upload ${path.basename(localPath)}`, fileSize);
+    let uploadedBytes = 0;
+    const progressStream = new Transform({
+      transform(chunk, _encoding, callback) {
+        uploadedBytes += chunk.length;
+        progress.update(uploadedBytes);
+        callback(null, chunk);
+      },
+    });
+
+    let uploadResponse: Response;
+    try {
+      uploadResponse = await fetch(intent.url, {
+        method: intent.method,
+        headers: {
+          ...intent.headers,
+          "Content-Length": String(fileSize),
+        },
+        body: createReadStream(localPath).pipe(progressStream),
+        duplex: "half",
+      });
+      if (!uploadResponse.ok) {
+        throw new Error(`R2 upload failed with status ${uploadResponse.status}`);
+      }
+      progress.complete();
+    } catch (error) {
+      progress.fail();
+      throw error;
+    }
+
+    const commitResponse = await this.request(`/api/v1/fs/uploads/${intent.uploadId}/commit`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        etag: uploadResponse.headers.get("etag") ?? "uploaded",
+      }),
+    });
+
+    return await commitResponse.json();
+  }
+
+  private async writeRemoteFile(remotePath: string, localPath?: string) {
+    const response = await this.request(`/api/v1/fs/download?path=${encodeURIComponent(remotePath)}`);
+    let destination = resolveFileDestination(remotePath, localPath);
+    if (localPath) {
+      try {
+        const localStat = await stat(localPath);
+        if (localStat.isDirectory()) {
+          destination = path.join(localPath, getRemoteLeafName(remotePath));
+        }
+      } catch {
+        // Treat a missing path as the intended file destination.
+      }
+    }
+
+    await mkdir(path.dirname(destination), { recursive: true });
+    const totalBytes = Number(response.headers.get("content-length") ?? 0);
+    const progress = new TransferProgress(`Download ${path.basename(destination)}`, totalBytes || 0);
+    const body = response.body;
+    if (!body) {
+      progress.fail();
+      throw new Error(`No response body returned for ${remotePath}`);
+    }
+
+    const writer = createWriteStream(destination);
+    const reader = body.getReader();
+    let writtenBytes = 0;
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+
+        writtenBytes += value.byteLength;
+        progress.update(totalBytes > 0 ? writtenBytes : Math.max(writtenBytes, 1));
+
+        await new Promise<void>((resolve, reject) => {
+          writer.write(Buffer.from(value), (error) => {
+            if (error) {
+              reject(error);
+              return;
+            }
+            resolve();
+          });
+        });
+      }
+
+      await new Promise<void>((resolve, reject) => {
+        writer.end((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+
+      if (totalBytes > 0) {
+        progress.complete();
+      } else {
+        progress.update(writtenBytes);
+        progress.complete();
+      }
+    } catch (error) {
+      progress.fail();
+      writer.destroy();
+      throw error;
+    }
+
+    return destination;
+  }
+
+  async download(remotePath: string, localPath?: string) {
+    let isFolder = false;
+    try {
+      await this.list(remotePath);
+      isFolder = true;
+    } catch {
+      isFolder = false;
+    }
+
+    if (!isFolder) {
+      return this.writeRemoteFile(remotePath, localPath);
+    }
+
+    const destinationRoot = resolveFolderDestination(remotePath, localPath);
+    await mkdir(destinationRoot, { recursive: true });
+
+    const tree = await this.tree(remotePath);
+    const flattened = flattenTree(tree.tree);
+
+    for (const directory of flattened.directories) {
+      await mkdir(joinRelativeDestination(destinationRoot, directory), { recursive: true });
+    }
+
+    for (const file of flattened.files) {
+      await this.writeRemoteFile(file.path, joinRelativeDestination(destinationRoot, file.relativePath));
+    }
+
+    console.error(summarizeFolderDownload(flattened.files.length, destinationRoot));
+    return destinationRoot;
+  }
+
+  async share(pathname: string, ttl = "15m") {
+    const response = await this.request("/api/v1/shares", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ path: pathname, ttl }),
+    });
+    return shareCreateResponseSchema.parse(await response.json());
+  }
+
+  async listTokens() {
+    const response = await this.request("/api/v1/tokens");
+    return tokenListResponseSchema.parse(await response.json());
+  }
+
+  async createToken(label: string, ttl?: string) {
+    const response = await this.request("/api/v1/tokens", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ label, ttl }),
+    });
+    return tokenCreateResponseSchema.parse(await response.json());
+  }
+
+  async listShares() {
+    const response = await this.request("/api/v1/shares");
+    return shareListResponseSchema.parse(await response.json());
+  }
+}

package/src/lib/config.test.ts

@@ -0,0 +1,31 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getConfigPath, readConfig, writeConfig } from "./config";
+
+let tempDir = "";
+const previousXdg = process.env.XDG_CONFIG_HOME;
+
+describe("config persistence", () => {
+  beforeEach(async () => {
+    tempDir = await mkdtemp(path.join(os.tmpdir(), "agfs-cli-"));
+    process.env.XDG_CONFIG_HOME = tempDir;
+  });
+
+  afterEach(async () => {
+    process.env.XDG_CONFIG_HOME = previousXdg;
+    if (tempDir) {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("writes and reads config from XDG config home", async () => {
+    await writeConfig({ baseUrl: "https://example.com", token: "secret" });
+    expect(getConfigPath()).toContain(tempDir);
+    await expect(readConfig()).resolves.toEqual({
+      baseUrl: "https://example.com",
+      token: "secret",
+    });
+  });
+});

package/src/lib/config.ts

@@ -0,0 +1,42 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+export interface CliConfig {
+  baseUrl?: string;
+  token?: string;
+}
+
+function getConfigDir() {
+  return process.env.XDG_CONFIG_HOME
+    ? path.join(process.env.XDG_CONFIG_HOME, "agfs")
+    : path.join(os.homedir(), ".config", "agfs");
+}
+
+export function getConfigPath() {
+  return path.join(getConfigDir(), "config.json");
+}
+
+export async function readConfig(): Promise<CliConfig> {
+  try {
+    const content = await readFile(getConfigPath(), "utf8");
+    return JSON.parse(content) as CliConfig;
+  } catch {
+    return {};
+  }
+}
+
+export async function writeConfig(config: CliConfig) {
+  const filePath = getConfigPath();
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, JSON.stringify(config, null, 2), "utf8");
+  await chmod(filePath, 0o600);
+}
+
+export function getResolvedBaseUrl(config: CliConfig) {
+  return (process.env.AGFS_BASE_URL ?? config.baseUrl ?? "https://agfs.dev").replace(/\/+$/, "");
+}
+
+export function getResolvedToken(config: CliConfig) {
+  return process.env.AGFS_TOKEN ?? config.token ?? null;
+}

package/src/lib/download.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import { flattenTree, getRemoteLeafName, joinRelativeDestination, resolveFolderDestination } from "./download";
+
+describe("getRemoteLeafName", () => {
+  it("uses the final segment for normal paths", () => {
+    expect(getRemoteLeafName("/screenshots/shot.png")).toBe("shot.png");
+    expect(getRemoteLeafName("/screenshots")).toBe("screenshots");
+  });
+
+  it("uses agfs-root for root downloads", () => {
+    expect(getRemoteLeafName("/")).toBe("agfs-root");
+  });
+});
+
+describe("flattenTree", () => {
+  it("separates directories and files while preserving relative paths", () => {
+    const result = flattenTree([
+      {
+        id: "dir_1",
+        path: "/screenshots",
+        name: "screenshots",
+        kind: "folder",
+        size: null,
+        children: [
+          {
+            id: "file_1",
+            path: "/screenshots/a.png",
+            name: "a.png",
+            kind: "file",
+            size: 12,
+          },
+          {
+            id: "dir_2",
+            path: "/screenshots/nested",
+            name: "nested",
+            kind: "folder",
+            size: null,
+            children: [
+              {
+                id: "file_2",
+                path: "/screenshots/nested/b.png",
+                name: "b.png",
+                kind: "file",
+                size: 18,
+              },
+            ],
+          },
+        ],
+      },
+    ] as any);
+
+    expect(result.directories).toEqual(["screenshots", "screenshots/nested"]);
+    expect(result.files).toEqual([
+      {
+        path: "/screenshots/a.png",
+        relativePath: "screenshots/a.png",
+      },
+      {
+        path: "/screenshots/nested/b.png",
+        relativePath: "screenshots/nested/b.png",
+      },
+    ]);
+  });
+});
+
+describe("destination helpers", () => {
+  it("uses the provided folder destination as-is", () => {
+    expect(resolveFolderDestination("/screenshots", "./downloads")).toBe("./downloads");
+    expect(joinRelativeDestination("./downloads", "screenshots/a.png")).toBe("downloads/screenshots/a.png");
+  });
+});

package/src/lib/download.ts

@@ -0,0 +1,58 @@
+import path from "node:path";
+import type { FsTreeNode } from "@agfs/contracts";
+
+export interface FlattenedTree {
+  directories: string[];
+  files: Array<{
+    path: string;
+    relativePath: string;
+  }>;
+}
+
+export function getRemoteLeafName(remotePath: string): string {
+  const normalized = remotePath.replace(/\/+$/, "");
+  if (!normalized || normalized === "/") {
+    return "agfs-root";
+  }
+
+  return normalized.split("/").filter(Boolean).at(-1) ?? "agfs-root";
+}
+
+export function flattenTree(nodes: FsTreeNode[]): FlattenedTree {
+  const directories: string[] = [];
+  const files: Array<{ path: string; relativePath: string }> = [];
+
+  function walk(items: FsTreeNode[], parentSegments: string[]) {
+    for (const item of items) {
+      const segments = [...parentSegments, item.name];
+      const relativePath = segments.join("/");
+
+      if (item.kind === "folder") {
+        directories.push(relativePath);
+        walk((item.children ?? []) as FsTreeNode[], segments);
+        continue;
+      }
+
+      files.push({
+        path: item.path,
+        relativePath,
+      });
+    }
+  }
+
+  walk(nodes, []);
+
+  return { directories, files };
+}
+
+export function resolveFolderDestination(remotePath: string, localPath?: string): string {
+  return localPath ?? getRemoteLeafName(remotePath);
+}
+
+export function resolveFileDestination(remotePath: string, localPath?: string): string {
+  return localPath ?? getRemoteLeafName(remotePath);
+}
+
+export function joinRelativeDestination(root: string, relativePath: string): string {
+  return path.join(root, ...relativePath.split("/"));
+}

package/src/lib/format.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { renderEntries, renderTree } from "./format";
+
+describe("renderEntries", () => {
+  it("renders a tabular listing", () => {
+    expect(
+      renderEntries([
+        {
+          id: "1",
+          ownerId: "user_1",
+          parentPath: "/",
+          path: "/shots",
+          name: "shots",
+          kind: "folder",
+          size: null,
+          contentType: null,
+          etag: null,
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        },
+      ]),
+    ).toContain("/shots\tfolder\tfolder");
+  });
+});
+
+describe("renderTree", () => {
+  it("renders nested branches", () => {
+    expect(
+      renderTree([
+        {
+          id: "folder_1",
+          path: "/shots",
+          name: "shots",
+          kind: "folder",
+          size: null,
+          children: [
+            {
+              id: "file_1",
+              path: "/shots/a.png",
+              name: "a.png",
+              kind: "file",
+              size: 128,
+            },
+          ],
+        },
+      ]),
+    ).toContain("shots/");
+  });
+});