clank-cli 0.1.59 → 0.1.62

package/src/Mapper.ts

@@ -12,6 +12,19 @@ export interface ScopeOptions {
   worktree?: boolean;
 }
 
+/** Result of mapping an overlay path to a target path */
+export interface TargetMapping {
+  targetPath: string;
+  scope: Scope;
+}
+
+/** params for mapping from the overlay repo to the target project repo */
+export interface MapperContext {
+  overlayRoot: string;
+  targetRoot: string;
+  gitContext: GitContext;
+}
+
 /** Resolve scope from CLI options
  * @param options - The CLI options
  * @param defaultScope - Default scope if none specified, or "require" to throw
@@ -32,19 +45,6 @@ export function resolveScopeFromOptions(
   return defaultScope;
 }
 
-/** Result of mapping an overlay path to a target path */
-export interface TargetMapping {
-  targetPath: string;
-  scope: Scope;
-}
-
-/** params for mapping from the overlay repo to the target project repo */
-export interface MapperContext {
-  overlayRoot: string;
-  targetRoot: string;
-  gitContext: GitContext;
-}
-
 /** Get overlay path for a project: overlay/targets/{projectName} */
 export function overlayProjectDir(
   overlayRoot: string,
@@ -132,34 +132,6 @@ export function targetToOverlay(
   return encodeTargetPath(relPath, overlayBase);
 }
 
-/** Encode a target-relative path to an overlay path */
-function encodeTargetPath(relPath: string, overlayBase: string): string {
-  // agents.md stays at natural path
-  if (basename(relPath) === "agents.md") {
-    return join(overlayBase, relPath);
-  }
-  // .claude/prompts/ and .gemini/prompts/ → prompts/ in overlay (agent-agnostic)
-  for (const agentDir of managedAgentDirs) {
-    const prefix = `${agentDir}/prompts/`;
-    if (relPath.startsWith(prefix)) {
-      return join(overlayBase, "prompts", relPath.slice(prefix.length));
-    }
-  }
-  // .claude/* and .gemini/* → claude/*, gemini/* in overlay (agent-specific)
-  for (const agentDir of managedAgentDirs) {
-    if (relPath.startsWith(`${agentDir}/`)) {
-      const subPath = relPath.slice(agentDir.length + 1);
-      return join(overlayBase, agentDir.slice(1), subPath); // strip leading dot
-    }
-  }
-  // Files with clank/ in path → preserve structure
-  if (relPath.includes("clank/")) {
-    return join(overlayBase, relPath);
-  }
-  // Plain files → add clank/ prefix
-  return join(overlayBase, "clank", relPath);
-}
-
 /**
  * Normalize file path argument from clank add command
  * All files go to clank/ in target (except .claude/ files and agent files)
@@ -217,6 +189,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();
@@ -271,6 +248,64 @@ function mapGlobalOverlay(
   return decodeOverlayPath(relPath, targetRoot, "global");
 }
 
+/** Map project overlay files to target */
+function mapProjectOverlay(
+  overlayPath: string,
+  projectPrefix: string,
+  context: MapperContext,
+): TargetMapping | null {
+  const { targetRoot, gitContext } = context;
+  const relPath = relative(projectPrefix, overlayPath);
+
+  // Worktree-specific files
+  const worktreePrefix = join("worktrees", gitContext.worktreeName);
+  if (relPath.startsWith(`${worktreePrefix}/`)) {
+    const innerPath = relative(worktreePrefix, relPath);
+    return decodeOverlayPath(innerPath, targetRoot, "worktree");
+  }
+
+  // Skip other worktrees
+  if (relPath.startsWith("worktrees/")) return null;
+
+  // Project settings.json (project-only, before shared logic)
+  if (relPath === "claude/settings.json") {
+    return {
+      targetPath: join(targetRoot, ".claude/settings.json"),
+      scope: "project",
+    };
+  }
+
+  return decodeOverlayPath(relPath, targetRoot, "project");
+}
+
+/** Encode a target-relative path to an overlay path */
+function encodeTargetPath(relPath: string, overlayBase: string): string {
+  // agents.md stays at natural path
+  if (basename(relPath) === "agents.md") {
+    return join(overlayBase, relPath);
+  }
+  // .claude/prompts/ and .gemini/prompts/ → prompts/ in overlay (agent-agnostic)
+  for (const agentDir of managedAgentDirs) {
+    const prefix = `${agentDir}/prompts/`;
+    if (relPath.startsWith(prefix)) {
+      return join(overlayBase, "prompts", relPath.slice(prefix.length));
+    }
+  }
+  // .claude/* and .gemini/* → claude/*, gemini/* in overlay (agent-specific)
+  for (const agentDir of managedAgentDirs) {
+    if (relPath.startsWith(`${agentDir}/`)) {
+      const subPath = relPath.slice(agentDir.length + 1);
+      return join(overlayBase, agentDir.slice(1), subPath); // strip leading dot
+    }
+  }
+  // Files with clank/ in path → preserve structure
+  if (isClankPath(relPath)) {
+    return join(overlayBase, relPath);
+  }
+  // Plain files → add clank/ prefix
+  return join(overlayBase, "clank", relPath);
+}
+
 /** Decode an overlay-relative path to target (shared by all scopes) */
 function decodeOverlayPath(
   relPath: string,
@@ -278,7 +313,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 };
   }
 
