@tuskydp/cli 0.1.0 → 0.1.1

package/src/mcp/tools/account.ts

@@ -0,0 +1,40 @@
+/**
+ * MCP tools — Account
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpContext } from '../context.js';
+import { wrapToolError } from './helpers.js';
+
+export function registerAccountTools(server: McpServer, ctx: McpContext) {
+  server.tool(
+    'tusky_account_info',
+    'Get account information including email, plan, storage usage, and encryption status',
+    {},
+    async () => {
+      try {
+        const account = await ctx.sdk.account.get();
+
+        const info = {
+          id: account.id,
+          email: account.email,
+          plan: account.planName,
+          planTier: account.planTier,
+          storageUsed: account.storageUsedFormatted,
+          storageLimit: account.storageLimitFormatted,
+          storageUsedBytes: account.storageUsedBytes,
+          storageLimitBytes: account.storageLimitBytes,
+          encryptionSetup: account.encryptionSetupComplete,
+          encryptionUnlocked: ctx.isEncryptionReady(),
+          createdAt: account.createdAt,
+        };
+
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(info, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+}

package/src/mcp/tools/files.ts

@@ -0,0 +1,428 @@
+/**
+ * MCP tools — File operations
+ *
+ * Handles upload with client-side encryption for private vaults,
+ * download with decryption and rehydration polling for cold files.
+ */
+
+import { z } from 'zod';
+import { readFileSync, writeFileSync, statSync } from 'fs';
+import { basename, resolve, join } from 'path';
+import { lookup } from 'mime-types';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpContext } from '../context.js';
+import { encryptBuffer, decryptBuffer } from '../../crypto.js';
+import { wrapToolError } from './helpers.js';
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+/** MIME types that should be returned as text rather than base64. */
+function isTextMimeType(mimeType: string): boolean {
+  if (mimeType.startsWith('text/')) return true;
+  const textTypes = [
+    'application/json',
+    'application/xml',
+    'application/javascript',
+    'application/typescript',
+    'application/x-yaml',
+    'application/yaml',
+    'application/toml',
+    'application/x-sh',
+    'application/sql',
+    'application/graphql',
+    'application/xhtml+xml',
+    'application/svg+xml',
+    'application/x-httpd-php',
+  ];
+  return textTypes.includes(mimeType) || mimeType.endsWith('+json') || mimeType.endsWith('+xml');
+}
+
+/**
+ * Fetch a file from Tusky, handle rehydration polling and decryption.
+ * Returns the plaintext buffer and encryption info.
+ */
+async function fetchAndDecryptFile(fileId: string, ctx: McpContext) {
+  let dlResponse = await ctx.sdk.files.getDownloadUrl(fileId);
+  let { downloadUrl, status, encryption } = dlResponse;
+
+  // Handle rehydration from Walrus (cold files)
+  if (status === 'rehydrating') {
+    for (let i = 0; i < 30; i++) {
+      await new Promise((r) => setTimeout(r, 2000));
+      const check = await ctx.sdk.files.getDownloadUrl(fileId);
+      if (check.status === 'ready') {
+        downloadUrl = check.downloadUrl;
+        encryption = check.encryption;
+        status = 'ready';
+        break;
+      }
+    }
+    if (status !== 'ready') {
+      throw new Error('File rehydration timed out (60s). The file is being retrieved from Walrus. Try again later.');
+    }
+  }
+
+  if (!downloadUrl) {
+    throw new Error('No download URL available for this file.');
+  }
+
+  // Download
+  const response = await fetch(downloadUrl);
+  if (!response.ok) {
+    throw new Error(`Download failed: HTTP ${response.status}`);
+  }
+  const arrayBuf = await response.arrayBuffer();
+  let fileBuffer: Buffer = Buffer.from(arrayBuf as ArrayBuffer);
+
+  // Decrypt if needed
+  if (encryption?.encrypted) {
+    const masterKey = ctx.getMasterKey();
+    if (!masterKey) {
+      throw new Error(
+        'Encryption passphrase required to decrypt this file. ' +
+        'Set the TUSKYDP_PASSWORD environment variable in your MCP server config.',
+      );
+    }
+    fileBuffer = decryptBuffer(
+      fileBuffer,
+      encryption.wrappedKey!,
+      encryption.iv!,
+      masterKey,
+      encryption.plaintextChecksumSha256 ?? undefined,
+    );
+  }
+
+  return { fileBuffer, encryption };
+}
+
+/**
+ * Encrypt (if private vault) and upload a buffer to Tusky.
+ * Shared by tusky_file_upload (from disk) and tusky_file_create (from content).
+ */
+async function encryptAndUpload(
+  fileBuffer: Buffer,
+  fileName: string,
+  mimeType: string,
+  vaultId: string,
+  folderId: string | undefined,
+  ctx: McpContext,
+) {
+  const vault = await ctx.sdk.vaults.get(vaultId);
+  const isPrivate = vault.visibility === 'private';
+
+  let uploadBody: Buffer;
+  let encryptionMeta: {
+    wrappedKey?: string;
+    encryptionIv?: string;
+    plaintextSizeBytes?: number;
+    plaintextChecksumSha256?: string;
+  } = {};
+
+  if (isPrivate) {
+    const masterKey = ctx.getMasterKey();
+    if (!masterKey) {
+      throw new Error(
+        'Encryption passphrase required for private vault uploads. ' +
+        'Set the TUSKYDP_PASSWORD environment variable in your MCP server config.',
+      );
+    }
+
+    const { ciphertext, wrappedKey, iv, plaintextChecksum } = encryptBuffer(fileBuffer, masterKey);
+    uploadBody = ciphertext;
+    encryptionMeta = {
+      wrappedKey,
+      encryptionIv: iv,
+      plaintextSizeBytes: fileBuffer.length,
+      plaintextChecksumSha256: plaintextChecksum,
+    };
+  } else {
+    uploadBody = fileBuffer;
+  }
+
+  // Request presigned upload URL
+  const { fileId, uploadUrl } = await ctx.sdk.files.requestUpload({
+    name: fileName,
+    mimeType,
+    sizeBytes: uploadBody.length,
+    vaultId,
+    folderId,
+    ...encryptionMeta,
+  });
+
+  // PUT to presigned URL
+  const putRes = await fetch(uploadUrl, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/octet-stream' },
+    body: new Uint8Array(uploadBody),
+  });
+  if (!putRes.ok) {
+    const errText = await putRes.text().catch(() => putRes.statusText);
+    throw new Error(`Upload PUT failed (${putRes.status}): ${errText}`);
+  }
+
+  // Confirm upload
+  const file = await ctx.sdk.files.confirmUpload(fileId);
+
+  return { file, isPrivate, uploadedSizeBytes: uploadBody.length };
+}
+
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+
+export function registerFileTools(server: McpServer, ctx: McpContext) {
+  // ── Upload file from disk ──────────────────────────────────────────────
+  server.tool(
+    'tusky_file_upload',
+    'Upload a file from a local filesystem path to a vault. Handles encryption transparently for private vaults. Use tusky_file_create instead if you want to upload content directly without a file on disk.',
+    {
+      filePath: z.string().describe('Absolute or relative path to the local file to upload'),
+      vaultId: z.string().describe('Target vault ID'),
+      folderId: z.string().optional().describe('Target folder ID within the vault (omit for vault root)'),
+    },
+    async ({ filePath, vaultId, folderId }) => {
+      try {
+        const resolvedPath = resolve(filePath);
+
+        // Validate file exists
+        let stat;
+        try {
+          stat = statSync(resolvedPath);
+        } catch {
+          return wrapToolError(new Error(`File not found: ${resolvedPath}`));
+        }
+        if (!stat.isFile()) {
+          return wrapToolError(new Error(`Not a file: ${resolvedPath}`));
+        }
+
+        const fileBuffer = readFileSync(resolvedPath);
+        const fileName = basename(resolvedPath);
+        const mimeType = lookup(resolvedPath) || 'application/octet-stream';
+
+        const { file, isPrivate, uploadedSizeBytes } = await encryptAndUpload(
+          fileBuffer, fileName, mimeType, vaultId, folderId, ctx,
+        );
+
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify({
+            ...file,
+            localPath: resolvedPath,
+            encrypted: isPrivate,
+            uploadedSizeBytes,
+          }, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Create file from content ─────────────────────────────────────────
+  server.tool(
+    'tusky_file_create',
+    'Create a file in a vault from raw content (text or base64-encoded binary). Use this when you want to upload content directly without needing a file on disk. Handles encryption transparently for private vaults.',
+    {
+      name: z.string().describe('File name including extension (e.g. "report.md", "data.json", "image.png")'),
+      content: z.string().describe('File content: plain text for text files, or base64-encoded string for binary files'),
+      encoding: z.enum(['utf-8', 'base64']).optional().describe(
+        'Content encoding. "utf-8" (default) for text content, "base64" for binary content.',
+      ),
+      vaultId: z.string().describe('Target vault ID'),
+      folderId: z.string().optional().describe('Target folder ID within the vault (omit for vault root)'),
+    },
+    async ({ name, content, encoding, vaultId, folderId }) => {
+      try {
+        const enc = encoding ?? 'utf-8';
+        const fileBuffer = enc === 'base64'
+          ? Buffer.from(content, 'base64')
+          : Buffer.from(content, 'utf-8');
+
+        const mimeType = lookup(name) || 'application/octet-stream';
+
+        const { file, isPrivate, uploadedSizeBytes } = await encryptAndUpload(
+          fileBuffer, name, mimeType, vaultId, folderId, ctx,
+        );
+
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify({
+            ...file,
+            encrypted: isPrivate,
+            uploadedSizeBytes,
+          }, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Download file (to disk) ────────────────────────────────────────────
+  server.tool(
+    'tusky_file_download',
+    'Download a file by ID and save it to a local path on disk. Handles decryption for private vaults and rehydration for cold files. Use tusky_file_read instead if you just want the file content returned directly.',
+    {
+      fileId: z.string().describe('File ID to download'),
+      outputPath: z.string().describe('Local path to save the file (must be writable)'),
+    },
+    async ({ fileId, outputPath }) => {
+      try {
+        const { fileBuffer, encryption } = await fetchAndDecryptFile(fileId, ctx);
+
+        const fileInfo = await ctx.sdk.files.getStatus(fileId);
+        const finalPath = resolve(outputPath);
+
+        writeFileSync(finalPath, fileBuffer);
+
+        const result = {
+          fileId,
+          name: fileInfo.name,
+          savedTo: finalPath,
+          sizeBytes: fileBuffer.length,
+          mimeType: fileInfo.mimeType,
+          wasEncrypted: encryption?.encrypted ?? false,
+        };
+
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Read file content (inline) ───────────────────────────────────────
+  server.tool(
+    'tusky_file_read',
+    'Read a file\'s content and return it directly. For text files the content is returned as text. For binary files it is returned as base64. Handles decryption for private vaults and rehydration for cold files transparently. Prefer this over tusky_file_download when you need to inspect file content.',
+    {
+      fileId: z.string().describe('File ID to read'),
+    },
+    async ({ fileId }) => {
+      try {
+        const { fileBuffer, encryption } = await fetchAndDecryptFile(fileId, ctx);
+        const fileInfo = await ctx.sdk.files.getStatus(fileId);
+
+        const isText = isTextMimeType(fileInfo.mimeType);
+
+        if (isText) {
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `--- ${fileInfo.name} (${fileInfo.mimeType}, ${fileBuffer.length} bytes${encryption?.encrypted ? ', decrypted' : ''}) ---\n\n${fileBuffer.toString('utf-8')}`,
+              },
+            ],
+          };
+        }
+
+        // Binary file — return as base64
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: JSON.stringify({
+                fileId,
+                name: fileInfo.name,
+                mimeType: fileInfo.mimeType,
+                sizeBytes: fileBuffer.length,
+                wasEncrypted: encryption?.encrypted ?? false,
+                encoding: 'base64',
+                data: fileBuffer.toString('base64'),
+              }, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── List files ───────────────────────────────────────────────────────
+  server.tool(
+    'tusky_file_list',
+    'List files, optionally filtered by vault or folder. Returns file metadata including status.',
+    {
+      vaultId: z.string().optional().describe('Filter by vault ID'),
+      folderId: z.string().optional().describe('Filter by folder ID'),
+      limit: z.number().optional().describe('Max number of files to return (default 50)'),
+      cursor: z.string().optional().describe('Pagination cursor from a previous response'),
+    },
+    async ({ vaultId, folderId, limit, cursor }) => {
+      try {
+        const result = await ctx.sdk.files.list({ vaultId, folderId, limit, cursor });
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Get file info ────────────────────────────────────────────────────
+  server.tool(
+    'tusky_file_get',
+    'Get detailed metadata for a specific file by ID',
+    {
+      fileId: z.string().describe('File ID'),
+    },
+    async ({ fileId }) => {
+      try {
+        const file = await ctx.sdk.files.get(fileId);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(file, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Delete file ──────────────────────────────────────────────────────
+  server.tool(
+    'tusky_file_delete',
+    'Soft-delete a file (moves to trash). Can be restored within 7 days.',
+    {
+      fileId: z.string().describe('File ID to delete'),
+    },
+    async ({ fileId }) => {
+      try {
+        await ctx.sdk.files.delete(fileId);
+        return {
+          content: [{ type: 'text' as const, text: `File ${fileId} moved to trash.` }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Retry failed file sync ──────────────────────────────────────────
+  server.tool(
+    'tusky_file_retry',
+    'Retry Walrus sync for a failed file, or retry all failed files if no fileId given.',
+    {
+      fileId: z.string().optional().describe('File ID to retry (omit to retry all failed files)'),
+    },
+    async ({ fileId }) => {
+      try {
+        if (fileId) {
+          const result = await ctx.sdk.files.retry(fileId);
+          return {
+            content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+          };
+        }
+        const result = await ctx.sdk.files.retryAll();
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+}

package/src/mcp/tools/folders.ts

@@ -0,0 +1,109 @@
+/**
+ * MCP tools — Folder management
+ */
+
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpContext } from '../context.js';
+import { wrapToolError } from './helpers.js';
+
+export function registerFolderTools(server: McpServer, ctx: McpContext) {
+  // ── Create folder ────────────────────────────────────────────────────
+  server.tool(
+    'tusky_folder_create',
+    'Create a folder inside a vault',
+    {
+      vaultId: z.string().describe('Vault ID'),
+      name: z.string().describe('Folder name'),
+      parentId: z.string().optional().describe('Parent folder ID (omit for root)'),
+    },
+    async ({ vaultId, name, parentId }) => {
+      try {
+        const folder = await ctx.sdk.folders.create({ vaultId, name, parentId });
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(folder, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── List folders ─────────────────────────────────────────────────────
+  server.tool(
+    'tusky_folder_list',
+    'List folders in a vault (optionally within a parent folder)',
+    {
+      vaultId: z.string().describe('Vault ID'),
+      parentId: z.string().optional().describe('Parent folder ID (omit for root-level folders)'),
+    },
+    async ({ vaultId, parentId }) => {
+      try {
+        const folders = await ctx.sdk.folders.list({ vaultId, parentId });
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(folders, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Get folder contents ──────────────────────────────────────────────
+  server.tool(
+    'tusky_folder_get_contents',
+    'Get the contents (files and subfolders) of a folder',
+    {
+      folderId: z.string().describe('Folder ID'),
+    },
+    async ({ folderId }) => {
+      try {
+        const contents = await ctx.sdk.folders.getContents(folderId);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(contents, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Update/rename folder ──────────────────────────────────────────────
+  server.tool(
+    'tusky_folder_update',
+    'Rename a folder',
+    {
+      folderId: z.string().describe('Folder ID'),
+      name: z.string().describe('New folder name'),
+    },
+    async ({ folderId, name }) => {
+      try {
+        const folder = await ctx.sdk.folders.update(folderId, { name });
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(folder, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Delete folder ────────────────────────────────────────────────────
+  server.tool(
+    'tusky_folder_delete',
+    'Delete a folder',
+    {
+      folderId: z.string().describe('Folder ID'),
+    },
+    async ({ folderId }) => {
+      try {
+        await ctx.sdk.folders.delete(folderId);
+        return {
+          content: [{ type: 'text' as const, text: `Folder ${folderId} deleted successfully.` }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+}

package/src/mcp/tools/helpers.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared helpers for MCP tool handlers.
+ */
+
+import { TuskyError } from '@tuskydp/sdk';
+
+/**
+ * Wraps an error into an MCP tool error result.
+ * Extracts meaningful messages from TuskyError or generic Error instances.
+ */
+export function wrapToolError(err: unknown): {
+  content: { type: 'text'; text: string }[];
+  isError: true;
+} {
+  let message: string;
+  if (err instanceof TuskyError) {
+    message = `Tusky API error (${err.statusCode}): ${err.message}`;
+  } else if (err instanceof Error) {
+    message = err.message;
+  } else {
+    message = String(err);
+  }
+
+  return {
+    content: [{ type: 'text' as const, text: message }],
+    isError: true,
+  };
+}

package/src/mcp/tools/trash.ts

@@ -0,0 +1,82 @@
+/**
+ * MCP tools — Trash management
+ */
+
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpContext } from '../context.js';
+import { wrapToolError } from './helpers.js';
+
+export function registerTrashTools(server: McpServer, ctx: McpContext) {
+  // ── List trash ───────────────────────────────────────────────────────
+  server.tool(
+    'tusky_trash_list',
+    'List all soft-deleted files and vaults in the trash',
+    {},
+    async () => {
+      try {
+        const trash = await ctx.sdk.trash.list();
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(trash, null, 2) }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Restore from trash ───────────────────────────────────────────────
+  server.tool(
+    'tusky_trash_restore',
+    'Restore a file or vault from the trash',
+    {
+      id: z.string().describe('ID of the trashed file or vault to restore'),
+    },
+    async ({ id }) => {
+      try {
+        const result = await ctx.sdk.trash.restore(id);
+        return {
+          content: [{ type: 'text' as const, text: `Restored ${result.type ?? 'item'} ${id} successfully.` }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Delete single item from trash permanently ────────────────────────
+  server.tool(
+    'tusky_trash_delete',
+    'Permanently delete a single item from the trash. This action cannot be undone.',
+    {
+      id: z.string().describe('ID of the trashed file or vault to permanently delete'),
+    },
+    async ({ id }) => {
+      try {
+        const result = await ctx.sdk.trash.delete(id);
+        return {
+          content: [{ type: 'text' as const, text: `Permanently deleted ${result.type ?? 'item'} ${id}.` }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+
+  // ── Empty trash ──────────────────────────────────────────────────────
+  server.tool(
+    'tusky_trash_empty',
+    'Permanently delete ALL items in the trash. This action cannot be undone.',
+    {},
+    async () => {
+      try {
+        await ctx.sdk.trash.empty();
+        return {
+          content: [{ type: 'text' as const, text: 'Trash emptied successfully. All items permanently deleted.' }],
+        };
+      } catch (err) {
+        return wrapToolError(err);
+      }
+    },
+  );
+}