clank-cli 0.1.59 → 0.1.62

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.
@@ -181,7 +205,7 @@ clank help structure
 
 ### `--config <path>` (global option)
 
-Specify a custom config file location (default `~/.config/clank/config.js`).
+Specify a custom config file location (default `~/.config/clank/clank.config.js`).
 
 ```bash
 clank --config /tmp/test-config.js init /tmp/test-overlay
@@ -219,23 +243,25 @@ clank/
 
 ## Configuration
 
-Global configuration is stored by default in `~/.config/clank/config.js`:
+Global configuration is stored in `~/.config/clank/clank.config.js`:
 
 ```javascript
 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.62",
   "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/ClassifyFiles.ts

@@ -25,8 +25,6 @@ export interface AgentFileClassification {
   outdatedSymlinks: OutdatedSymlink[];
 }
 
-type PartialClassification = Partial<AgentFileClassification>;
-
 export interface OutdatedSymlink {
   /** Path to the symlink in the target */
   symlinkPath: string;
@@ -38,6 +36,8 @@ export interface OutdatedSymlink {
   expectedTarget: string;
 }
 
+type PartialClassification = Partial<AgentFileClassification>;
+
 /** Find all agent files in the repository and classify them.
  * Returns absolute paths in the classification.
  */
@@ -127,6 +127,21 @@ To fix:
   return sections.join("\n\n");
 }
 
+/** Find all agent files in the repository */
+async function findAllAgentFiles(targetRoot: string): Promise<string[]> {
+  const files: string[] = [];
+  const agentFileSet = new Set(agentFiles);
+
+  for await (const { path, isDirectory } of walkDirectory(targetRoot)) {
+    if (isDirectory) continue;
+    if (agentFileSet.has(basename(path))) {
+      files.push(path);
+    }
+  }
+
+  return files;
+}
+
 /** Classify a single agent file */
 async function classifySingleAgentFile(
   filePath: string,
@@ -146,6 +161,18 @@ async function classifySingleAgentFile(
   return {};
 }
 
+/** Merge sparse classifications into a complete classification with arrays */
+function mergeClassifications(
+  items: PartialClassification[],
+): AgentFileClassification {
+  return {
+    tracked: items.flatMap((i) => i.tracked ?? []),
+    untracked: items.flatMap((i) => i.untracked ?? []),
+    staleSymlinks: items.flatMap((i) => i.staleSymlinks ?? []),
+    outdatedSymlinks: items.flatMap((i) => i.outdatedSymlinks ?? []),
+  };
+}
+
 /** Classify an agent symlink - check if stale or outdated */
 async function classifyAgentSymlink(
   filePath: string,
@@ -179,30 +206,3 @@ async function classifyAgentSymlink(
 
   return {};
 }
-
-/** Merge sparse classifications into a complete classification with arrays */
-function mergeClassifications(
-  items: PartialClassification[],
-): AgentFileClassification {
-  return {
-    tracked: items.flatMap((i) => i.tracked ?? []),
-    untracked: items.flatMap((i) => i.untracked ?? []),
-    staleSymlinks: items.flatMap((i) => i.staleSymlinks ?? []),
-    outdatedSymlinks: items.flatMap((i) => i.outdatedSymlinks ?? []),
-  };
-}
-
-/** Find all agent files in the repository */
-async function findAllAgentFiles(targetRoot: string): Promise<string[]> {
-  const files: string[] = [];
-  const agentFileSet = new Set(agentFiles);
-
-  for await (const { path, isDirectory } of walkDirectory(targetRoot)) {
-    if (isDirectory) continue;
-    if (agentFileSet.has(basename(path))) {
-      files.push(path);
-    }
-  }
-
-  return files;
-}

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";
@@ -92,6 +93,24 @@ function registerCoreCommands(program: Command): void {
   registerUtilityCommands(program);
 }
 
+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) return program.help();
+      const subcommand = program.commands.find((c) => c.name() === commandName);
+      if (subcommand) return subcommand.help();
+      console.error(`Unknown command: ${commandName}`);
+      process.exit(1);
+    });
+  help
+    .command("structure")
+    .description("Show overlay directory structure")
+    .action(() => console.log(structureHelp));
+}
+
 function registerOverlayCommands(program: Command): void {
   program
     .command("init")
@@ -145,6 +164,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,27 +173,17 @@ function registerUtilityCommands(program: Command): void {
     .action(withErrorHandling(vscodeCommand));
 }
 
-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();
-      }
-      const subcommand = program.commands.find((c) => c.name() === commandName);
-      if (subcommand) {
-        subcommand.help();
-      } else {
-        console.error(`Unknown command: ${commandName}`);
-        process.exit(1);
-      }
-    });
-  help
-    .command("structure")
-    .description("Show overlay directory structure")
-    .action(() => console.log(structureHelp));
+function withErrorHandling<T extends unknown[]>(
+  fn: (...args: T) => Promise<void>,
+): (...args: T) => Promise<void> {
+  return async (...args: T) => {
+    try {
+      await fn(...args);
+    } catch (error) {
+      console.error("Error:", error instanceof Error ? error.message : error);
+      process.exit(1);
+    }
+  };
 }
 
 function registerRmCommand(program: Command): void {
@@ -215,15 +226,50 @@ function registerMvCommand(program: Command): void {
   cmd.action(withErrorHandling(moveCommand));
 }
 
-function withErrorHandling<T extends unknown[]>(
-  fn: (...args: T) => Promise<void>,
-): (...args: T) => Promise<void> {
-  return async (...args: T) => {
-    try {
-      await fn(...args);
-    } catch (error) {
-      console.error("Error:", error instanceof Error ? error.message : error);
-      process.exit(1);
-    }
-  };
+function registerFilesCommand(program: Command): void {
+  const files = program
+    .command("files")
+    .alias("list")
+    .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));
 }

