clank-cli 0.1.61 → 0.1.62

package/README.md

@@ -205,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
@@ -243,7 +243,7 @@ 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 {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clank-cli",
   "description": "Keep AI files in a separate overlay repository",
-  "version": "0.1.61",
+  "version": "0.1.62",
   "author": "",
   "type": "module",
   "bin": {

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

@@ -93,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")
@@ -155,9 +173,63 @@ function registerUtilityCommands(program: Command): void {
     .action(withErrorHandling(vscodeCommand));
 }
 
+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 {
+  program
+    .command("rm")
+    .alias("remove")
+    .description("Remove file(s) from overlay and target")
+    .argument("<files...>", "File(s) to remove")
+    .option("-g, --global", "Remove from global scope")
+    .option("-p, --project", "Remove from project scope")
+    .option("-w, --worktree", "Remove from worktree scope")
+    .action(withErrorHandling(rmCommand));
+}
+
+function registerMvCommand(program: Command): void {
+  const cmd = program
+    .command("mv")
+    .alias("move")
+    .description("Move file(s) between overlay scopes")
+    .argument("<files...>", "File(s) to move");
+
+  cmd.addOption(
+    new Option("-g, --global", "Move to global scope").conflicts([
+      "project",
+      "worktree",
+    ]),
+  );
+  cmd.addOption(
+    new Option("-p, --project", "Move to project scope").conflicts([
+      "global",
+      "worktree",
+    ]),
+  );
+  cmd.addOption(
+    new Option("-w, --worktree", "Move to worktree scope").conflicts([
+      "global",
+      "project",
+    ]),
+  );
+  cmd.action(withErrorHandling(moveCommand));
+}
+
 function registerFilesCommand(program: Command): void {
   const files = program
     .command("files")
+    .alias("list")
     .description("List clank-managed files (paths relative to cwd)")
     .argument(
       "[path]",
@@ -201,74 +273,3 @@ function registerFilesCommand(program: Command): void {
 
   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) 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 registerRmCommand(program: Command): void {
-  program
-    .command("rm")
-    .alias("remove")
-    .description("Remove file(s) from overlay and target")
-    .argument("<files...>", "File(s) to remove")
-    .option("-g, --global", "Remove from global scope")
-    .option("-p, --project", "Remove from project scope")
-    .option("-w, --worktree", "Remove from worktree scope")
-    .action(withErrorHandling(rmCommand));
-}
-
-function registerMvCommand(program: Command): void {
-  const cmd = program
-    .command("mv")
-    .alias("move")
-    .description("Move file(s) between overlay scopes")
-    .argument("<files...>", "File(s) to move");
-
-  cmd.addOption(
-    new Option("-g, --global", "Move to global scope").conflicts([
-      "project",
-      "worktree",
-    ]),
-  );
-  cmd.addOption(
-    new Option("-p, --project", "Move to project scope").conflicts([
-      "global",
-      "worktree",
-    ]),
-  );
-  cmd.addOption(
-    new Option("-w, --worktree", "Move to worktree scope").conflicts([
-      "global",
-      "project",
-    ]),
-  );
-  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);
-    }
-  };
-}

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[];
@@ -17,6 +15,8 @@ export interface ClankConfig {
   ignore?: string[];
 }
 
+export const defaultOverlayDir = "clankover";
+
 const defaultConfig: ClankConfig = {
   overlayRepo: join(homedir(), defaultOverlayDir),
   agents: ["agents", "claude", "gemini"],
@@ -30,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 };
@@ -50,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,
@@ -84,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,
@@ -100,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/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 } };
 }

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 (isClankPath(relPath)) {
-    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)
@@ -276,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,
@@ -312,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");
-}