clank-cli 0.1.59 → 0.1.62

package/src/commands/Link.ts

@@ -51,6 +51,12 @@ interface LinkedFile {
   scope: Scope;
 }
 
+interface SeparatedMappings {
+  agentsMappings: FileMapping[];
+  promptsMappings: FileMapping[];
+  regularMappings: FileMapping[];
+}
+
 /** Link overlay repository to target directory */
 export async function linkCommand(targetDir?: string): Promise<void> {
   const gitContext = await getGitContext(targetDir || process.cwd());
@@ -68,19 +74,9 @@ export async function linkCommand(targetDir?: string): Promise<void> {
   await ensureDir(join(overlayRoot, "targets", gitContext.projectName));
   await maybeInitWorktree(overlayRoot, gitContext);
 
-  // Collect and separate mappings (agents.md and prompts get special handling)
-  const mappings = await overlayMappings(overlayRoot, gitContext, targetRoot);
-  const agentsMappings = mappings.filter(
-    (m) => basename(m.targetPath) === "agents.md",
-  );
-  const promptsMappings = mappings.filter((m) =>
-    m.targetPath.includes("/.claude/prompts/"),
-  );
-  const regularMappings = mappings.filter(
-    (m) =>
-      basename(m.targetPath) !== "agents.md" &&
-      !m.targetPath.includes("/.claude/prompts/"),
-  );
+  const ignorePatterns = config.ignore ?? [];
+  const { agentsMappings, promptsMappings, regularMappings } =
+    await collectMappings(overlayRoot, gitContext, targetRoot, ignorePatterns);
 
   // Create symlinks
   const linkedPaths = await createLinks(regularMappings, targetRoot);
@@ -91,26 +87,12 @@ export async function linkCommand(targetDir?: string): Promise<void> {
   await setupProjectSettings(overlayRoot, gitContext, targetRoot);
   await addGitExcludes(targetRoot);
   await maybeGenerateVscodeSettings(config, targetRoot);
-  await warnOrphans(overlayRoot, targetRoot, gitContext.projectName);
-}
-
-/** Generate VS Code settings if configured */
-async function maybeGenerateVscodeSettings(
-  config: ClankConfig,
-  targetRoot: string,
-): Promise<void> {
-  const setting = config.vscodeSettings ?? "auto";
-
-  if (setting === "never") return;
-
-  if (setting === "auto") {
-    const isVscode = await isVscodeProject(targetRoot);
-    if (!isVscode) return;
-  }
-
-  // setting === "always" or (setting === "auto" && isVscodeProject)
-  console.log("");
-  await generateVscodeSettings(targetRoot);
+  await warnOrphans(
+    overlayRoot,
+    targetRoot,
+    gitContext.projectName,
+    ignorePatterns,
+  );
 }
 
 function logGitContext(ctx: GitContext): void {
@@ -119,27 +101,6 @@ function logGitContext(ctx: GitContext): void {
   console.log(`Branch: ${ctx.worktreeName}${suffix}`);
 }
 
-function logLinkedPaths(files: LinkedFile[]): void {
-  if (files.length === 0) return;
-  console.log(`\nLinked ${files.length} file(s):`);
-  for (const { path, scope } of files) {
-    const suffix = scope === "project" ? "" : ` (${scope})`;
-    console.log(`  ${path}${suffix}`);
-  }
-}
-
-async function warnOrphans(
-  overlayRoot: string,
-  targetRoot: string,
-  projectName: string,
-): Promise<void> {
-  const orphans = await findOrphans(overlayRoot, targetRoot, projectName);
-  if (orphans.length > 0) {
-    console.log(`\nWarning: ${orphans.length} orphaned overlay path(s) found.`);
-    console.log("Run 'clank check' for details.");
-  }
-}
-
 /** Check for problematic agent files and error if found */
 async function checkAgentFiles(
   targetRoot: string,
@@ -165,67 +126,64 @@ async function maybeInitWorktree(
   }
 }
 
-/** Collect all file mappings from global, project, and worktree locations */
-async function overlayMappings(
+/** Collect and separate mappings by type (agents.md and prompts get special handling) */
+async function collectMappings(
   overlayRoot: string,
   gitContext: GitContext,
   targetRoot: 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)),
-  ];
-}
-
-async function dirMappings(
-  dir: string,
-  context: MapperContext,
-): Promise<FileMapping[]> {
-  if (!(await fileExists(dir))) return [];
+  ignorePatterns: string[],
+): Promise<SeparatedMappings> {
+  const mappings = await overlayMappings(
+    overlayRoot,
+    gitContext,
+    targetRoot,
+    ignorePatterns,
+  );
+  const isAgent = ({ targetPath }: FileMapping) =>
+    basename(targetPath) === "agents.md";
+  const isPrompt = ({ targetPath }: FileMapping) =>
+    targetPath.includes("/.claude/prompts/");
 
-  const mappings: FileMapping[] = [];
-  for await (const overlayPath of walkOverlayFiles(dir)) {
-    const result = overlayToTarget(overlayPath, context);
-    if (result) {
-      mappings.push({ overlayPath, ...result });
-    }
-  }
-  return mappings;
-}
+  const agentsMappings = mappings.filter(isAgent);
+  const promptsMappings = mappings.filter((m) => !isAgent(m) && isPrompt(m));
+  const regularMappings = mappings.filter((m) => !isAgent(m) && !isPrompt(m));
 
-/** Check if a file is tracked in git (exists as real file, not symlink, and tracked) */
-async function isTrackedFile(path: string, gitRoot: string): Promise<boolean> {
-  if (!(await fileExists(path))) return false;
-  if (await isSymlink(path)) return false;
-  return isTrackedByGit(path, gitRoot);
+  return { agentsMappings, promptsMappings, regularMappings };
 }
 
-/** Process a single agents.md mapping into agent symlink paths */
-async function processAgentMapping(
-  mapping: FileMapping,
+/** Create symlinks, handling conflicts with scope suffixes.
+ * Conflicts occur when the same filename exists at multiple scopes (global, project, worktree).
+ * Returns linked files with their scopes. */
+async function createLinks(
+  mappings: FileMapping[],
   targetRoot: string,
-  agents: string[],
-): Promise<{ created: string[]; skipped: string[] }> {
-  const { overlayPath, targetPath } = mapping;
-  const targetDir = dirname(targetPath);
-  const created: string[] = [];
-  const skipped: string[] = [];
+): Promise<LinkedFile[]> {
+  // Filter out subdirectory clank files where parent doesn't exist in target
+  const validMappings = await filterValidMappings(mappings, targetRoot);
 
-  await forEachAgentPath(targetDir, agents, async (agentPath) => {
-    if (await isTrackedFile(agentPath, targetRoot)) {
-      skipped.push(relative(targetRoot, agentPath));
-    } else {
-      const linkTarget = getLinkTarget(agentPath, overlayPath);
-      await createSymlink(linkTarget, agentPath);
-      created.push(relative(targetRoot, agentPath));
-    }
-  });
+  const byTarget = Map.groupBy(validMappings, (m) => m.targetPath);
+  const links = [...byTarget].flatMap(([targetPath, files]) =>
+    resolveLinks(targetPath, files),
+  );
 
-  return { created, skipped };
+  const linkPromises = links.map(({ overlayPath, linkPath }) =>
+    createSymlink(getLinkTarget(linkPath, overlayPath), linkPath),
+  );
+  await Promise.all(linkPromises);
+
+  return links.map(({ linkPath, scope }) => ({
+    path: relative(targetRoot, linkPath),
+    scope,
+  }));
+}
+
+function logLinkedPaths(files: LinkedFile[]): void {
+  if (files.length === 0) return;
+  console.log(`\nLinked ${files.length} file(s):`);
+  for (const { path, scope } of files) {
+    const suffix = scope === "project" ? "" : ` (${scope})`;
+    console.log(`  ${path}${suffix}`);
+  }
 }
 
 /** Create agent symlinks (CLAUDE.md, GEMINI.md, AGENTS.md → agents.md) for all agents.md files */
@@ -278,47 +236,106 @@ async function createPromptLinks(
   }
 }
 
-/** Process a single prompt mapping into symlinks for all agent directories */
-async function processPromptMapping(
-  mapping: FileMapping,
+/** Setup project settings.json - adopt existing or create new */
+async function setupProjectSettings(
+  overlayRoot: string,
+  gitContext: GitContext,
   targetRoot: string,
-): Promise<{ created: string[] }> {
-  const { overlayPath, targetPath } = mapping;
-  const promptRelPath = getPromptRelPath(targetPath);
-  if (!promptRelPath) return { created: [] };
-
-  const createdPaths = await createPromptLinksShared(
-    overlayPath,
-    promptRelPath,
-    targetRoot,
+): Promise<void> {
+  const overlayPath = join(
+    overlayRoot,
+    "targets",
+    gitContext.projectName,
+    "claude",
+    "settings.json",
   );
-  return { created: createdPaths.map((p) => relative(targetRoot, p)) };
+  const targetPath = join(targetRoot, ".claude/settings.json");
+
+  const inOverlay = await fileExists(overlayPath);
+  const inTarget =
+    (await fileExists(targetPath)) && !(await isSymlink(targetPath));
+
+  if (inTarget && inOverlay) {
+    throw new Error(
+      `Conflict: settings.json exists in both target and overlay.\n` +
+        `  Target: ${targetPath}\n` +
+        `  Overlay: ${overlayPath}\n` +
+        `Remove one to resolve.`,
+    );
+  }
+
+  if (inTarget) {
+    // Adopt target's settings - move to overlay
+    await ensureDir(dirname(overlayPath));
+    await rename(targetPath, overlayPath);
+    console.log(`Moved .claude/settings.json to overlay`);
+  } else if (!inOverlay) {
+    // Neither exists - create blank in overlay
+    await ensureDir(dirname(overlayPath));
+    await writeFile(overlayPath, "{}\n", "utf-8");
+    console.log(
+      `Created .claude/settings.json symlink (project settings will be stored in overlay)`,
+    );
+  }
+
+  // Create symlink (overlay now has the file)
+  await ensureDir(dirname(targetPath));
+  const linkTarget = getLinkTarget(targetPath, overlayPath);
+  await createSymlink(linkTarget, targetPath);
 }
 
-/** Create symlinks, handling conflicts with scope suffixes.
- * Conflicts occur when the same filename exists at multiple scopes (global, project, worktree).
- * Returns linked files with their scopes. */
-async function createLinks(
-  mappings: FileMapping[],
+/** Generate VS Code settings if configured */
+async function maybeGenerateVscodeSettings(
+  config: ClankConfig,
   targetRoot: string,
-): Promise<LinkedFile[]> {
-  // Filter out subdirectory clank files where parent doesn't exist in target
-  const validMappings = await filterValidMappings(mappings, targetRoot);
+): Promise<void> {
+  const setting = config.vscodeSettings ?? "auto";
 
-  const byTarget = Map.groupBy(validMappings, (m) => m.targetPath);
-  const links = [...byTarget].flatMap(([targetPath, files]) =>
-    resolveLinks(targetPath, files),
-  );
+  if (setting === "never") return;
 
-  const linkPromises = links.map(({ overlayPath, linkPath }) =>
-    createSymlink(getLinkTarget(linkPath, overlayPath), linkPath),
+  if (setting === "auto") {
+    const isVscode = await isVscodeProject(targetRoot);
+    if (!isVscode) return;
+  }
+
+  // setting === "always" or (setting === "auto" && isVscodeProject)
+  console.log("");
+  await generateVscodeSettings(targetRoot);
+}
+
+async function warnOrphans(
+  overlayRoot: string,
+  targetRoot: string,
+  projectName: string,
+  ignorePatterns: string[] = [],
+): Promise<void> {
+  const orphans = await findOrphans(
+    overlayRoot,
+    targetRoot,
+    projectName,
+    ignorePatterns,
   );
-  await Promise.all(linkPromises);
+  if (orphans.length > 0) {
+    console.log(`\nWarning: ${orphans.length} orphaned overlay path(s) found.`);
+    console.log("Run 'clank check' for details.");
+  }
+}
 
-  return links.map(({ linkPath, scope }) => ({
-    path: relative(targetRoot, linkPath),
-    scope,
-  }));
+/** Collect all file mappings from global, project, and worktree locations */
+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, ignorePatterns)),
+    ...(await dirMappings(overlayProject, context, ignorePatterns)),
+  ];
 }
 
 /** Filter mappings to exclude subdirectory clank files where target parent doesn't exist.
@@ -334,24 +351,6 @@ async function filterValidMappings(
   return results.filter((m): m is FileMapping => m !== null);
 }
 
-/** Check if a subdirectory clank file's parent exists in the target */
-async function checkMappingParentExists(
-  m: FileMapping,
-  targetRoot: string,
-): Promise<FileMapping | null> {
-  const relPath = relative(targetRoot, m.targetPath);
-  // Subdirectory clank files have /clank/ in the middle of the path
-  const clankIndex = relPath.indexOf("/clank/");
-  if (clankIndex !== -1) {
-    // Check if parent directory exists (e.g., packages/foo for packages/foo/clank/notes.md)
-    const parentDir = join(targetRoot, relPath.slice(0, clankIndex));
-    if (!(await fileExists(parentDir))) {
-      return null;
-    }
-  }
-  return m;
-}
-
 /** Compute link paths, adding scope suffixes when the same target has multiple sources */
 function resolveLinks(
   targetPath: string,
@@ -371,50 +370,85 @@ function resolveLinks(
   }));
 }
 