@@ -307,33 +342,3 @@ function decodeOverlayPath(
 
   return null;
 }
-
-/** Map project overlay files to target */
-function mapProjectOverlay(
-  overlayPath: string,
-  projectPrefix: string,
-  context: MapperContext,
-): TargetMapping | null {
-  const { targetRoot, gitContext } = context;
-  const relPath = relative(projectPrefix, overlayPath);
-
-  // Worktree-specific files
-  const worktreePrefix = join("worktrees", gitContext.worktreeName);
-  if (relPath.startsWith(`${worktreePrefix}/`)) {
-    const innerPath = relative(worktreePrefix, relPath);
-    return decodeOverlayPath(innerPath, targetRoot, "worktree");
-  }
-
-  // Skip other worktrees
-  if (relPath.startsWith("worktrees/")) return null;
-
-  // Project settings.json (project-only, before shared logic)
-  if (relPath === "claude/settings.json") {
-    return {
-      targetPath: join(targetRoot, ".claude/settings.json"),
-      scope: "project",
-    };
-  }
-
-  return decodeOverlayPath(relPath, targetRoot, "project");
-}

package/src/OverlayGit.ts

@@ -1,16 +1,18 @@
 import { execa } from "execa";
+import picomatch from "picomatch";
 import { managedDirs } from "./AgentFiles.ts";
 
 /** Get git status of the overlay repository */
 export async function getOverlayStatus(
   overlayRoot: string,
-): Promise<{ lines: string[]; raw: string }> {
+  ignorePatterns: string[] = [],
+): Promise<string[]> {
   const { stdout } = await execa({
     cwd: overlayRoot,
   })`git status --porcelain -uall`;
 
-  const lines = stdout.trimEnd() ? stdout.trimEnd().split("\n") : [];
-  return { lines, raw: stdout };
+  const allLines = stdout.trimEnd() ? stdout.trimEnd().split("\n") : [];
+  return filterIgnoredLines(allLines, ignorePatterns);
 }
 
 /** Format git status --porcelain output into readable lines */
@@ -35,6 +37,31 @@ export function formatStatusCode(code: string): string {
   return "?";
 }
 
