clank-cli 0.1.61 → 0.1.62

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/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 */

package/src/commands/Check.ts

@@ -1,4 +1,5 @@
 import { basename, join, relative } from "node:path";
+import picomatch from "picomatch";
 import { managedDirs, targetManagedDirs } from "../AgentFiles.ts";
 import {
   agentFileProblems,
@@ -27,6 +28,9 @@ export type UnaddedFile = ManagedFileState & {
   relativePath: string;
 };
 
+/** Files that should remain local and not be tracked by clank */
+const localOnlyFiles = ["settings.local.json"];
+
 /** Check for orphaned overlay paths that don't match target structure */
 export async function checkCommand(): Promise<void> {
   const cwd = process.cwd();
@@ -35,19 +39,131 @@ export async function checkCommand(): Promise<void> {
   const overlayRoot = expandPath(config.overlayRepo);
   const { gitRoot: targetRoot } = gitContext;
   const ctx: MapperContext = { overlayRoot, targetRoot, gitContext };
+  const ignorePatterns = config.ignore ?? [];
 
-  await showOverlayStatus(overlayRoot);
+  await showOverlayStatus(overlayRoot, ignorePatterns);
 
-  const problems = await checkAllProblems(ctx, cwd);
+  const problems = await checkAllProblems(ctx, cwd, ignorePatterns);
   if (!problems) {
     console.log("No issues found. Overlay matches target structure.");
   }
 }
 
+/** Find files in clank-managed directories that aren't valid symlinks to the overlay */
+export async function findUnaddedFiles(
+  context: MapperContext,
+): Promise<UnaddedFile[]> {
+  const { targetRoot } = context;
+  const unadded: UnaddedFile[] = [];
+
+  for await (const { path, isDirectory } of walkDirectory(targetRoot)) {
+    if (isDirectory) continue;
+
+    const relPath = relative(targetRoot, path);
+    if (!isInManagedDir(relPath)) continue;
+    if (isLocalOnlyFile(relPath)) continue;
+
+    const managed = await verifyManaged(path, context);
+    if (managed.kind !== "valid") {
+      unadded.push({ targetPath: path, relativePath: relPath, ...managed });
+    }
+  }
+
+  return unadded;
+}
+
+/** Find overlay paths whose target directories don't exist */
+export async function findOrphans(
+  overlayRoot: string,
+  targetRoot: string,
+  projectName: string,
+  ignorePatterns: string[] = [],
+): Promise<OrphanedPath[]> {
+  const orphans: OrphanedPath[] = [];
+  const projectDir = overlayProjectDir(overlayRoot, projectName);
+
+  if (!(await fileExists(projectDir))) {
+    return orphans;
+  }
+
+  const isIgnored =
+    ignorePatterns.length > 0 ? picomatch(ignorePatterns) : null;
+
+  const skip = (relPath: string): boolean => {
+    if (isIgnored) {
+      const pathBasename = relPath.split("/").at(-1) ?? "";
+      if (isIgnored(relPath) || isIgnored(pathBasename)) return true;
+    }
+    return false;
+  };
+
+  for await (const { path, isDirectory } of walkDirectory(projectDir, {
+    skipDirs: [".git", "node_modules", "worktrees"],
+    skip,
+  })) {
+    if (isDirectory) continue;
+
+    const relPath = relative(projectDir, path);
+
+    // Skip files at project root (agents.md, settings.json)
+    if (!relPath.includes("/")) continue;
+
+    // Skip standard directories that don't map to target subdirs
+    if (managedDirs.some((dir) => relPath.startsWith(`${dir}/`))) {
+      continue;
+    }
+
+    // This is a subdirectory file - check if target dir exists
+    // e.g., tools/packages/wesl/clank/notes.md -> check tools/packages/wesl/
+    const targetSubdir = extractTargetSubdir(relPath);
+    if (!targetSubdir) continue;
+
+    const expectedTargetDir = join(targetRoot, targetSubdir);
+    if (!(await fileExists(expectedTargetDir))) {
+      orphans.push({
+        overlayPath: path,
+        expectedTargetDir: targetSubdir,
+        fileName: basename(path),
+        scope: projectName,
+      });
+    }
+  }
+
+  return orphans;
+}
+
+/** Show git status of the overlay repository */
+async function showOverlayStatus(
+  overlayRoot: string,
+  ignorePatterns: string[] = [],
+): Promise<void> {
+  if (!(await fileExists(overlayRoot))) {
+    console.log("Overlay repository not found\n");
+    return;
+  }
+
+  const lines = await getOverlayStatus(overlayRoot, ignorePatterns);
+
+  console.log(`Overlay: ${overlayRoot}`);
+
+  if (lines.length === 0) {
+    console.log("Status: clean\n");
+    return;
+  }
+
+  console.log(`Status: ${lines.length} uncommitted change(s)\n`);
+
+  for (const formatted of formatStatusLines(lines)) {
+    console.log(`  ${formatted}`);
+  }
+  console.log();
+}
+
 /** Run all checks and display problems. Returns true if any problems found. */
 async function checkAllProblems(
   ctx: MapperContext,
   cwd: string,
+  ignorePatterns: string[] = [],
 ): Promise<boolean> {
   const { overlayRoot, targetRoot, gitContext } = ctx;
   let hasProblems = false;
@@ -73,6 +189,7 @@ async function checkAllProblems(
     overlayRoot,
     targetRoot,
     gitContext.projectName,
+    ignorePatterns,
   );
   if (orphans.length > 0) {
     hasProblems = true;
@@ -82,49 +199,35 @@ async function checkAllProblems(
   return hasProblems;
 }
 
-/** Display orphaned paths and remediation prompt */
-function showOrphanedPaths(
-  orphans: OrphanedPath[],
-  targetRoot: string,
-  overlayRoot: string,
-): void {
-  console.log(`Found ${orphans.length} orphaned overlay path(s):\n`);
-  for (const orphan of orphans) {
-    console.log(`  ${orphan.fileName} (${orphan.scope})`);
-    console.log(`    Overlay: ${orphan.overlayPath}`);
-    console.log(`    Expected dir: ${orphan.expectedTargetDir}\n`);
-  }
-
-  console.log("Target project:", targetRoot);
-  console.log("Overlay:", overlayRoot);
-  console.log("\nTo fix with an agent, copy this prompt:");
-  console.log("─".repeat(50));
-  console.log(generateAgentPrompt(orphans, targetRoot, overlayRoot));
-  console.log("─".repeat(50));
+/** Check if a path is inside a clank-managed directory */
+function isInManagedDir(relPath: string): boolean {
+  const parts = relPath.split("/");
+  return parts.some((part) => targetManagedDirs.includes(part));
 }
 
-/** Show git status of the overlay repository */
-async function showOverlayStatus(overlayRoot: string): Promise<void> {
-  if (!(await fileExists(overlayRoot))) {
-    console.log("Overlay repository not found\n");
-    return;
-  }
-
-  const { lines } = await getOverlayStatus(overlayRoot);
-
-  console.log(`Overlay: ${overlayRoot}`);
+/** Check if a file should remain local (not tracked by clank) */
+function isLocalOnlyFile(relPath: string): boolean {
+  const fileName = basename(relPath);
+  return localOnlyFiles.includes(fileName);
+}
 
-  if (lines.length === 0) {
-    console.log("Status: clean\n");
-    return;
+/** Extract the target subdirectory from an overlay path
+ * @param relPath - Path relative to overlay project dir (e.g., targets/wesl-js/)
+ * @returns Target subdirectory path, or null if not a subdirectory file
+ * @example "tools/packages/wesl/clank/notes.md" -> "tools/packages/wesl"
+ * @example "tools/packages/wesl/agents.md" -> "tools/packages/wesl"
+ */
+function extractTargetSubdir(relPath: string): string | null {
+  // Check for /clank/ or /claude/ in path
+  for (const dir of managedDirs) {
+    const idx = relPath.indexOf(`/${dir}/`);
+    if (idx !== -1) return relPath.slice(0, idx);
   }
-
-  console.log(`Status: ${lines.length} uncommitted change(s)\n`);
-
-  for (const formatted of formatStatusLines(lines)) {
-    console.log(`  ${formatted}`);
+  // Check for agents.md in a subdirectory
+  if (relPath.endsWith("/agents.md")) {
+    return relPath.slice(0, -"/agents.md".length);
   }
-  console.log();
+  return null;
 }
 
 /** Display unadded files in clank-managed directories */
@@ -181,108 +284,25 @@ function showUnaddedFiles(
   }
 }
 
-/** Files that should remain local and not be tracked by clank */
-const localOnlyFiles = ["settings.local.json"];
-
-/** Check if a path is inside a clank-managed directory */
-function isInManagedDir(relPath: string): boolean {
-  const parts = relPath.split("/");
-  return parts.some((part) => targetManagedDirs.includes(part));
-}
-
-/** Check if a file should remain local (not tracked by clank) */
-function isLocalOnlyFile(relPath: string): boolean {
-  const fileName = basename(relPath);
-  return localOnlyFiles.includes(fileName);
-}
-
-/** Find files in clank-managed directories that aren't valid symlinks to the overlay */
-export async function findUnaddedFiles(
-  context: MapperContext,
-): Promise<UnaddedFile[]> {
-  const { targetRoot } = context;
-  const unadded: UnaddedFile[] = [];
-
-  for await (const { path, isDirectory } of walkDirectory(targetRoot)) {
-    if (isDirectory) continue;
-
-    const relPath = relative(targetRoot, path);
-    if (!isInManagedDir(relPath)) continue;
-    if (isLocalOnlyFile(relPath)) continue;
-
-    const managed = await verifyManaged(path, context);
-    if (managed.kind !== "valid") {
-      unadded.push({ targetPath: path, relativePath: relPath, ...managed });
-    }
-  }
-
-  return unadded;
-}
-
-/** Find overlay paths whose target directories don't exist */
-export async function findOrphans(
-  overlayRoot: string,
+/** Display orphaned paths and remediation prompt */
+function showOrphanedPaths(
+  orphans: OrphanedPath[],
   targetRoot: string,
-  projectName: string,
-): Promise<OrphanedPath[]> {
-  const orphans: OrphanedPath[] = [];
-  const projectDir = overlayProjectDir(overlayRoot, projectName);
-
-  if (!(await fileExists(projectDir))) {
-    return orphans;
-  }
-
-  for await (const { path, isDirectory } of walkDirectory(projectDir, {
-    skipDirs: [".git", "node_modules", "worktrees"],
-  })) {
-    if (isDirectory) continue;
-
-    const relPath = relative(projectDir, path);
-
-    // Skip files at project root (agents.md, settings.json)
-    if (!relPath.includes("/")) continue;
-
-    // Skip standard directories that don't map to target subdirs
-    if (managedDirs.some((dir) => relPath.startsWith(`${dir}/`))) {
-      continue;
-    }
-
-    // This is a subdirectory file - check if target dir exists
-    // e.g., tools/packages/wesl/clank/notes.md -> check tools/packages/wesl/
-    const targetSubdir = extractTargetSubdir(relPath);
-    if (!targetSubdir) continue;
-
-    const expectedTargetDir = join(targetRoot, targetSubdir);
-    if (!(await fileExists(expectedTargetDir))) {
-      orphans.push({
-        overlayPath: path,
-        expectedTargetDir: targetSubdir,
-        fileName: basename(path),
-        scope: projectName,
-      });
-    }
+  overlayRoot: string,
+): void {
+  console.log(`Found ${orphans.length} orphaned overlay path(s):\n`);
+  for (const orphan of orphans) {
+    console.log(`  ${orphan.fileName} (${orphan.scope})`);
+    console.log(`    Overlay: ${orphan.overlayPath}`);
+    console.log(`    Expected dir: ${orphan.expectedTargetDir}\n`);
   }
 
-  return orphans;
-}
-
-/** Extract the target subdirectory from an overlay path
- * @param relPath - Path relative to overlay project dir (e.g., targets/wesl-js/)
- * @returns Target subdirectory path, or null if not a subdirectory file
- * @example "tools/packages/wesl/clank/notes.md" -> "tools/packages/wesl"
- * @example "tools/packages/wesl/agents.md" -> "tools/packages/wesl"
- */
-function extractTargetSubdir(relPath: string): string | null {
-  // Check for /clank/ or /claude/ in path
-  for (const dir of managedDirs) {
-    const idx = relPath.indexOf(`/${dir}/`);
-    if (idx !== -1) return relPath.slice(0, idx);
-  }
-  // Check for agents.md in a subdirectory
-  if (relPath.endsWith("/agents.md")) {
-    return relPath.slice(0, -"/agents.md".length);
-  }
-  return null;
+  console.log("Target project:", targetRoot);
+  console.log("Overlay:", overlayRoot);
+  console.log("\nTo fix with an agent, copy this prompt:");
+  console.log("─".repeat(50));
+  console.log(generateAgentPrompt(orphans, targetRoot, overlayRoot));
+  console.log("─".repeat(50));
 }
 
 /** Generate agent prompt for fixing orphaned paths */

package/src/commands/Commit.ts

@@ -18,7 +18,7 @@ export async function commitCommand(
   const message = options.message || "update";
   const fullMessage = `[clank] ${message}`;
 
-  const { lines } = await getOverlayStatus(overlayRoot);
+  const lines = await getOverlayStatus(overlayRoot);
 
   if (lines.length === 0) {
     console.log("Nothing to commit");