feat(fs): add directory listing seam

packages/fs/fs-local/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-fs-local
 
-The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the six `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
+The **local-filesystem implementation** of the `ctx.fs` provider seam ([`@deepseek-ai/dsh-fs`](../fs)). Backs the seven `FileSystem` primitives with the host filesystem; loading it as a plugin populates `ctx.fs`.
 
 ```ts ignore-check
 import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
@@ -15,6 +15,7 @@ await ctx.plugin(LocalFileSystem, { cwd: process.cwd() })
 - **`resolve(path, opts?)`** — a relative `path` resolves against `opts.cwd` when the caller supplies one (the model-facing tools pass the calling agent's session cwd — see [the per-session cwd RFC](../../../docs/rfc/implemented/architecture/2026-07-02-fs-per-session-cwd.md)), else `config.cwd` (default `process.cwd()`); an absolute `path` ignores both. The `targetKey` is the file's `realpath`, so two input paths reaching the same file through symlinks share one identity, and writes/edits land on the link target (preserving the link). A not-yet-existing path uses the realpathed parent directory plus basename when the parent exists; only an unresolvable parent falls back to the absolute path. `displayPath` is the absolute (un-resolved) path.
 - **`stat`** — returns `FsInfo` (`version` = `mtimeMs:size`, `type` of `file`/`directory`/`other`, byte `size`) or `undefined` when the target is absent.
 - **`readText` / `streamText`** — UTF-8 only. `readText` reads the whole file; `streamText` streams it in chunks (cross-chunk decoding) so a huge file never has to be held whole in memory. Both reject invalid UTF-8 and NUL-byte binary samples (`FS_NOT_TEXT`) and non-regular targets. The `read` tool (`@deepseek-ai/dsh-tool-fs`) decides which to call by size and owns the line windowing.
+- **`listDir`** — lists one directory level in stable `name.localeCompare()` order. Each entry carries the child basename, type, resolved child target (`displayPath` under the listed directory, `targetKey` as the realpath identity), and cheap stat metadata (`version`, plus `size` for regular files). It never opens or decodes file contents. Missing targets report `FS_NOT_FOUND`, file/special-file targets report `FS_NOT_DIRECTORY`, aborted calls report `FS_ABORTED`, permission failures report `FS_PERMISSION_DENIED`, and other `readdir` I/O failures report `FS_IO_ERROR`.
 - **`writeText`** — atomic: writes to a temp file opened exclusively (`wx`, `0o600`) inside a randomly-named private staging dir (`0o700`) next to the target, fsyncs, then renames over the target. An existing file's mode is preserved, while new files default to `0o600`. The `expected` guard is OPTIONAL: omitting it unconditionally creates-or-overwrites; `createIfAbsent` creates a missing target and rejects an existing one (`FS_NOT_OBSERVED`); `replaceIfVersion` replaces only at the observed version (a missing target or mismatch is `FS_STALE_VERSION`).
 - **`editText`** — atomic literal read-modify-write over the same primitive, serialized per target by a mutation lock. The `expected` guard is OPTIONAL: when supplied it verifies the version BEFORE literal matching (a stale edit reports `FS_STALE_VERSION`, never `FS_EDIT_NOT_FOUND`/`FS_AMBIGUOUS_EDIT` against newer content); omitting it edits the current content unconditionally. A missing target reports `FS_STALE_VERSION` either way. LF-normalizes for matching, restores the file's dominant CRLF/LF style, and rejects empty `oldString` / zero matches (`FS_EDIT_NOT_FOUND`) or ambiguous multi-matches without `replace_all` (`FS_AMBIGUOUS_EDIT`).
 

packages/fs/fs-local/src/fsio.ts

@@ -20,8 +20,8 @@
 
 import { randomUUID } from 'node:crypto'
 import { createReadStream } from 'node:fs'
-import { chmod, mkdir, open, readFile, realpath, rename, rm, stat } from 'node:fs/promises'
-import type { Stats } from 'node:fs'
+import { chmod, mkdir, open, readFile, realpath, readdir, rename, rm, stat } from 'node:fs/promises'
+import type { Dirent, Stats } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { TextDecoder } from 'node:util'
 import { FsError, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
@@ -55,6 +55,12 @@ function errorMessage(error: unknown): string {
 }
 /* v8 ignore stop */
 
+/* v8 ignore start -- requires permission/kernel failures from readdir after a successful directory stat. */
+function isPermissionError(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && (error.code === 'EACCES' || error.code === 'EPERM')
+}
+/* v8 ignore stop */
+
 function throwIfAborted(signal: AbortSignal | undefined, verb: string): void {
   if (signal?.aborted) throw new FsError(`${verb} aborted`, 'FS_ABORTED')
 }
@@ -112,6 +118,15 @@ export interface PathInfo {
   size: number
 }
 
+/** One local directory child with a resolved target and cheap metadata. */
+export interface LocalDirEntry {
+  name: string
+  type: 'file' | 'directory' | 'other'
+  target: LocalTarget
+  version?: FsVersion
+  size?: number
+}
+
 /**
  * Resolve a path to its absolute display path and realpath identity. Relative
  * paths are based on `cwd`. When the file itself does not yet exist, the
@@ -172,6 +187,51 @@ export async function probe(absolutePath: string): Promise<PathInfo | null> {
   }
 }
 
+// --- Directory listing ---
+
+/* v8 ignore start -- requires permission/kernel failures from readdir after a successful directory stat. */
+function listingIoError(displayPath: string, error: unknown): FsError {
+  if (isENOENT(error) || isENOTDIR(error)) return new FsError(`cannot list "${displayPath}": not found`, 'FS_NOT_FOUND', { cause: error })
+  if (isPermissionError(error)) return new FsError(`cannot list "${displayPath}": permission denied`, 'FS_PERMISSION_DENIED', { cause: error })
+  return new FsError(`cannot list "${displayPath}": ${errorMessage(error)}`, 'FS_IO_ERROR', { cause: error })
+}
+/* v8 ignore stop */
+
+/**
+ * List direct children of a directory in stable name order. Each child includes
+ * a resolved target plus stat metadata when still available; file contents are
+ * never read.
+ */
+export async function listDirectory(target: LocalTarget, signal?: AbortSignal): Promise<LocalDirEntry[]> {
+  throwIfAborted(signal, 'list')
+  const info = await probe(target.targetKey)
+  if (!info) throw new FsError(`cannot list "${target.displayPath}": not found`, 'FS_NOT_FOUND')
+  if (info.type !== 'directory') throw new FsError(`cannot list "${target.displayPath}": not a directory`, 'FS_NOT_DIRECTORY')
+
+  let entries: Dirent[]
+  try {
+    entries = await readdir(target.targetKey, { withFileTypes: true, encoding: 'utf8' })
+  } catch (error: unknown) {
+    /* v8 ignore next -- requires permission/kernel failure from readdir after a successful directory stat. */
+    throw listingIoError(target.displayPath, error)
+  }
+  throwIfAborted(signal, 'list')
+
+  return await Promise.all(entries
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map(async (entry): Promise<LocalDirEntry> => {
+      const childTarget = await resolveLocalTarget(target.displayPath, entry.name)
+      const childInfo = await probe(childTarget.targetKey)
+      return {
+        name: entry.name,
+        type: childInfo?.type ?? 'other',
+        target: childTarget,
+        ...(childInfo ? { version: childInfo.version } : {}),
+        ...(childInfo?.type === 'file' ? { size: childInfo.size } : {}),
+      }
+    }))
+}
+
 // --- Reading ---
 
 function notTextError(verb: 'read' | 'edit', displayPath: string): FsError {

packages/fs/fs-local/src/index.ts

@@ -1,6 +1,6 @@
 /**
  * Local-filesystem implementation of the `ctx.fs` provider seam.
- * {@link LocalFileSystem} subclasses {@link FileSystem} and backs the six
+ * {@link LocalFileSystem} subclasses {@link FileSystem} and backs the seven
  * text-storage primitives with the host filesystem via
  * {@link module:@deepseek-ai/dsh-fs-local/fsio}. Path resolution uses
  * `realpath`, so the stable `targetKey` is the real file identity (two input
@@ -17,6 +17,7 @@ import { Context } from 'cordis'
 import z from 'schemastery'
 import { FileSystem, FsError, FsVersion } from '@deepseek-ai/dsh-fs'
 import type {
+  FsDirEntry,
   FsEditOutcome,
   FsEditRequest,
   FsInfo,
@@ -26,6 +27,7 @@ import type {
 } from '@deepseek-ai/dsh-fs'
 import {
   applyLiteralEdit,
+  listDirectory,
   probe,
   readForEdit,
   readWholeText,
@@ -39,6 +41,7 @@ import type { FsIoInternals } from './fsio.ts'
 export {
   STREAM_MIN_SIZE,
   applyLiteralEdit,
+  listDirectory,
   probe,
   readForEdit,
   readWholeText,
@@ -47,7 +50,7 @@ export {
   streamWholeText,
   writeFileAtomic,
 } from './fsio.ts'
-export type { FsIoInternals, LineEndings, LocalTarget, PathInfo } from './fsio.ts'
+export type { FsIoInternals, LineEndings, LocalDirEntry, LocalTarget, PathInfo } from './fsio.ts'
 
 /** Configuration for the local filesystem backend. */
 export interface Config {
@@ -117,6 +120,17 @@ export class LocalFileSystem extends FileSystem {
     return Promise.resolve(streamWholeText({ displayPath: target.displayPath, targetKey: target.targetKey }, signal))
   }
 
+  override async listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]> {
+    const entries = await listDirectory({ displayPath: target.displayPath, targetKey: target.targetKey }, signal)
+    return entries.map(entry => ({
+      name: entry.name,
+      type: entry.type,
+      target: { inputPath: entry.target.displayPath, targetKey: entry.target.targetKey, displayPath: entry.target.displayPath },
+      ...(entry.version !== undefined ? { version: entry.version } : {}),
+      ...(entry.size !== undefined ? { size: entry.size } : {}),
+    }))
+  }
+
   override async writeText(
     target: FsTarget,
     content: string,

packages/fs/fs-local/tests/filesystem.spec.ts

@@ -7,7 +7,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { mkdtemp, readFile, rm, stat, symlink, writeFile, unlink } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, realpath, rm, stat, symlink, writeFile, unlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from 'cordis'
@@ -118,6 +118,50 @@ describe('readText / streamText', () => {
   })
 })
 
+describe('listDir', () => {
+  it('lists files and directories in stable name order with resolved child targets', async () => {
+    await mkdir(join(dir, 'skills', 'dir-skill'), { recursive: true })
+    await writeFile(join(dir, 'skills', 'zeta.md'), 'zeta')
+    await writeFile(join(dir, 'skills', 'alpha.md'), 'alpha')
+    await symlink(join(dir, 'skills', 'missing-target'), join(dir, 'skills', 'broken-link'))
+
+    const entries = await fs.listDir(await fs.resolve('skills'))
+    expect(entries.map(entry => [entry.name, entry.type])).toEqual([
+      ['alpha.md', 'file'],
+      ['broken-link', 'other'],
+      ['dir-skill', 'directory'],
+      ['zeta.md', 'file'],
+    ])
+    expect(entries.map(entry => entry.target.displayPath)).toEqual([
+      join(dir, 'skills', 'alpha.md'),
+      join(dir, 'skills', 'broken-link'),
+      join(dir, 'skills', 'dir-skill'),
+      join(dir, 'skills', 'zeta.md'),
+    ])
+    const materializedEntries = entries.filter(entry => entry.version !== undefined)
+    expect(materializedEntries.map(entry => entry.target.targetKey))
+      .toEqual(await Promise.all(materializedEntries.map(entry => realpath(entry.target.displayPath))))
+    expect(entries.find(entry => entry.name === 'alpha.md')?.size).toBe(5)
+    expect(typeof entries.find(entry => entry.name === 'alpha.md')?.version).toBe('string')
+    expect(entries.find(entry => entry.name === 'broken-link')?.version).toBeUndefined()
+    expect(entries.find(entry => entry.name === 'dir-skill')?.size).toBeUndefined()
+  })
+
+  it('reports a missing directory as FS_NOT_FOUND', async () => {
+    await expect(fs.listDir(await fs.resolve('missing'))).rejects.toMatchObject({ code: 'FS_NOT_FOUND' })
+  })
+
+  it('reports a file target as FS_NOT_DIRECTORY', async () => {
+    await writeFile(join(dir, 'a.txt'), 'text')
+    await expect(fs.listDir(await fs.resolve('a.txt'))).rejects.toMatchObject({ code: 'FS_NOT_DIRECTORY' })
+  })
+
+  it('honors a pre-aborted signal', async () => {
+    await mkdir(join(dir, 'skills'), { recursive: true })
+    await expect(fs.listDir(await fs.resolve('skills'), AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
+  })
+})
+
 describe('writeText', () => {
   it('createIfAbsent creates a new file', async () => {
     const target = await fs.resolve('new.txt')

packages/fs/fs-local/tests/fsio.spec.ts

@@ -12,6 +12,7 @@ import { join } from 'node:path'
 import { createServer } from 'node:net'
 import {
   applyLiteralEdit,
+  listDirectory,
   probe,
   readForEdit,
   readWholeText,
@@ -145,6 +146,36 @@ describe('probe', () => {
   })
 })
 
+describe('listDirectory', () => {
+  it('lists direct children in stable order without reading content', async () => {
+    const root = join(dir, 'skills')
+    await mkdir(join(root, 'dir-skill'), { recursive: true })
+    await writeFile(join(root, 'zeta.md'), 'zeta')
+    await writeFile(join(root, 'alpha.md'), 'alpha')
+    await symlink(join(root, 'missing-target'), join(root, 'broken-link'))
+
+    const entries = await listDirectory(localTarget(root))
+    expect(entries.map(entry => [entry.name, entry.type])).toEqual([
+      ['alpha.md', 'file'],
+      ['broken-link', 'other'],
+      ['dir-skill', 'directory'],
+      ['zeta.md', 'file'],
+    ])
+    expect(entries.find(entry => entry.name === 'alpha.md')?.size).toBe(5)
+    expect(typeof entries.find(entry => entry.name === 'alpha.md')?.version).toBe('string')
+    expect(entries.find(entry => entry.name === 'broken-link')?.version).toBeUndefined()
+    expect(entries.find(entry => entry.name === 'dir-skill')?.size).toBeUndefined()
+  })
+
+  it('rejects missing, non-directory, and aborted listing requests', async () => {
+    await expect(listDirectory(localTarget(join(dir, 'missing')))).rejects.toMatchObject({ code: 'FS_NOT_FOUND' })
+    const file = join(dir, 'a.txt')
+    await writeFile(file, 'hi')
+    await expect(listDirectory(localTarget(file))).rejects.toMatchObject({ code: 'FS_NOT_DIRECTORY' })
+    await expect(listDirectory(localTarget(dir), AbortSignal.abort())).rejects.toMatchObject({ code: 'FS_ABORTED' })
+  })
+})
+
 describe('readWholeText', () => {
   it('reads a small file', async () => {
     const file = join(dir, 'a.txt')