clank-cli 0.1.59 → 0.1.61

package/README.md

@@ -8,6 +8,7 @@ Common commands:
 - **`clank link`** to connect overlay files to your project.
 - **`clank commit`** to commit changes in the overlay repository.
 - **`clank check`** to show overlay status and find misaligned files.
+- **`clank files`** to list clank-managed files for piping into tools like `rg`.
 
 ## Why a Separate Repository?
 
@@ -137,6 +138,29 @@ clank check
 # The following overlay files no longer match...
 ```
 
+### `clank files [path]`
+
+List clank-managed files in the current repo as paths relative to your current directory (useful for `xargs rg` workflows).
+
+By default, this includes `clank/` files and agent files (`AGENTS.md`, etc.), but excludes dot-prefixed directories like `.claude/` and `.gemini/`. Use `--hidden` to include those.
+
+**Options:**
+- `--hidden` - Include files under dot-prefixed directories (`.claude/`, `.gemini/`)
+- `--depth <n>` - Max depth under `clank/` directories (e.g. `--depth 1` includes `*/clank/*.md` but excludes `*/clank/*/*.md`)
+- `-0, --null` - NUL-separate output paths (recommended when piping to `xargs`)
+- `--no-dedupe` - Disable deduplication of agent files and prompts
+- `--linked-only` - Only include symlinks into the overlay
+- `--unlinked-only` - Only include non-overlay files/symlinks
+- `--global|--project|--worktree` - Only include linked files from that scope (implies `--linked-only`)
+
+**Examples:**
+```bash
+clank files -0 | xargs -0 rg "TODO"
+clank files --depth 1
+clank files --hidden | rg '^\\.claude/'
+clank files .               # Only this directory/subtree (relative to cwd)
+```
+
 ### `clank rm <files...>` (alias: `remove`)
 
 Remove file(s) from both the overlay repository and the local project symlinks. Accepts [scope options](#scope-options); if omitted, clank detects the scope from the symlink.
@@ -226,16 +250,18 @@ export default {
   overlayRepo: "~/clankover",
   agents: ["agents", "claude", "gemini"],
   vscodeSettings: "auto",  // "auto" | "always" | "never"
-  vscodeGitignore: true
+  vscodeGitignore: true,
+  ignore: [".obsidian", "*.bak"]
 };
 ```
 
-- `agents` - which symlinks to create for agent files like CLAUDE.md
+- `agents` - which symlinks to create for agent files like CLAUDE.md; also controls which agent file/prompt path is preferred for `clank files` output when deduping.
 - `vscodeSettings` - when to generate `.vscode/settings.json` to show clank files in VS Code
   - `"auto"` (default): only if project already has a `.vscode` directory
   - `"always"`: always generate settings
   - `"never"`: never auto-generate (you can still run `clank vscode` manually)
 - `vscodeGitignore` - add `.vscode/settings.json` to `.git/info/exclude` (default: true)
+- `ignore` - glob patterns to skip in the overlay (e.g., `[".obsidian", "*.bak", ".DS_Store"]`).
 
 By default, clank creates symlinks for AGENTS.md, CLAUDE.md, and GEMINI.md.
 Run `clank unlink` then `clank link` to apply config changes.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clank-cli",
   "description": "Keep AI files in a separate overlay repository",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "author": "",
   "type": "module",
   "bin": {
@@ -14,11 +14,13 @@
   "repository": "github:mighdoll/clank",
   "dependencies": {
     "commander": "^14.0.2",
-    "cosmiconfig": "^9.0.0"
+    "cosmiconfig": "^9.0.0",
+    "picomatch": "^4.0.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.8",
+    "@biomejs/biome": "^2.3.10",
     "@types/node": "^24.10.1",
+    "@types/picomatch": "^4.0.2",
     "@typescript/native-preview": "7.0.0-dev.20251221.1",
     "@vitest/ui": "^4.0.16",
     "execa": "^9.6.1",

package/src/Cli.ts

@@ -4,6 +4,7 @@ import { defaultOverlayDir, setConfigPath } from "./Config.ts";
 import { addCommand } from "./commands/Add.ts";
 import { checkCommand } from "./commands/Check.ts";
 import { commitCommand } from "./commands/Commit.ts";
+import { filesCommand } from "./commands/Files.ts";
 import { initCommand } from "./commands/Init.ts";
 import { linkCommand } from "./commands/Link.ts";
 import { moveCommand } from "./commands/Move.ts";
@@ -145,6 +146,8 @@ function registerUtilityCommands(program: Command): void {
     .description("Show overlay status and check for issues")
     .action(withErrorHandling(checkCommand));
 
+  registerFilesCommand(program);
+
   program
     .command("vscode")
     .description("Generate VS Code settings to show clank files")
@@ -152,22 +155,64 @@ function registerUtilityCommands(program: Command): void {
     .action(withErrorHandling(vscodeCommand));
 }
 
+function registerFilesCommand(program: Command): void {
+  const files = program
+    .command("files")
+    .description("List clank-managed files (paths relative to cwd)")
+    .argument(
+      "[path]",
+      "Limit to this directory/subtree (relative to cwd; default: repo root)",
+    )
+    .option("--hidden", "Include files under dot-prefixed directories")
+    .option("--depth <n>", "Max depth under clank/ directories")
+    .option("-0, --null", "NUL-separate output paths")
+    .option("--no-dedupe", "Disable deduplication");
+
+  files.addOption(
+    new Option(
+      "-g, --global",
+      "Only include linked files from global scope",
+    ).conflicts(["project", "worktree"]),
+  );
+  files.addOption(
+    new Option(
+      "-p, --project",
+      "Only include linked files from project scope",
+    ).conflicts(["global", "worktree"]),
+  );
+  files.addOption(
+    new Option(
+      "-w, --worktree",
+      "Only include linked files from worktree scope",
+    ).conflicts(["global", "project"]),
+  );
+  files.addOption(
+    new Option(
+      "--linked-only",
+      "Only include symlinks into the overlay",
+    ).conflicts(["unlinkedOnly"]),
+  );
+  files.addOption(
+    new Option(
+      "--unlinked-only",
+      "Only include non-overlay files/symlinks",
+    ).conflicts(["linkedOnly"]),
+  );
+
+  files.action(withErrorHandling(filesCommand));
+}
+
 function registerHelpCommands(program: Command): void {
   const help = program
     .command("help")
     .description("Show help information")
     .argument("[command]", "Command to show help for")
     .action((commandName?: string) => {
-      if (!commandName) {
-        program.help();
-      }
+      if (!commandName) return program.help();
       const subcommand = program.commands.find((c) => c.name() === commandName);
-      if (subcommand) {
-        subcommand.help();
-      } else {
-        console.error(`Unknown command: ${commandName}`);
-        process.exit(1);
-      }
+      if (subcommand) return subcommand.help();
+      console.error(`Unknown command: ${commandName}`);
+      process.exit(1);
     });
   help
     .command("structure")

package/src/Config.ts

@@ -13,6 +13,8 @@ export interface ClankConfig {
   vscodeSettings?: "auto" | "always" | "never";
   /** Add .vscode/settings.json to .git/info/exclude (default: true) */
   vscodeGitignore?: boolean;
