@lanes-sh/link 0.1.0

package/src/connectivity/transports/fs/commands.ts

@@ -0,0 +1,258 @@
+import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import type { ToolResult } from '#connectivity';
+import { ALWAYS_EXCLUDED } from './operations.ts';
+import { confine, isPlaceholder, placeholderFor, rootOf } from './paths.ts';
+import { error, json } from './result.ts';
+import type { FsConnectorOptions } from './index.ts';
+
+/** The nine operations, as free functions over the connector's options. */
+
+export async function listFiles(
+  options: FsConnectorOptions,
+  excluded: ReadonlySet<string>,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+  const { absolute, relative: shown, root } = await confine(options, excluded, args['path']);
+  const limit = Math.min(Number(args['limit'] ?? 200) || 200, 500);
+  const recursive = args['recursive'] === true;
+
+  const entries: unknown[] = [];
+
+  const walk = async (directory: string, depth: number): Promise<void> => {
+    if (entries.length >= limit) return;
+
+    const found = await readdir(directory, { withFileTypes: true });
+    for (const entry of found.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entries.length >= limit) return;
+      if (excluded.has(entry.name)) continue;
+
+      // A placeholder is an implementation detail of eviction, reported on the
+      // file it stands for rather than listed as a file of its own.
+      if (isPlaceholder(entry.name, options.placeholder?.suffix)) continue;
+
+      const full = join(directory, entry.name);
+      const info = await stat(full).catch(() => null);
+
+      entries.push({
+        path: relative(root, full),
+        kind: entry.isDirectory() ? 'folder' : 'file',
+        ...(entry.isDirectory()
+          ? {}
+          : {
+              bytes: info?.size ?? null,
+              downloaded: (await placeholderFor(full, options.placeholder?.suffix)) === null,
+            }),
+        modified: info?.mtime.toISOString() ?? null,
+      });
+
+      if (recursive && entry.isDirectory() && depth < 8) await walk(full, depth + 1);
+    }
+  };
+
+  await walk(absolute, 0);
+
+  return json({
+    path: shown,
+    truncated: entries.length >= limit,
+    entries,
+  });
+}
+
+export async function searchFiles(
+  options: FsConnectorOptions,
+  excluded: ReadonlySet<string>,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+  const { absolute, root } = await confine(options, excluded, args['path']);
+  const query = String(args['query'] ?? '').toLowerCase();
+  if (!query) return error('query is required.');
+
+  const contains = args['contains'] ? String(args['contains']).toLowerCase() : null;
+  const limit = Math.min(Number(args['limit'] ?? 50) || 50, 200);
+  const matches: unknown[] = [];
+
+  const walk = async (directory: string, depth: number): Promise<void> => {
+    if (matches.length >= limit || depth > 8) return;
+
+    const found = await readdir(directory, { withFileTypes: true }).catch(() => []);
+    for (const entry of found) {
+      if (matches.length >= limit) return;
+      if (excluded.has(entry.name)) continue;
+      if (isPlaceholder(entry.name, options.placeholder?.suffix)) continue;
+
+      const full = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full, depth + 1);
+        continue;
+      }
+
+      if (!entry.name.toLowerCase().includes(query)) continue;
+
+      if (contains) {
+        const info = await stat(full).catch(() => null);
+        // Not worth reading a large file into memory to grep it, and a binary
+        // has nothing to find.
+        if (!info || info.size > options.maxFileBytes) continue;
+        const text = await readFile(full, 'utf8').catch(() => null);
+        if (!text || !text.toLowerCase().includes(contains)) continue;
+      }
+
+      matches.push({ path: relative(root, full) });
+    }
+  };
+
+  await walk(absolute, 0);
+
+  return json({ query, ...(contains ? { contains: args['contains'] } : {}), matches });
+}
+
+export async function readTextFile(
+  options: FsConnectorOptions,
+  excluded: ReadonlySet<string>,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+  const { absolute, relative: shown } = await confine(options, excluded, args['path']);
+
+  const placeholder = await placeholderFor(absolute, options.placeholder?.suffix);
+  if (placeholder) {
+    return error(
+      `"${shown}" is not downloaded to this machine — whatever syncs this folder is ` +
+        `holding the contents remotely, so there is nothing to read yet.` +
+        (options.placeholder?.hint ? `\n${options.placeholder.hint} ${absolute}` : ''),
+    );
+  }
+
+  const info = await stat(absolute).catch(() => null);
+  if (!info) return error(`"${shown}" is not there.`);
+  if (info.isDirectory()) return error(`"${shown}" is a folder. Use list_files.`);
+  if (info.size > options.maxFileBytes) {
+    return error(
+      `"${shown}" is ${Math.round(info.size / 1024)}KB, over the ${Math.round(options.maxFileBytes / 1024)}KB limit for one read.`,
+    );
+  }
+
+  const bytes = await readFile(absolute);
+  if (looksBinary(bytes)) {
+    return json({
+      path: shown,
+      bytes: info.size,
+      binary: true,
+      note: 'Binary file. Its contents are not returned as text.',
+    });
+  }
+
+  return json({ path: shown, bytes: info.size, content: new TextDecoder().decode(bytes) });
+}
+
+export async function fileInfo(
+  options: FsConnectorOptions,
+  excluded: ReadonlySet<string>,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+  const { absolute, relative: shown } = await confine(options, excluded, args['path']);
+  const info = await stat(absolute).catch(() => null);
+
+  if (!info) {
+    const placeholder = await placeholderFor(absolute, options.placeholder?.suffix);
+    if (placeholder) return json({ path: shown, downloaded: false, kind: 'file' });
+    return error(`"${shown}" is not there.`);
+  }
+
+  return json({
+    path: shown,
+    kind: info.isDirectory() ? 'folder' : 'file',
+    bytes: info.size,
+    modified: info.mtime.toISOString(),
+    created: info.birthtime.toISOString(),
+    downloaded: info.isDirectory() ? true : (await placeholderFor(absolute, options.placeholder?.suffix)) === null,
+  });
+}
+
+export async function writeTextFile(
+  options: FsConnectorOptions,
+  excluded: ReadonlySet<string>,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+  const { absolute, relative: shown } = await confine(options, excluded, args['path']);
+  const content = String(args['content'] ?? '');
+
+  const existing = await stat(absolute).catch(() => null);
+  if (existing?.isDirectory()) return error(`"${shown}" is a folder.`);
+  if (existing && args['overwrite'] !== true) {
+    // Replacing a file is a different act from creating one, and an agent that
+    // meant to create should not silently destroy.
+    return error(`"${shown}" already exists. Pass overwrite: true to replace it.`);
+  }
+
+  await mkdir(dirname(absolute), { recursive: true });
+  await writeFile(absolute, content, 'utf8');
+
+  return json({ written: true, path: shown, bytes: Buffer.byteLength(content, 'utf8') });
+}
+
+export async function moveFile(
+  options: FsConnectorOptions,
+  excluded: ReadonlySet<string>,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+  const from = await confine(options, excluded, args['from']);
+  const to = await confine(options, excluded, args['to']);
+
+  if (!(await stat(from.absolute).catch(() => null))) return error(`"${from.relative}" is not there.`);
+  if (await stat(to.absolute).catch(() => null)) return error(`"${to.relative}" already exists.`);
+
+  await mkdir(dirname(to.absolute), { recursive: true });
+  await rename(from.absolute, to.absolute);
+
+  return json({ moved: true, from: from.relative, to: to.relative });
+}
+
+export async function createFolder(
+  options: FsConnectorOptions,
+  excluded: ReadonlySet<string>,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+  const { absolute, relative: shown } = await confine(options, excluded, args['path']);
+  await mkdir(absolute, { recursive: true });
+  return json({ created: true, path: shown });
+}
+
+/**
+ * Move to the system Trash rather than unlinking.
+ *
+ * Same reasoning as mail: an agent that can permanently destroy a file is a
+ * different risk class from one that can tidy up, and the Finder's Trash is a
+ * recovery path everyone already knows. If the Trash is on another volume the
+ * rename fails, and refusing beats falling back to a real delete.
+ */
+export async function trashFile(
+  options: FsConnectorOptions,
+  excluded: ReadonlySet<string>,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+  const { absolute, relative: shown } = await confine(options, excluded, args['path']);
+  if (!(await stat(absolute).catch(() => null))) return error(`"${shown}" is not there.`);
+
+  const trash = join(homedir(), '.Trash');
+  let target = join(trash, basename(absolute));
+  for (let attempt = 1; await stat(target).catch(() => null); attempt++) {
+    target = join(trash, `${basename(absolute)} ${attempt}`);
+  }
+
+  try {
+    await rename(absolute, target);
+  } catch {
+    return error(
+      `"${shown}" could not be moved to the Trash, and nothing here deletes permanently. Move it somewhere else instead.`,
+    );
+  }
+
+  return json({ trashed: true, path: shown, recoverable_from: '~/.Trash' });
+}
+
+/** A NUL byte in the first block is the practical test for "not text". */
+export function looksBinary(bytes: Uint8Array): boolean {
+  return bytes.subarray(0, 4096).includes(0);
+}

