Handle permission errors gracefully, matching Linux tree behavior

Instead of crashing on inaccessible directories (e.g. "System Volume
Information" on Windows), show them with [error opening dir] like
Linux tree does. Fixes #41.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: yangshun

README.md

@@ -4,7 +4,7 @@ Lists the contents of directories in a tree-like format, similar to the Linux [`
 
 `tree` is a command that produces a nicely-formatted indented output of directories and files. When a directory argument is given, tree lists all the files and/or directories found in the given directory.
 
-Note: Symlinks are not followed.
+Note: Symlinks are not followed. Directories that cannot be opened (e.g. due to permission errors) are listed with `[error opening dir]` instead of crashing, matching Linux `tree` behavior.
 
 ## Quickstart
 
@@ -130,6 +130,7 @@ type TreeJsonEntry =
 // size: present when `sizes: true`
 // mode: present when `permissions: true`
 // time: present when `date: true`
+// error: present when the directory could not be opened (e.g. permission denied)
 ```
 
 ```js

src/formats/json.ts

@@ -6,6 +6,7 @@ interface TreeJsonEntryBase {
   size?: number;
   mode?: string;
   time?: string;
+  error?: string;
 }
 
 interface TreeJsonDirectoryEntry extends TreeJsonEntryBase {
@@ -39,6 +40,10 @@ export function formatAsJson(
     base.time = `${node.mtime.toLocaleDateString('en-CA')} ${node.mtime.toLocaleTimeString('en-GB')}`;
   }
 
+  if (node.openError) {
+    base.error = 'error opening dir';
+  }
+
   if (node.isDirectory) {
     return {
       ...base,

src/formats/text.test.ts

@@ -163,6 +163,30 @@ describe('formatAsText', () => {
     expect(lines[0]).toMatch(/^\[.+\] a\.ts$/);
   });
 
+  test('openError shows [error opening dir]', () => {
+    const node = makeDir('root', [
+      makeDir('forbidden', [], { path: 'root/forbidden', openError: true }),
+      makeFile('ok.txt', { path: 'root/ok.txt' }),
+    ]);
+    const lines = formatAsText(node, opts(), '.');
+    expect(lines).toEqual([
+      'root',
+      '├── forbidden [error opening dir]',
+      '└── ok.txt',
+    ]);
+  });
+
+  test('openError with trailingSlash', () => {
+    const node = makeDir('root', [
+      makeDir('forbidden', [], { path: 'root/forbidden', openError: true }),
+    ]);
+    const lines = formatAsText(node, opts({ trailingSlash: true }), '.');
+    expect(lines).toEqual([
+      'root/',
+      '└── forbidden/ [error opening dir]',
+    ]);
+  });
+
   test('vertical line for non-last siblings', () => {
     const node = makeDir('root', [
       makeDir('dir1', [makeFile('file.txt', { path: 'root/dir1/file.txt' })], {

src/formats/text.ts

@@ -63,6 +63,10 @@ export function formatAsText(
     line.push('/');
   }
 
+  if (node.openError) {
+    line.push(' [error opening dir]');
+  }
+
   const lines = [line.join('')];
 
   // Recurse into children.

src/index.test.ts

@@ -643,6 +643,53 @@ describe('tree error handling', () => {
     expect(lines).toHaveLength(1);
     expect(lines[0]).toBe('alpha.txt');
   });
+
+  test('shows [error opening dir] for inaccessible directories', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tree-perm-'));
+    const forbidden = path.join(tmpDir, 'forbidden');
+    fs.mkdirSync(forbidden);
+    fs.writeFileSync(path.join(tmpDir, 'ok.txt'), 'hello');
+    // Remove all permissions from the directory.
+    fs.chmodSync(forbidden, 0o000);
+
+    const result = tree(tmpDir);
+    expect(result).toContain('forbidden [error opening dir]');
+    expect(result).toContain('ok.txt');
+
+    // Restore permissions for cleanup.
+    fs.chmodSync(forbidden, 0o755);
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  test('json includes error for inaccessible directories', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tree-perm-'));
+    const forbidden = path.join(tmpDir, 'forbidden');
+    fs.mkdirSync(forbidden);
+    fs.chmodSync(forbidden, 0o000);
+
+    const result = asDir(treeJson(tmpDir));
+    const entry = result.contents.find((c) => c.name === 'forbidden');
+    expect(entry).toBeDefined();
+    expect((entry as any).error).toBe('error opening dir');
+
+    fs.chmodSync(forbidden, 0o755);
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  test('du handles inaccessible directories gracefully', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tree-perm-'));
+    const forbidden = path.join(tmpDir, 'forbidden');
+    fs.mkdirSync(forbidden);
+    fs.writeFileSync(path.join(tmpDir, 'ok.txt'), 'hello');
+    fs.chmodSync(forbidden, 0o000);
+
+    const result = tree(tmpDir, { du: true });
+    expect(result).toContain('forbidden [error opening dir]');
+    expect(result).toContain('ok.txt');
+
+    fs.chmodSync(forbidden, 0o755);
+    fs.rmSync(tmpDir, { recursive: true });
+  });
 });
 
 describe('tree with symlinks', () => {

src/index.ts

@@ -64,6 +64,7 @@ export interface TreeNode {
   mtime: Date;
   size: number;
   children: TreeNode[];
+  openError?: boolean;
 }
 
 // ── Build tree ─────────────────────────────────────────────
@@ -98,14 +99,20 @@ function matchesExcludePattern(
 function statEntries(
   dirPath: string,
   entries: string[],
-): Map<string, fs.Stats> {
+): { stats: Map<string, fs.Stats>; accessible: string[] } {
   const stats = new Map<string, fs.Stats>();
+  const accessible: string[] = [];
 
   for (const entry of entries) {
-    stats.set(entry, fs.lstatSync(nodePath.join(dirPath, entry)));
+    try {
+      stats.set(entry, fs.lstatSync(nodePath.join(dirPath, entry)));
+      accessible.push(entry);
+    } catch {
+      // Skip entries that cannot be stat'd (e.g. permission denied).
+    }
   }
 
-  return stats;
+  return { stats, accessible };
 }
 
 /**
@@ -189,19 +196,25 @@ function filterAndOrderContents(
 function getDirectoryContents(
   dirPath: string,
   options: RequiredOptions,
-): { entries: string[]; stats: Map<string, fs.Stats> } {
-  let entries = fs.readdirSync(dirPath);
+): { entries: string[]; stats: Map<string, fs.Stats>; openError: boolean } {
+  let entries: string[];
+
+  try {
+    entries = fs.readdirSync(dirPath);
+  } catch {
+    return { entries: [], stats: new Map(), openError: true };
+  }
 
   // Filter hidden files before stat'ing to avoid unnecessary syscalls.
   if (!options.allFiles) {
     entries = entries.filter((entry) => !isHiddenFile(entry));
   }
 
-  const stats = statEntries(dirPath, entries);
-  const sorted = sortContentsInPlace(entries, stats, options);
+  const { stats, accessible } = statEntries(dirPath, entries);
+  const sorted = sortContentsInPlace(accessible, stats, options);
   const filtered = filterAndOrderContents(sorted, stats, options);
 
-  return { entries: filtered, stats };
+  return { entries: filtered, stats, openError: false };
 }
 
 /**
@@ -212,10 +225,24 @@ function getDirectoryContents(
  */
 function computeSizes(dirPath: string, cache: Map<string, number>): number {
   let size = 0;
+  let entries: string[];
+
+  try {
+    entries = fs.readdirSync(dirPath);
+  } catch {
+    cache.set(dirPath, 0);
+    return 0;
+  }
 
-  for (const entry of fs.readdirSync(dirPath)) {
+  for (const entry of entries) {
     const entryPath = nodePath.join(dirPath, entry);
-    const stat = fs.lstatSync(entryPath);
+
+    let stat: fs.Stats;
+    try {
+      stat = fs.lstatSync(entryPath);
+    } catch {
+      continue;
+    }
 
     if (stat.isDirectory()) {
       size += computeSizes(entryPath, cache);
@@ -267,7 +294,11 @@ function buildTree(
     return node;
   }
 
-  const { entries, stats } = getDirectoryContents(path, options);
+  const { entries, stats, openError } = getDirectoryContents(path, options);
+
+  if (openError) {
+    node.openError = true;
+  }
 
   for (const entry of entries) {
     const child = buildTree(