+  /** Patterns to ignore when walking overlay (e.g., [".obsidian", "*.bak"]) */
+  ignore?: string[];
 }
 
 const defaultConfig: ClankConfig = {

package/src/FsUtil.ts

@@ -1,3 +1,4 @@
+import type { Dirent } from "node:fs";
 import {
   lstat,
   mkdir,
@@ -11,6 +12,22 @@ import {
 import { dirname, isAbsolute, join, relative } from "node:path";
 import { execFileAsync } from "./Exec.ts";
 
+export interface WalkOptions {
+  /** Directories to skip (default: [".git", "node_modules"]) */
+  skipDirs?: string[];
+  /** Include dot-prefixed directories (default: true) */
+  includeHiddenDirs?: boolean;
+  /** Skip entries matching this predicate (checked before recursing into directories) */
+  skip?: (relPath: string, isDirectory: boolean) => boolean;
+}
+
+interface WalkContext {
+  root: string;
+  skipDirs: string[];
+  includeHidden: boolean;
+  skip?: (relPath: string, isDirectory: boolean) => boolean;
+}
+
 /**
  * Create a symbolic link, removing existing link/file first
  * @param target - The path the symlink should point to (absolute)
@@ -56,28 +73,27 @@ export function getLinkTarget(_from: string, to: string): string {
 /** Recursively walk a directory, yielding all files and directories */
 export async function* walkDirectory(
   dir: string,
-  options: { skipDirs?: string[] } = {},
+  options: WalkOptions = {},
+  rootDir?: string,
 ): AsyncGenerator<{ path: string; isDirectory: boolean }> {
-  const skipDirs = options.skipDirs || [".git", "node_modules"];
-
-  try {
-    const entries = await readdir(dir, { withFileTypes: true });
-
-    for (const entry of entries) {
-      if (skipDirs.includes(entry.name)) continue;
-
-      const fullPath = join(dir, entry.name);
-
-      if (entry.isDirectory()) {
-        yield { path: fullPath, isDirectory: true };
-        yield* walkDirectory(fullPath, options);
-      } else if (entry.isFile() || entry.isSymbolicLink()) {
-        yield { path: fullPath, isDirectory: false };
+  const ctx: WalkContext = {
+    root: rootDir ?? dir,
+    skipDirs: options.skipDirs ?? [".git", "node_modules"],
+    includeHidden: options.includeHiddenDirs ?? true,
+    skip: options.skip,
+  };
+
+  const entries = await tryReadDir(dir);
+  if (!entries) return;
+
+  for (const entry of entries) {
+    for (const result of processEntry(entry, dir, ctx)) {
+      if ("recurse" in result) {
+        yield* walkDirectory(result.recurse, result.options, result.root);
+      } else {
+        yield result;
       }
     }
-  } catch (_error) {
-    // Directory doesn't exist or can't be read
-    return;
   }
 }
 
@@ -161,3 +177,49 @@ export async function writeJsonFile(
 ): Promise<void> {
   await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`);
 }
+
+async function tryReadDir(dir: string): Promise<Dirent[] | null> {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+}
+
+function* processEntry(
+  entry: Dirent,
+  dir: string,
+  ctx: WalkContext,
+): Generator<
+  | { path: string; isDirectory: boolean }
+  | { recurse: string; options: WalkOptions; root: string }
+> {
+  const fullPath = join(dir, entry.name);
+  const relPath = relative(ctx.root, fullPath);
+
+  if (entry.isDirectory()) {
+    if (shouldSkipDir(entry.name, ctx.skipDirs, ctx.includeHidden)) return;
+    if (ctx.skip?.(relPath, true)) return;
+    yield { path: fullPath, isDirectory: true };
+    yield {
+      recurse: fullPath,
+      options: {
+        skipDirs: ctx.skipDirs,
+        includeHiddenDirs: ctx.includeHidden,
+        skip: ctx.skip,
+      },
+      root: ctx.root,
+    };
+  } else if (entry.isFile() || entry.isSymbolicLink()) {
+    if (ctx.skip?.(relPath, false)) return;
+    yield { path: fullPath, isDirectory: false };
+  }
+}
+
+function shouldSkipDir(
+  name: string,
+  skipDirs: string[],
+  includeHidden: boolean,
+): boolean {
+  return skipDirs.includes(name) || (!includeHidden && name.startsWith("."));
+}

package/src/Mapper.ts

@@ -153,7 +153,7 @@ function encodeTargetPath(relPath: string, overlayBase: string): string {
     }
   }
   // Files with clank/ in path → preserve structure
-  if (relPath.includes("clank/")) {
+  if (isClankPath(relPath)) {
     return join(overlayBase, relPath);
   }
   // Plain files → add clank/ prefix
@@ -217,6 +217,11 @@ export function normalizeAddPath(
   return join(normalizedCwd, "clank", filename);
 }
 
+/** Check if a relative path contains a clank/ directory component */
+export function isClankPath(relPath: string): boolean {
+  return relPath.startsWith("clank/") || relPath.includes("/clank/");
+}
+
 /** Check if a filename is an agent file (CLAUDE.md, GEMINI.md, AGENTS.md) */
 export function isAgentFile(filename: string): boolean {
   const name = basename(filename).toLowerCase();
@@ -278,7 +283,7 @@ function decodeOverlayPath(
   scope: Scope,
 ): TargetMapping | null {
   // clank/ files (at root or in subdirectories)
-  if (relPath.startsWith("clank/") || relPath.includes("/clank/")) {
+  if (isClankPath(relPath)) {
     return { targetPath: join(targetRoot, relPath), scope };
   }
 

package/src/OverlayLinks.ts

@@ -1,5 +1,6 @@
 import { lstat } from "node:fs/promises";
-import { dirname, join, relative } from "node:path";
+import { dirname, join } from "node:path";
+import picomatch from "picomatch";
 import { managedAgentDirs } from "./AgentFiles.ts";
 import {
   createSymlink,
@@ -73,16 +74,6 @@ export async function verifyManaged(
   }
 }
 
-/** Check if two paths are equivalent prompt files in different agent directories */
-function isMatchingPromptPath(
-  canonicalPath: string,
-  actualPath: string,
-): boolean {
-  const canonicalPrompt = getPromptRelPath(canonicalPath);
-  const actualPrompt = getPromptRelPath(actualPath);
-  return canonicalPrompt !== null && canonicalPrompt === actualPrompt;
-}
-
 /** Check if a path is a symlink pointing to the overlay repository */
 export async function isSymlinkToOverlay(
   linkPath: string,
@@ -104,15 +95,25 @@ export async function isSymlinkToOverlay(
 /** Walk overlay directory and yield all files that should be linked (excludes init/ templates) */
 export async function* walkOverlayFiles(
   overlayRoot: string,
+  ignorePatterns: string[] = [],
 ): AsyncGenerator<string> {
-  for await (const { path, isDirectory } of walkDirectory(overlayRoot, {
-    skipDirs: [".git", "node_modules"],
-  })) {
-    if (isDirectory) continue;
+  const isIgnored =
+    ignorePatterns.length > 0 ? picomatch(ignorePatterns) : null;
 
-    const relPath = relative(overlayRoot, path);
-    if (relPath.startsWith("clank/init/")) continue;
+  const skip = (relPath: string): boolean => {
+    // Skip templates
+    if (relPath.startsWith("clank/init/")) return true;
+    // Check ignore patterns against relative path and basename
+    if (isIgnored) {
+      const basename = relPath.split("/").at(-1) ?? "";
+      if (isIgnored(relPath) || isIgnored(basename)) return true;
+    }
+    return false;
+  };
 
+  const genEntries = walkDirectory(overlayRoot, { skip });
+  for await (const { path, isDirectory } of genEntries) {
+    if (isDirectory) continue;
     yield path;
   }
 }
@@ -133,3 +134,13 @@ export async function createPromptLinks(
   }
   return created;
 }
+
+/** Check if two paths are equivalent prompt files in different agent directories */
+function isMatchingPromptPath(
+  canonicalPath: string,
+  actualPath: string,
+): boolean {
+  const canonicalPrompt = getPromptRelPath(canonicalPath);
+  const actualPrompt = getPromptRelPath(actualPath);
+  return canonicalPrompt !== null && canonicalPrompt === actualPrompt;
+}

package/src/Util.ts

@@ -11,3 +11,13 @@ export function partition<T>(
   }
   return [pass, fail];
 }
+
+/** Filter an array, returning the truthy results of the filter function */
+export function filterMap<T, U>(arr: T[], fn: (t: T) => U | undefined): U[] {
+  const out: U[] = [];
+  for (const t of arr) {
+    const u = fn(t);
+    if (u) out.push(u);
+  }
+  return out;
+}

package/src/commands/Files.ts

@@ -0,0 +1,38 @@
+import { dedupeEntries } from "./files/Dedupe.ts";
+import {
+  collectEntries,
+  type FileEntry,
+  type FilesOptions,
+  getFilesContext,
+  normalizeFilesOptions,
+} from "./files/Scan.ts";
+
+/** List clank-managed files in the current target repository. */
+export async function filesCommand(
+  inputPath?: string,
+  options?: FilesOptions,
+): Promise<void> {
+  const ctx = await getFilesContext(inputPath);
+  const opts = normalizeFilesOptions(options);
+  const entries = await collectEntries(ctx, opts);
+  const output = buildOutput(entries, opts.dedupe, ctx.agentsPreference);
+  writeOutput(output, opts.null);
+}
+
+/** Convert filtered entries to sorted, cwd-relative output paths. */
+function buildOutput(
+  entries: FileEntry[],
+  dedupe: boolean,
+  agentsPreference: string[],
+): string[] {
+  const filtered = dedupe ? dedupeEntries(entries, agentsPreference) : entries;
+  return filtered
+    .map((e) => e.cwdRelativePath)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+/** Emit the final list in a form that is friendly to `xargs` and friends. */
+function writeOutput(paths: string[], nul: boolean): void {
+  const sep = nul ? "\0" : "\n";
+  process.stdout.write(paths.join(sep) + (paths.length === 0 ? "" : sep));
+}

package/src/commands/Link.ts

@@ -69,7 +69,13 @@ export async function linkCommand(targetDir?: string): Promise<void> {
   await maybeInitWorktree(overlayRoot, gitContext);
 
   // Collect and separate mappings (agents.md and prompts get special handling)
-  const mappings = await overlayMappings(overlayRoot, gitContext, targetRoot);
+  const ignorePatterns = config.ignore ?? [];
+  const mappings = await overlayMappings(
+    overlayRoot,
+    gitContext,
+    targetRoot,
+    ignorePatterns,
+  );
   const agentsMappings = mappings.filter(
     (m) => basename(m.targetPath) === "agents.md",
   );
@@ -170,25 +176,27 @@ async function overlayMappings(
   overlayRoot: string,
   gitContext: GitContext,
   targetRoot: string,
+  ignorePatterns: string[] = [],
 ): Promise<FileMapping[]> {
   const context: MapperContext = { overlayRoot, targetRoot, gitContext };
   const overlayGlobal = join(overlayRoot, "global");
   const overlayProject = overlayProjectDir(overlayRoot, gitContext.projectName);
 
   return [
-    ...(await dirMappings(overlayGlobal, context)),
-    ...(await dirMappings(overlayProject, context)),
+    ...(await dirMappings(overlayGlobal, context, ignorePatterns)),
+    ...(await dirMappings(overlayProject, context, ignorePatterns)),
   ];
 }
 
 async function dirMappings(
   dir: string,
   context: MapperContext,
+  ignorePatterns: string[] = [],
 ): Promise<FileMapping[]> {
   if (!(await fileExists(dir))) return [];
 
   const mappings: FileMapping[] = [];
-  for await (const overlayPath of walkOverlayFiles(dir)) {
+  for await (const overlayPath of walkOverlayFiles(dir, ignorePatterns)) {
     const result = overlayToTarget(overlayPath, context);
     if (result) {
       mappings.push({ overlayPath, ...result });

package/src/commands/files/Dedupe.ts

@@ -0,0 +1,134 @@
+import { dirname } from "node:path";
+import { agentFiles } from "../../AgentFiles.ts";
+import { getPromptRelPath } from "../../Mapper.ts";
+import { partition } from "../../Util.ts";
+import { type FileEntry, isInDirectory } from "./Scan.ts";
+
+/** Apply dedupe rules for agent files and prompt fanout paths. */
+export function dedupeEntries(
+  entries: FileEntry[],
+  agentsPreference: string[],
+): FileEntry[] {
+  const dedupedAgents = dedupeAgentFiles(entries, agentsPreference);
+  return dedupePromptFiles(dedupedAgents, agentsPreference);
+}
+
+/** Check if a relative path ends with an agent filename (CLAUDE.md, etc.) */
+export function isAgentFilePath(relPath: string): boolean {
+  const base = relPath.split("/").at(-1)?.toLowerCase();
+  if (!base) return false;
+  return agentFiles.some((f) => f.toLowerCase() === base);
+}
+
+/** Keep at most one agent file per directory, using the configured preference order. */
+function dedupeAgentFiles(
+  entries: FileEntry[],
+  agentsPreference: string[],
+): FileEntry[] {
+  const byDir = Map.groupBy(entries, (e) =>
+    isAgentFilePath(e.targetRelativePath) ? dirname(e.targetRelativePath) : "",
+  );
+  const preferred = agentPreferenceToFilename(agentsPreference);
+
+  return [...byDir].flatMap(([dirKey, group]) => {
+    if (dirKey === "") return group;
+    const [candidates, others] = partition(group, (e) =>
+      isAgentFilePath(e.targetRelativePath),
+    );
+    const chosen = chooseByBasename(candidates, preferred);
+    return chosen ? [...others, chosen] : others;
+  });
+}
+
+/** Keep only one prompt path per prompt-relative filename, using agent preference order. */
+function dedupePromptFiles(
+  entries: FileEntry[],
+  agentsPreference: string[],
+): FileEntry[] {
+  const preferred = agentPreferenceToDotAgentDir(agentsPreference);
+  const promptGroups = Map.groupBy(
+    entries,
+    (e) => getPromptRelPath(e.absolutePath) ?? "",
+  );
+
+  return [...promptGroups].flatMap(([key, group]) => {
+    if (key === "") return group;
+    const chosen = choosePreferredPrompt(group, preferred);
+    return chosen ? [chosen] : [];
+  });
+}
+
+/** Convert config preference strings into a basename priority list. */
+function agentPreferenceToFilename(preference: string[]): string[] {
+  return mapPreference(
+    preference,
+    { agents: "AGENTS.md", claude: "CLAUDE.md", gemini: "GEMINI.md" },
+    ["AGENTS.md", "CLAUDE.md", "GEMINI.md"],
+  );
+}
+
+/** Select a single representative entry, preferring basenames in priority order. */
+function chooseByBasename(
+  entries: FileEntry[],
+  preferredBasenames: string[],
+): FileEntry | null {
+  const byBase = new Map(
+    entries.map((e) => [basenameUpper(e.targetRelativePath), e]),
+  );
+  for (const base of preferredBasenames) {
+    const found = byBase.get(base.toUpperCase());
+    if (found) return found;
+  }
+  // Fallback: pick first alphabetically (entries should never be empty here)
+  const sorted = entries.toSorted((a, b) =>
+    a.cwdRelativePath.localeCompare(b.cwdRelativePath),
+  );
+  return sorted[0] ?? null;
+}
+
+/** Convert config preference strings into a dot-agent directory priority list. */
+function agentPreferenceToDotAgentDir(preference: string[]): string[] {
+  return mapPreference(preference, { claude: ".claude", gemini: ".gemini" }, [
+    ".claude",
+    ".gemini",
+  ]);
+}
+
+/** Pick the prompt entry to keep based on which agent directory it lives under. */
+function choosePreferredPrompt(
+  entries: FileEntry[],
+  preferredDirs: string[],
+): FileEntry | null {
+  const byDir = new Map<string, FileEntry>();
+  for (const e of entries) {
+    const rel = e.targetRelativePath;
+    if (isInDirectory(rel, ".claude/prompts")) {
+      byDir.set(".claude", e);
+    } else if (isInDirectory(rel, ".gemini/prompts")) {
+      byDir.set(".gemini", e);
+    }
+  }
+  for (const dir of preferredDirs) {
+    const found = byDir.get(dir);
+    if (found) return found;
+  }
+  const sorted = entries.toSorted((a, b) =>
+    a.cwdRelativePath.localeCompare(b.cwdRelativePath),
+  );
+  return sorted[0];
+}
+
+/** Map preference strings through a mapping, with defaults if empty. */
+function mapPreference(
+  preference: string[],
+  mapping: Record<string, string>,
+  defaults: string[],
+): string[] {
+  const order = preference.map((p) => mapping[p.toLowerCase()]).filter(Boolean);
+  return order.length > 0 ? order : defaults;
+}
+
+function basenameUpper(relPath: string): string {
+  const base = relPath.split("/").at(-1) ?? "";
+  return base.toUpperCase();
+}

package/src/commands/files/Scan.ts

@@ -0,0 +1,278 @@
+import { join, relative } from "node:path";
+import { expandPath, loadConfig } from "../../Config.ts";
+import { resolveSymlinkTarget, walkDirectory } from "../../FsUtil.ts";
+import { getGitContext } from "../../Git.ts";
+import { isClankPath } from "../../Mapper.ts";
+import { isAgentFilePath } from "./Dedupe.ts";
+
+export interface FilesOptions {
+  /** Include files under dot-prefixed directories (e.g. .claude/) */
+  hidden?: boolean;
+
+  /** Max depth under clank/ directories (segments after clank/) */
+  depth?: string;
+
+  /** Output NUL-separated paths */
+  null?: boolean;
+
+  /** Disable deduplication */
+  dedupe?: boolean;
+
+  /** Only include symlinks into the overlay */
+  linkedOnly?: boolean;
+
+  /** Only include non-overlay files/symlinks */
+  unlinkedOnly?: boolean;
+
+  /** Only include linked files from global scope (implies `linkedOnly`) */
+  global?: boolean;
+
+  /** Only include linked files from project scope (implies `linkedOnly`) */
+  project?: boolean;
+
+  /** Only include linked files from worktree scope (implies `linkedOnly`) */
+  worktree?: boolean;
+}
+
+export type LinkState = LinkedToOverlay | NotLinkedToOverlay;
+
+export interface FileEntry {
+  absolutePath: string;
+  cwdRelativePath: string;
+  targetRelativePath: string;
+  link: LinkState;
+}
+
+export interface FilesContext {
+  cwd: string;
+  gitContext: Awaited<ReturnType<typeof getGitContext>>;
+  targetRoot: string;
+  scanRoot: string;
+  overlayRoot: string;
+  agentsPreference: string[];
+}
+
+export interface NormalizedFilesOptions {
+  hidden: boolean;
+  depth: number | null;
+  null: boolean;
+  dedupe: boolean;
+  linkedOnly: boolean;
+  unlinkedOnly: boolean;
+  scopeFilter: "global" | "project" | "worktree" | null;
+}
+
+interface LinkedToOverlay {
+  kind: "linked";
+  overlayPath: string;
+  scope: "global" | "project" | "worktree";
+}
+
+interface NotLinkedToOverlay {
+  kind: "unlinked";
+}
+
+/** Gather derived paths and configuration needed to scan the repository. */
+export async function getFilesContext(
+  inputPath?: string,
+): Promise<FilesContext> {
+  const cwd = process.cwd();
+  const gitContext = await getGitContext(cwd);
+  const targetRoot = gitContext.gitRoot;
+  const scanRoot = resolveScanRoot(targetRoot, cwd, inputPath);
+  const config = await loadConfig();
+
+  return {
+    cwd,
+    gitContext,
+    targetRoot,
+    scanRoot,
+    overlayRoot: expandPath(config.overlayRepo),
+    agentsPreference: config.agents,
+  };
+}
+
+/** Apply defaults and turn user-facing flags into a stable internal shape. */
+export function normalizeFilesOptions(
+  options?: FilesOptions,
+): NormalizedFilesOptions {
+  const hidden = options?.hidden ?? false;
+  const depthRaw = options?.depth?.trim() ?? "";
+  const depth = depthRaw === "" ? null : parseDepth(depthRaw);
+
+  const scopeFilter = scopeFilterFromOptions({
+    global: options?.global ?? false,
+    project: options?.project ?? false,
+    worktree: options?.worktree ?? false,
+  });
+
+  return {
+    hidden,
+    depth,
+    null: options?.null ?? false,
+    dedupe: options?.dedupe ?? true,
+    linkedOnly: options?.linkedOnly ?? false,
+    unlinkedOnly: options?.unlinkedOnly ?? false,
+    scopeFilter,
+  };
+}
+
+/** Walk the scan root and collect candidates that match filters. */
+export async function collectEntries(
+  ctx: FilesContext,
+  opts: NormalizedFilesOptions,
+): Promise<FileEntry[]> {
+  const entries: FileEntry[] = [];
+  for await (const { path, isDirectory } of walkDirectory(ctx.scanRoot, {
+    includeHiddenDirs: opts.hidden,
+  })) {
+    if (isDirectory) continue;
+    const entry = await maybeCreateEntry(ctx, opts, path);
+    if (entry) entries.push(entry);
+  }
+  return entries;
+}
+
+/** Check if a relative path is under a specific directory component. */
+export function isInDirectory(relPath: string, dirName: string): boolean {
+  return relPath.startsWith(`${dirName}/`) || relPath.includes(`/${dirName}/`);
+}
+
+/** Resolve the scan root and reject paths that escape the git repository. */
+function resolveScanRoot(
+  targetRoot: string,
+  cwd: string,
+  input?: string,
+): string {
+  if (!input) return targetRoot;
+  const resolved = join(cwd, input);
+  const rel = normalizeRelPath(relative(targetRoot, resolved));
+  if (rel.startsWith("..")) {
+    throw new Error(`Path is outside the git repository: ${input}`);
+  }
+  return resolved;
+}
+
+/** Parse a user-supplied numeric flag and reject negative/invalid values. */
+function parseDepth(raw: string): number {
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || Number.isNaN(n) || n < 0) {
+    throw new Error(`Invalid --depth value: ${raw}`);
+  }
+  return n;
+}
+
+/** Resolve scope filter from CLI options (null = no filter, show all scopes) */
+function scopeFilterFromOptions(
+  options: Required<Pick<FilesOptions, "global" | "project" | "worktree">>,
+): "global" | "project" | "worktree" | null {
+  if (options.global) return "global";
+  if (options.project) return "project";
+  if (options.worktree) return "worktree";
+  return null;
+}
+
+/** Build a single output entry, or skip the file based on filters. */
+async function maybeCreateEntry(
+  ctx: FilesContext,
+  opts: NormalizedFilesOptions,
+  filePath: string,
+): Promise<FileEntry | null> {
+  const targetRel = normalizeRelPath(relative(ctx.targetRoot, filePath));
+  if (!isManagedTargetPath(targetRel, opts.hidden)) return null;
+  if (!passesDepthFilter(targetRel, opts.depth)) return null;
+
+  const link = await classifyLink(filePath, ctx.overlayRoot, ctx.gitContext);
+  if (!passesLinkFilter(link, opts)) return null;
+
+  return {
+    absolutePath: filePath,
+    cwdRelativePath: normalizeRelPath(relative(ctx.cwd, filePath) || "."),
+    targetRelativePath: targetRel,
+    link,
+  };
+}
+
+function normalizeRelPath(p: string): string {
+  return p.replaceAll("\\", "/");
+}
+
+/** Decide whether a target-relative path is managed by clank for listing. */
+function isManagedTargetPath(relPath: string, includeHidden: boolean): boolean {
+  if (isAgentFilePath(relPath)) return true;
+  if (isClankPath(relPath)) return true;
+  if (includeHidden && isInDotAgentDir(relPath)) return true;
+  return false;
+}
+
+/** Apply the clank-depth constraint only to paths under `clank/`. */
+function passesDepthFilter(relPath: string, depth: number | null): boolean {
+  if (depth === null) return true;
+  if (!isClankPath(relPath)) return true;
+  return passesClankDepth(relPath, depth);
+}
+
+/** Classify a path as linked to the overlay (and which scope) vs not. */
+async function classifyLink(
+  filePath: string,
+  overlayRoot: string,
+  gitContext: Awaited<ReturnType<typeof getGitContext>>,
+): Promise<LinkState> {
+  try {
+    const overlayPath = await resolveSymlinkTarget(filePath);
+    if (!overlayPath.startsWith(overlayRoot)) return { kind: "unlinked" };
+    const scope = inferScopeFromOverlay(overlayPath, overlayRoot, gitContext);
+    if (!scope) return { kind: "unlinked" };
+    return { kind: "linked", overlayPath, scope };
+  } catch {
+    return { kind: "unlinked" };
+  }
+}
+
+/** Apply linked/unlinked and scope filters consistently. */
+function passesLinkFilter(
+  link: LinkState,
+  opts: NormalizedFilesOptions,
+): boolean {
+  const effectiveLinkedOnly = opts.linkedOnly || opts.scopeFilter !== null;
+  if (effectiveLinkedOnly && link.kind !== "linked") return false;
+  if (opts.unlinkedOnly && link.kind !== "unlinked") return false;
+  if (opts.scopeFilter === null) return true;
+  return link.kind === "linked" && link.scope === opts.scopeFilter;
+}
+
+function isInDotAgentDir(relPath: string): boolean {
+  return isInDirectory(relPath, ".claude") || isInDirectory(relPath, ".gemini");
+}
+
+/** Enforce a max segment count beneath the nearest `clank/` path component. */
+function passesClankDepth(relPath: string, depth: number): boolean {
+  const marker = "/clank/";
+  const idx = relPath.includes(marker) ? relPath.lastIndexOf(marker) : -1;
+  const after =
+    idx === -1
+      ? relPath.slice("clank/".length)
+      : relPath.slice(idx + marker.length);
+  const segments = after.split("/").filter(Boolean);
+  return segments.length <= depth;
+}
+
+/** Infer the overlay scope from a resolved overlay path and current git context. */
+function inferScopeFromOverlay(
+  overlayPath: string,
+  overlayRoot: string,
+  gitContext: Awaited<ReturnType<typeof getGitContext>>,
+): "global" | "project" | "worktree" | null {
+  const globalPrefix = `${join(overlayRoot, "global")}/`;
+  if (overlayPath.startsWith(globalPrefix)) return "global";
+
+  const { projectName, worktreeName } = gitContext;
+  const projectPath = join(overlayRoot, "targets", projectName);
+  const worktreePath = join(projectPath, "worktrees", worktreeName);
+  if (overlayPath.startsWith(`${worktreePath}/`)) return "worktree";
+
+  const projectPrefix = `${projectPath}/`;
+  if (overlayPath.startsWith(projectPrefix)) return "project";
+
+  return null;
+}