package/src/Config.ts

@@ -4,8 +4,6 @@ import { join } from "node:path";
 import { cosmiconfig } from "cosmiconfig";
 import { fileExists } from "./FsUtil.ts";
 
-export const defaultOverlayDir = "clankover";
-
 export interface ClankConfig {
   overlayRepo: string;
   agents: string[];
@@ -13,8 +11,12 @@ 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[];
 }
 
+export const defaultOverlayDir = "clankover";
+
 const defaultConfig: ClankConfig = {
   overlayRepo: join(homedir(), defaultOverlayDir),
   agents: ["agents", "claude", "gemini"],
@@ -28,14 +30,11 @@ export function setConfigPath(path: string | undefined): void {
   customConfigPath = path;
 }
 
-/** Load global clank configuration from ~/.config/clank/config.js or similar */
+/** Load global clank configuration from ~/.config/clank/clank.config.js or similar */
 export async function loadConfig(): Promise<ClankConfig> {
   if (customConfigPath) {
     const result = await explorer.load(customConfigPath);
-    if (!result) {
-      throw new Error(`Config file not found: ${customConfigPath}`);
-    }
-    if (result.isEmpty) {
+    if (!result || result.isEmpty) {
       return defaultConfig;
     }
     return { ...defaultConfig, ...result.config };
@@ -48,10 +47,10 @@ export async function loadConfig(): Promise<ClankConfig> {
   return { ...defaultConfig, ...result.config };
 }
 
-/** Create default configuration file at ~/.config/clank/config.js */
+/** Create default configuration file at ~/.config/clank/clank.config.js */
 export async function createDefaultConfig(overlayRepo?: string): Promise<void> {
   const configDir = getConfigDir();
-  const configPath = customConfigPath || join(configDir, "config.js");
+  const configPath = customConfigPath || join(configDir, "clank.config.js");
 
   const config = {
     ...defaultConfig,
@@ -82,12 +81,6 @@ export async function getOverlayPath(): Promise<string> {
   return expandPath(config.overlayRepo);
 }
 
-/** Get the XDG config directory (respects XDG_CONFIG_HOME, defaults to ~/.config/clank) */
-function getConfigDir(): string {
-  const xdgConfig = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
-  return join(xdgConfig, "clank");
-}
-
 /** Validate overlay repository exists, throw if not */
 export async function validateOverlayExists(
   overlayRoot: string,
@@ -98,3 +91,9 @@ export async function validateOverlayExists(
     );
   }
 }
+
+/** Get the XDG config directory (respects XDG_CONFIG_HOME, defaults to ~/.config/clank) */
+function getConfigDir(): string {
+  const xdgConfig = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(xdgConfig, "clank");
+}

package/src/Exclude.ts

@@ -102,15 +102,6 @@ export async function removeGitExcludes(targetRoot: string): Promise<void> {
   console.log("Removed clank entries from .git/info/exclude");
 }
 
-/** Remove the clank section from exclude file content */
-function removeClankSection(content: string): string {
-  const pattern = new RegExp(
-    `\\n*${clankMarkerStart}[\\s\\S]*?${clankMarkerEnd}\\n*`,
-    "g",
-  );
-  return content.replace(pattern, "\n");
-}
-
 /** Filter out clank section from lines */
 export function filterClankLines(lines: string[]): string[] {
   const result: string[] = [];
@@ -129,6 +120,15 @@ export function filterClankLines(lines: string[]): string[] {
   return result;
 }
 
+/** Remove the clank section from exclude file content */
+function removeClankSection(content: string): string {
+  const pattern = new RegExp(
+    `\\n*${clankMarkerStart}[\\s\\S]*?${clankMarkerEnd}\\n*`,
+    "g",
+  );
+  return content.replace(pattern, "\n");
+}
+
 /** Check if a directory has any tracked files */
 async function hasTrackedFiles(
   dirPath: string,

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/Git.ts

@@ -115,16 +115,6 @@ export function parseRepoName(url: string): string | null {
   return basename(normalizedUrl);
 }
 
-/** Execute a git command and return stdout, or null if it fails */
-async function gitCommand(args: string, cwd?: string): Promise<string | null> {
-  try {
-    const { stdout } = await exec(`git ${args}`, { cwd });
-    return stdout.trim();
-  } catch {
-    return null;
-  }
-}
-
 /** Get the .git directory for the current worktree */
 export async function getGitDir(cwd: string): Promise<string | null> {
   const gitDir = await gitCommand("rev-parse --git-dir", cwd);
@@ -138,3 +128,13 @@ export async function getGitCommonDir(cwd: string): Promise<string | null> {
   if (!gitDir) return null;
   return isAbsolute(gitDir) ? gitDir : join(cwd, gitDir);
 }
+
+/** Execute a git command and return stdout, or null if it fails */
+async function gitCommand(args: string, cwd?: string): Promise<string | null> {
+  try {
+    const { stdout } = await exec(`git ${args}`, { cwd });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}

package/src/Gitignore.ts

@@ -169,22 +169,19 @@ async function parseGitignoreFile(
   result.negationWarnings.push(...parsed.negationWarnings);
 }
 
-/** Parse a single gitignore line */
-function parseLine(
-  trimmed: string,
-  source: string,
-  basePath: string,
-): { pattern?: GitignorePattern; negation?: string } {
-  // Skip empty lines and comments
-  if (!trimmed || trimmed.startsWith("#")) return {};
-
-  const isNegation = trimmed.startsWith("!");
-  const pattern = isNegation ? trimmed.slice(1) : trimmed;
+/** Find all nested .gitignore files (excluding root) */
+async function findNestedGitignores(targetRoot: string): Promise<string[]> {
+  const gitignores: string[] = [];
+  const rootGitignore = join(targetRoot, ".gitignore");
 
-  if (isNegation) {
-    return { negation: pattern };
+  for await (const { path, isDirectory } of walkDirectory(targetRoot)) {
+    if (isDirectory) continue;
+    if (basename(path) === ".gitignore" && path !== rootGitignore) {
+      gitignores.push(path);
+    }
   }
-  return { pattern: { pattern, basePath, negation: false, source } };
+
+  return gitignores;
 }
 
 /** Parse gitignore file content into patterns */
@@ -211,17 +208,20 @@ function parseGitignoreContent(
   return { patterns, negationWarnings };
 }
 
-/** Find all nested .gitignore files (excluding root) */
-async function findNestedGitignores(targetRoot: string): Promise<string[]> {
-  const gitignores: string[] = [];
-  const rootGitignore = join(targetRoot, ".gitignore");
+/** Parse a single gitignore line */
+function parseLine(
+  trimmed: string,
+  source: string,
+  basePath: string,
+): { pattern?: GitignorePattern; negation?: string } {
+  // Skip empty lines and comments
+  if (!trimmed || trimmed.startsWith("#")) return {};
 
-  for await (const { path, isDirectory } of walkDirectory(targetRoot)) {
-    if (isDirectory) continue;
-    if (basename(path) === ".gitignore" && path !== rootGitignore) {
-      gitignores.push(path);
-    }
-  }
+  const isNegation = trimmed.startsWith("!");
+  const pattern = isNegation ? trimmed.slice(1) : trimmed;
 
-  return gitignores;
+  if (isNegation) {
+    return { negation: pattern };
+  }
+  return { pattern: { pattern, basePath, negation: false, source } };
 }