+/** Filter out lines matching ignore patterns */
+function filterIgnoredLines(
+  lines: string[],
+  ignorePatterns: string[],
+): string[] {
+  if (ignorePatterns.length === 0) return lines;
+
+  const isIgnored = picomatch(ignorePatterns);
+  return lines.filter((line) => {
+    const filePath = line.slice(3); // Skip status code + space
+    const segments = filePath.split("/");
+    const pathBasename = segments.at(-1) ?? "";
+
+    // Check full path and basename
+    if (isIgnored(filePath) || isIgnored(pathBasename)) return false;
+
+    // Check each directory segment (for patterns like ".obsidian")
+    for (const segment of segments) {
+      if (isIgnored(segment)) return false;
+    }
+
+    return true;
+  });
+}
+
 /** Parse overlay path into scope and path parts within that scope */
 function parseScopedPath(filePath: string): {
   scope: string;

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

@@ -32,14 +32,36 @@ import {
 import { createPromptLinks, isSymlinkToOverlay } from "../OverlayLinks.ts";
 import { scopeFromSymlink } from "../ScopeFromSymlink.ts";
 
+export type AddOptions = ScopeOptions;
+
+interface AddContext {
+  cwd: string;
+  gitContext: GitContext;
+  config: { overlayRepo: string; agents: string[] };
+  overlayRoot: string;
+}
+
+/** Create agent symlinks (CLAUDE.md, GEMINI.md, AGENTS.md → agents.md) */
+interface AgentLinkParams {
+  overlayPath: string;
+  symlinkDir: string;
+  gitRoot: string;
+  overlayRoot: string;
+  agents: string[];
+}
+
+interface AgentLinkClassification {
+  toCreate: { targetPath: string; name: string }[];
+  existing: string[];
+  skipped: string[];
+}
+
 const scopeLabels: Record<Scope, string> = {
   global: "global",
   project: "project",
   worktree: "worktree",
 };
 
-export type AddOptions = ScopeOptions;
-
 /** Add file(s) to overlay and create symlinks in target */
 export async function addCommand(
   filePaths: string[],
@@ -68,11 +90,29 @@ export async function addCommand(
   }
 }
 
-interface AddContext {
-  cwd: string;
-  gitContext: GitContext;
-  config: { overlayRepo: string; agents: string[] };
-  overlayRoot: string;
+/** fail if we can't do an add with the given options */
+async function validateAddOptions(
+  options: AddOptions,
+  overlayRoot: string,
+  gitContext: GitContext,
+): Promise<void> {
+  await validateOverlayExists(overlayRoot);
+
+  if (options.worktree && !gitContext.isWorktree) {
+    throw new Error(
+      `--worktree scope requires a git worktree.\n` +
+        `You're on branch '${gitContext.worktreeName}' in the main repository.\n` +
+        `Use 'git worktree add' to create a worktree, or use --project scope instead.`,
+    );
+  }
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await lstat(path)).isDirectory();
+  } catch {
+    return false;
+  }
 }
 
 /** Add a single file to overlay and create symlink */
@@ -125,49 +165,20 @@ async function addSingleFile(
   }
 }
 