-/** Setup project settings.json - adopt existing or create new */
-async function setupProjectSettings(
-  overlayRoot: string,
-  gitContext: GitContext,
+/** Process a single agents.md mapping into agent symlink paths */
+async function processAgentMapping(
+  mapping: FileMapping,
   targetRoot: string,
-): Promise<void> {
-  const overlayPath = join(
-    overlayRoot,
-    "targets",
-    gitContext.projectName,
-    "claude",
-    "settings.json",
+  agents: string[],
+): Promise<{ created: string[]; skipped: string[] }> {
+  const { overlayPath, targetPath } = mapping;
+  const targetDir = dirname(targetPath);
+  const created: string[] = [];
+  const skipped: string[] = [];
+
+  await forEachAgentPath(targetDir, agents, async (agentPath) => {
+    if (await isTrackedFile(agentPath, targetRoot)) {
+      skipped.push(relative(targetRoot, agentPath));
+    } else {
+      const linkTarget = getLinkTarget(agentPath, overlayPath);
+      await createSymlink(linkTarget, agentPath);
+      created.push(relative(targetRoot, agentPath));
+    }
+  });
+
+  return { created, skipped };
+}
+
+/** Process a single prompt mapping into symlinks for all agent directories */
+async function processPromptMapping(
+  mapping: FileMapping,
+  targetRoot: string,
+): Promise<{ created: string[] }> {
+  const { overlayPath, targetPath } = mapping;
+  const promptRelPath = getPromptRelPath(targetPath);
+  if (!promptRelPath) return { created: [] };
+
+  const createdPaths = await createPromptLinksShared(
+    overlayPath,
+    promptRelPath,
+    targetRoot,
   );
-  const targetPath = join(targetRoot, ".claude/settings.json");
+  return { created: createdPaths.map((p) => relative(targetRoot, p)) };
+}
 
-  const inOverlay = await fileExists(overlayPath);
-  const inTarget =
-    (await fileExists(targetPath)) && !(await isSymlink(targetPath));
+async function dirMappings(
+  dir: string,
+  context: MapperContext,
+  ignorePatterns: string[] = [],
+): Promise<FileMapping[]> {
+  if (!(await fileExists(dir))) return [];
 
-  if (inTarget && inOverlay) {
-    throw new Error(
-      `Conflict: settings.json exists in both target and overlay.\n` +
-        `  Target: ${targetPath}\n` +
-        `  Overlay: ${overlayPath}\n` +
-        `Remove one to resolve.`,
-    );
+  const mappings: FileMapping[] = [];
+  for await (const overlayPath of walkOverlayFiles(dir, ignorePatterns)) {
+    const result = overlayToTarget(overlayPath, context);
+    if (result) {
+      mappings.push({ overlayPath, ...result });
+    }
   }
+  return mappings;
+}
 
-  if (inTarget) {
-    // Adopt target's settings - move to overlay
-    await ensureDir(dirname(overlayPath));
-    await rename(targetPath, overlayPath);
-    console.log(`Moved .claude/settings.json to overlay`);
-  } else if (!inOverlay) {
-    // Neither exists - create blank in overlay
-    await ensureDir(dirname(overlayPath));
-    await writeFile(overlayPath, "{}\n", "utf-8");
-    console.log(
-      `Created .claude/settings.json symlink (project settings will be stored in overlay)`,
-    );
+/** Check if a subdirectory clank file's parent exists in the target */
+async function checkMappingParentExists(
+  m: FileMapping,
+  targetRoot: string,
+): Promise<FileMapping | null> {
+  const relPath = relative(targetRoot, m.targetPath);
+  // Subdirectory clank files have /clank/ in the middle of the path
+  const clankIndex = relPath.indexOf("/clank/");
+  if (clankIndex !== -1) {
+    // Check if parent directory exists (e.g., packages/foo for packages/foo/clank/notes.md)
+    const parentDir = join(targetRoot, relPath.slice(0, clankIndex));
+    if (!(await fileExists(parentDir))) {
+      return null;
+    }
   }
+  return m;
+}
 
-  // Create symlink (overlay now has the file)
-  await ensureDir(dirname(targetPath));
-  const linkTarget = getLinkTarget(targetPath, overlayPath);
-  await createSymlink(linkTarget, targetPath);
+/** Check if a file is tracked in git (exists as real file, not symlink, and tracked) */
+async function isTrackedFile(path: string, gitRoot: string): Promise<boolean> {
+  if (!(await fileExists(path))) return false;
+  if (await isSymlink(path)) return false;
+  return isTrackedByGit(path, gitRoot);
 }

package/src/commands/Move.ts

@@ -101,22 +101,6 @@ async function moveSingleFile(
   );
 }
 
-/** Recreate a regular symlink after moving */
-async function recreateSymlink(
-  targetPath: string,
-  overlayPath: string,
-  ctx: MoveContext,
-): Promise<void> {
-  // Remove old symlink if it exists
-  if (await isSymlinkToOverlay(targetPath, ctx.overlayRoot)) {
-    await unlink(targetPath);
-  }
-
-  // Create new symlink
-  const linkTarget = getLinkTarget(targetPath, overlayPath);
-  await createSymlink(linkTarget, targetPath);
-}
-
 /** Recreate agent symlinks (CLAUDE.md, GEMINI.md, AGENTS.md) after moving */
 async function recreateAgentLinks(
   normalizedPath: string,
@@ -172,3 +156,19 @@ async function recreatePromptLinks(
     );
   }
 }
+
+/** Recreate a regular symlink after moving */
+async function recreateSymlink(
+  targetPath: string,
+  overlayPath: string,
+  ctx: MoveContext,
+): Promise<void> {
+  // Remove old symlink if it exists
+  if (await isSymlinkToOverlay(targetPath, ctx.overlayRoot)) {
+    await unlink(targetPath);
+  }
+
+  // Create new symlink
+  const linkTarget = getLinkTarget(targetPath, overlayPath);
+  await createSymlink(linkTarget, targetPath);
+}

package/src/commands/Rm.ts

@@ -90,21 +90,30 @@ async function resolveScope(
   return found[0];
 }
 
-/** Search all scopes to find where the file exists */
-async function findInScopes(
+/** Remove agent files (CLAUDE.md, GEMINI.md, AGENTS.md → agents.md) */
+async function removeAgentFiles(
   targetPath: string,
-  context: MapperContext,
-): Promise<Scope[]> {
-  const found: Scope[] = [];
+  overlayPath: string,
+  overlayRoot: string,
+  config: { agents: string[] },
+): Promise<void> {
+  const dir = dirname(targetPath);
+  const removed: string[] = [];
 
-  for (const scope of ["worktree", "project", "global"] as const) {
-    const overlayPath = targetToOverlay(targetPath, scope, context);
-    if (await fileExists(overlayPath)) {
-      found.push(scope);
+  await forEachAgentPath(dir, config.agents, async (linkPath) => {
+    if (await isSymlinkToOverlay(linkPath, overlayRoot)) {
+      await unlink(linkPath);
+      removed.push(basename(linkPath));
     }
+  });
+
+  if (removed.length > 0) {
+    console.log(`Removed symlinks: ${removed.join(", ")}`);
   }
 
-  return found;
+  // Remove agents.md from overlay
+  await rm(overlayPath);
+  console.log(`Removed from overlay: agents.md`);
 }
 
 /** Remove a regular file */
@@ -134,28 +143,19 @@ async function removeFile(
   console.log(`Removed from overlay: ${basename(overlayPath)}`);
 }
 
-/** Remove agent files (CLAUDE.md, GEMINI.md, AGENTS.md → agents.md) */
-async function removeAgentFiles(
+/** Search all scopes to find where the file exists */
+async function findInScopes(
   targetPath: string,
-  overlayPath: string,
-  overlayRoot: string,
-  config: { agents: string[] },
-): Promise<void> {
-  const dir = dirname(targetPath);
-  const removed: string[] = [];
+  context: MapperContext,
+): Promise<Scope[]> {
+  const found: Scope[] = [];
 
-  await forEachAgentPath(dir, config.agents, async (linkPath) => {
-    if (await isSymlinkToOverlay(linkPath, overlayRoot)) {
-      await unlink(linkPath);
-      removed.push(basename(linkPath));
+  for (const scope of ["worktree", "project", "global"] as const) {
+    const overlayPath = targetToOverlay(targetPath, scope, context);
+    if (await fileExists(overlayPath)) {
+      found.push(scope);
     }
-  });
-
-  if (removed.length > 0) {
-    console.log(`Removed symlinks: ${removed.join(", ")}`);
   }
 
-  // Remove agents.md from overlay
-  await rm(overlayPath);
-  console.log(`Removed from overlay: agents.md`);
+  return found;
 }