package/src/connectivity/transports/fs/index.ts

@@ -0,0 +1,121 @@
+import { mkdir, readdir, readFile, realpath, rename, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import {
+  READ_BUNDLE,
+  WRITE_BUNDLE,
+  type Connector,
+  type DiscoveredCapability,
+  type ToolResult,
+} from '#connectivity';
+
+/**
+ * The `fs` connector — a directory on this machine.
+ *
+ * Vendor-neutral, like the rest: it is a folder. iCloud Drive is a manifest
+ * pointing at `~/Library/Mobile Documents/com~apple~CloudDocs`, and the same
+ * connector serves a Dropbox folder, a Syncthing share, or a project directory.
+ *
+ * **It only works where the files are.** There is no credential here and nothing
+ * to export: access to iCloud Drive is a TCC grant bound to a binary on one Mac,
+ * not a token. That is why a cloud instance cannot serve this kind and must
+ * instead reach a local one — see `docs/detailed/adr/011-local-filesystem.md`.
+ *
+ * ## The guard that matters
+ *
+ * Everything else in this file is ordinary. `confine()` is not: it is the only
+ * thing standing between an agent and the rest of the disk, and on a Mac with
+ * "Desktop & Documents" syncing, the configured root contains almost everything
+ * a person owns. It resolves the *real* path — following symlinks — before
+ * comparing, because a symlink inside the root pointing at `~/.ssh` is otherwise
+ * a perfectly ordinary-looking file.
+ */
+
+export interface FsConnectorOptions {
+  readonly root: string;
+  readonly maxFileBytes: number;
+  /** Names never listed, read, or written. Matched against each path segment. */
+  readonly exclude: readonly string[];
+  /**
+   * How this folder's sync client marks an undownloaded file, if it uses one,
+   * and what to tell someone who hits it. Declared by the provider — this
+   * transport must not know which client it is.
+   */
+  readonly placeholder?: { readonly suffix: string; readonly hint?: string | undefined } | undefined;
+}
+
+
+import { fsCapabilities } from './capabilities.ts';
+import { ALWAYS_EXCLUDED, OPERATIONS } from './operations.ts';
+import { rootOf } from './paths.ts';
+import { error } from './result.ts';
+import {
+  createFolder,
+  fileInfo,
+  listFiles,
+  moveFile,
+  readTextFile,
+  searchFiles,
+  trashFile,
+  writeTextFile,
+} from './commands.ts';
+
+export function createFsConnector(options: FsConnectorOptions): Connector {
+  const excluded = new Set([...ALWAYS_EXCLUDED, ...options.exclude]);
+
+  return {
+    kind: 'fs',
+
+    async discover(): Promise<DiscoveredCapability[]> {
+      // The root has to exist and be readable. On a machine that is not the one
+      // holding the files this fails here, at `connect`, rather than as a
+      // puzzling empty listing later.
+      await rootOf(options);
+
+      return fsCapabilities();
+    },
+
+    /**
+     * Which folder this is.
+     *
+     * There is no account here, so the identity is the location — which is also
+     * the only thing that distinguishes two folder connections from each other.
+     * Abbreviated to `~` because the absolute form is long and says less.
+     */
+    async identify(): Promise<string | null> {
+      const resolved = await rootOf(options);
+      const home = homedir();
+      return resolved.startsWith(home + sep) ? `~${resolved.slice(home.length)}` : resolved;
+    },
+
+    async invoke(capability, args): Promise<ToolResult> {
+      const operation = String(capability.target?.['operation'] ?? capability.name);
+
+      try {
+        switch (operation) {
+          case OPERATIONS.listFiles:
+            return await listFiles(options, excluded, args);
+          case OPERATIONS.searchFiles:
+            return await searchFiles(options, excluded, args);
+          case OPERATIONS.readFile:
+            return await readTextFile(options, excluded, args);
+          case OPERATIONS.fileInfo:
+            return await fileInfo(options, excluded, args);
+          case OPERATIONS.writeFile:
+            return await writeTextFile(options, excluded, args);
+          case OPERATIONS.moveFile:
+            return await moveFile(options, excluded, args);
+          case OPERATIONS.createFolder:
+            return await createFolder(options, excluded, args);
+          case OPERATIONS.trashFile:
+            return await trashFile(options, excluded, args);
+          default:
+            return error(`Unknown operation "${operation}".`);
+        }
+      } catch (failure) {
+        return error((failure as Error).message);
+      }
+    },
+  };
+}
+

package/src/connectivity/transports/fs/operations.ts

@@ -0,0 +1,45 @@
+/**
+ * The operation names an `fs` connection exposes, plus the exclusions and
+ * argument shapes they share.
+ *
+ * `ALWAYS_EXCLUDED` is a security control rather than a tidiness one: the
+ * configured root on a Mac with Desktop & Documents syncing contains almost
+ * everything a person owns, and these are the names that must never be listed
+ * or read whatever the manifest says.
+ */
+
+export const OPERATIONS = {
+  listFiles: 'list_files',
+  readFile: 'read_file',
+  searchFiles: 'search_files',
+  fileInfo: 'file_info',
+  writeFile: 'write_file',
+  moveFile: 'move_file',
+  createFolder: 'create_folder',
+  trashFile: 'trash_file',
+} as const;
+
+/**
+ * Never traversed, whatever the manifest says.
+ *
+ * `.git` is here because a repository in a synced folder holds credentials in
+ * its config and the entire history of everything else; the rest are metadata
+ * nobody means to read.
+ */
+export const ALWAYS_EXCLUDED = ['.git', '.ssh', '.gnupg', 'node_modules', '.DS_Store', '.Trash'];
+
+export const object = (
+  properties: Record<string, unknown>,
+  required: string[] = [],
+): Record<string, unknown> => ({
+  type: 'object',
+  properties,
+  ...(required.length > 0 ? { required } : {}),
+  additionalProperties: false,
+});
+
+export const pathArgument = {
+  type: 'string',
+  description: 'Path relative to the folder root. "" or "." is the root itself.',
+};
+

package/src/connectivity/transports/fs/paths.ts

@@ -0,0 +1,120 @@
+import { readdir, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, relative, resolve, sep, basename, dirname } from 'node:path';
+import { ALWAYS_EXCLUDED } from './operations.ts';
+import type { FsConnectorOptions } from './index.ts';
+
+/**
+ * Resolving a path, and refusing the ones that leave the root.
+ *
+ * `confine()` is the only thing standing between an agent and the rest of the
+ * disk. It resolves the *real* path — following symlinks — before comparing,
+ * because a symlink inside the root pointing at `~/.ssh` is otherwise a
+ * perfectly ordinary-looking file. Its own file so that the guard is one thing
+ * to read and one thing to review, rather than forty lines in the middle of ten
+ * operations.
+ */
+
+export async function rootOf(options: FsConnectorOptions): Promise<string> {
+  const expanded = options.root.startsWith('~')
+    ? join(homedir(), options.root.slice(1))
+    : options.root;
+
+  try {
+    return await realpath(resolve(expanded));
+  } catch {
+    throw new Error(
+      `The folder ${expanded} is not there. This connector reads files on *this* machine, so it only works where they are.`,
+    );
+  }
+}
+
+/**
+ * Resolve a caller-supplied path, and refuse anything outside the root.
+ *
+ * The real path is resolved first, so a symlink inside the root pointing at
+ * `~/.ssh` is caught rather than followed. A path that does not exist yet is
+ * checked against its nearest existing ancestor — a write must be confined too,
+ * and `realpath` cannot resolve a file that is not there.
+ */
+export async function confine(
+  options: FsConnectorOptions,
+  excluded: ReadonlySet<string>,
+  candidate: unknown,
+): Promise<{ absolute: string; relative: string; root: string }> {
+  const root = await rootOf(options);
+  const requested = typeof candidate === 'string' ? candidate : '';
+
+  if (requested.startsWith('~') || resolve(requested) === requested) {
+    // An absolute path or a home-relative one is never what a caller inside a
+    // rooted folder means, and accepting it would make the root advisory.
+    if (requested !== '') {
+      throw new Error(`Give a path relative to the folder root, not "${requested}".`);
+    }
+  }
+
+  const absolute = resolve(root, requested);
+
+  for (const segment of relative(root, absolute).split(sep)) {
+    if (segment && excluded.has(segment)) {
+      throw new Error(`"${segment}" is excluded from this folder.`);
+    }
+  }
+
+  // Walk up to the nearest path that exists, so a not-yet-created file is still
+  // confined by where it *would* go.
+  let existing = absolute;
+  for (;;) {
+    try {
+      existing = await realpath(existing);
+      break;
+    } catch {
+      const parent = dirname(existing);
+      if (parent === existing) throw new Error(`Cannot resolve "${requested}".`);
+      existing = parent;
+    }
+  }
+
+  const within = existing === root || existing.startsWith(root + sep);
+  if (!within) {
+    throw new Error(
+      `"${requested}" resolves outside the folder root, so it was refused. ` +
+        `This usually means a symlink pointing elsewhere.`,
+    );
+  }
+
+  return { absolute, relative: relative(root, absolute) || '.', root };
+}
+
+/**
+ * Whether the sync client has evicted the file's contents.
+ *
+ * With "Optimise Mac Storage" on, a file that has not been opened recently is
+ * replaced by a hidden `.name<suffix>` placeholder holding a plist, and the real
+ * bytes live only in the cloud. Reading the placeholder returns a few hundred
+ * bytes of XML — which looks like a corrupt file rather than a missing one, so
+ * it is worth naming.
+ */
+export async function placeholderFor(
+  absolute: string,
+  suffix: string | undefined,
+): Promise<string | null> {
+  if (!suffix) return null;
+  const candidate = join(dirname(absolute), `.${basename(absolute)}${suffix}`);
+  try {
+    await stat(candidate);
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether a directory entry is a sync client's placeholder rather than a file.
+ *
+ * The suffix is declared by the provider (`placeholder_suffix`), so this
+ * transport never learns which sync client it is looking at.
+ */
+export function isPlaceholder(name: string, suffix: string | undefined): boolean {
+  return suffix !== undefined && name.startsWith('.') && name.endsWith(suffix);
+}

package/src/connectivity/transports/fs/result.ts

@@ -0,0 +1,12 @@
+import type { ToolResult } from '#connectivity';
+
+/** The two result shapes every operation returns. */
+
+export function error(message: string): ToolResult {
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+export function json(value: unknown): ToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+