-/** Handle prompt file symlink creation */
-async function handlePromptFile(
-  normalizedPath: string,
-  overlayPath: string,
-  gitRoot: string,
+/** Check if file is already in overlay at a different scope, throw helpful error */
+async function checkScopeConflict(
+  barePath: string,
+  requestedScope: Scope,
+  context: MapperContext,
   cwd: string,
 ): Promise<void> {
-  const promptRelPath = getPromptRelPath(normalizedPath);
-  if (promptRelPath) {
-    const created = await createPromptLinks(
-      overlayPath,
-      promptRelPath,
-      gitRoot,
+  const currentScope = await scopeFromSymlink(barePath, context);
+  if (currentScope && currentScope !== requestedScope) {
+    const fileName = relative(cwd, barePath);
+    throw new Error(
+      `${fileName} is already in ${scopeLabels[currentScope]} overlay.\n` +
+        `To move it to ${scopeLabels[requestedScope]} scope, use: clank mv ${fileName} --${requestedScope}`,
     );
-    if (created.length) {
-      console.log(
-        `Created symlinks: ${created.map((p) => relative(cwd, p)).join(", ")}`,
-      );
-    }
-  }
-}
-
-/** Handle regular file symlink creation */
-async function handleRegularFile(
-  normalizedPath: string,
-  overlayPath: string,
-  overlayRoot: string,
-  cwd: string,
-): Promise<void> {
-  if (await isSymlinkToOverlay(normalizedPath, overlayRoot)) {
-    console.log(`Symlink already exists: ${relative(cwd, normalizedPath)}`);
-  } else {
-    const linkTarget = getLinkTarget(normalizedPath, overlayPath);
-    await createSymlink(linkTarget, normalizedPath);
-    console.log(`Created symlink: ${relative(cwd, normalizedPath)}`);
-  }
-}
-
-async function isDirectory(path: string): Promise<boolean> {
-  try {
-    return (await lstat(path)).isDirectory();
-  } catch {
-    return false;
   }
 }
 
@@ -201,51 +212,6 @@ async function addFileToOverlay(
   }
 }
 
-/** Find content from normalized path or bare input path */
-async function findSourceContent(
-  normalizedPath: string,
-  barePath: string,
-): Promise<string> {
-  // Try normalized path first (e.g., cwd/clank/foo.md)
-  if (
-    (await fileExists(normalizedPath)) &&
-    !(await isSymlink(normalizedPath))
-  ) {
-    return await readFile(normalizedPath, "utf-8");
-  }
-  // Fall back to bare input path (e.g., cwd/foo.md)
-  if ((await fileExists(barePath)) && !(await isSymlink(barePath))) {
-    return await readFile(barePath, "utf-8");
-  }
-  return "";
-}
-
-/** fail if we can't do an add with the given options */
-async function validateAddOptions(
-  options: AddOptions,
-  overlayRoot: string,
-  gitContext: GitContext,
-): Promise<void> {
-  await validateOverlayExists(overlayRoot);
-
-  if (options.worktree && !gitContext.isWorktree) {
-    throw new Error(
-      `--worktree scope requires a git worktree.\n` +
-        `You're on branch '${gitContext.worktreeName}' in the main repository.\n` +
-        `Use 'git worktree add' to create a worktree, or use --project scope instead.`,
-    );
-  }
-}
-
-/** Create agent symlinks (CLAUDE.md, GEMINI.md, AGENTS.md → agents.md) */
-interface AgentLinkParams {
-  overlayPath: string;
-  symlinkDir: string;
-  gitRoot: string;
-  overlayRoot: string;
-  agents: string[];
-}
-
 async function createAgentLinks(p: AgentLinkParams): Promise<void> {
   const { overlayPath, ...classifyParams } = p;
   const { toCreate, existing, skipped } =
@@ -271,27 +237,61 @@ async function createAgentLinks(p: AgentLinkParams): Promise<void> {
   }
 }
 
-/** Check if file is already in overlay at a different scope, throw helpful error */
-async function checkScopeConflict(
-  barePath: string,
-  requestedScope: Scope,
-  context: MapperContext,
+/** Handle prompt file symlink creation */
+async function handlePromptFile(
+  normalizedPath: string,
+  overlayPath: string,
+  gitRoot: string,
   cwd: string,
 ): Promise<void> {
-  const currentScope = await scopeFromSymlink(barePath, context);
-  if (currentScope && currentScope !== requestedScope) {
-    const fileName = relative(cwd, barePath);
-    throw new Error(
-      `${fileName} is already in ${scopeLabels[currentScope]} overlay.\n` +
-        `To move it to ${scopeLabels[requestedScope]} scope, use: clank mv ${fileName} --${requestedScope}`,
+  const promptRelPath = getPromptRelPath(normalizedPath);
+  if (promptRelPath) {
+    const created = await createPromptLinks(
+      overlayPath,
+      promptRelPath,
+      gitRoot,
     );
+    if (created.length) {
+      console.log(
+        `Created symlinks: ${created.map((p) => relative(cwd, p)).join(", ")}`,
+      );
+    }
   }
 }
 
-interface AgentLinkClassification {
-  toCreate: { targetPath: string; name: string }[];
-  existing: string[];
-  skipped: string[];
+/** Handle regular file symlink creation */
+async function handleRegularFile(
+  normalizedPath: string,
+  overlayPath: string,
+  overlayRoot: string,
+  cwd: string,
+): Promise<void> {
+  if (await isSymlinkToOverlay(normalizedPath, overlayRoot)) {
+    console.log(`Symlink already exists: ${relative(cwd, normalizedPath)}`);
+  } else {
+    const linkTarget = getLinkTarget(normalizedPath, overlayPath);
+    await createSymlink(linkTarget, normalizedPath);
+    console.log(`Created symlink: ${relative(cwd, normalizedPath)}`);
+  }
+}
+
+/** Find content from normalized path or bare input path */
+async function findSourceContent(
+  normalizedPath: string,
+  barePath: string,
+): Promise<string> {
+  // Try normalized path first (e.g., cwd/clank/foo.md)
+  if (
+    (await fileExists(normalizedPath)) &&
+    !(await isSymlink(normalizedPath))
+  ) {
+    return await readFile(normalizedPath, "utf-8");
+  }
+  // Fall back to bare input path (e.g., cwd/foo.md)
+  if ((await fileExists(barePath)) && !(await isSymlink(barePath))) {
+    return await readFile(barePath, "utf-8");
+  }
+  return "";
 }
 
 /** Classify which agent symlinks to create vs skip */