clank-cli 0.1.52

package/src/Cli.ts

@@ -0,0 +1,229 @@
+import { Command, Option } from "commander";
+import pkg from "../package.json" with { type: "json" };
+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 { initCommand } from "./commands/Init.ts";
+import { linkCommand } from "./commands/Link.ts";
+import { moveCommand } from "./commands/Move.ts";
+import { rmCommand } from "./commands/Rm.ts";
+import { unlinkCommand } from "./commands/Unlink.ts";
+import { vscodeCommand } from "./commands/VsCode.ts";
+
+const defaultOverlayMsg = `(default: ~/${defaultOverlayDir})`;
+
+const structureHelp = `
+Clank Overlay Directory Structure
+═════════════════════════════════
+
+~/clankover/
+├── global/                      # Shared across all projects
+│   ├── clank/                   # Global files (--global)
+│   │   └── style.md
+│   ├── claude/                  # Claude Code specific
+│   │   ├── commands/            # -> .claude/commands/
+│   │   └── agents/              # -> .claude/agents/
+│   └── init/                    # Templates for new worktrees
+│       └── notes.md
+└── targets/
+    └── <project>/               # Per-project files
+        ├── agents.md            # Agent instructions (-> CLAUDE.md, etc.)
+        ├── clank/               # Project files (--project)
+        │   └── overview.md
+        ├── claude/              # Claude Code specific
+        │   ├── settings.json    # -> .claude/settings.json
+        │   ├── commands/        # -> .claude/commands/
+        │   └── agents/          # -> .claude/agents/
+        ├── <subdir>/clank/      # Subdirectory files (monorepo support)
+        │   └── notes.md         # -> <subdir>/clank/notes.md
+        └── worktrees/
+            └── <branch>/        # Worktree files (--worktree)
+                └── clank/
+                    └── notes.md
+
+Mapping Rules
+─────────────
+  Overlay Path                           Target Path
+  ────────────                           ───────────
+  global/clank/<file>                 -> clank/<file>
+  global/claude/commands/<file>       -> .claude/commands/<file>
+  targets/<proj>/clank/<file>         -> clank/<file>
+  targets/<proj>/claude/commands/     -> .claude/commands/
+  targets/<proj>/agents.md            -> CLAUDE.md, AGENTS.md, GEMINI.md
+  targets/<proj>/<sub>/clank/<file>   -> <sub>/clank/<file>
+  targets/<proj>/worktrees/<br>/clank -> clank/
+
+Scopes
+──────
+  --global    Shared across all projects
+  --project   Shared across all branches (default)
+  --worktree  This branch only
+`.trim();
+export function createCLI(): Command {
+  const program = new Command();
+
+  program
+    .name("clank")
+    .description("Keep your AI files in an overlay repository")
+    .version(pkg.version)
+    .option("-c, --config <path>", `Path to config file ${defaultOverlayMsg}`)
+    .hook("preAction", (thisCommand) => {
+      const opts = thisCommand.optsWithGlobals();
+      if (opts.config) setConfigPath(opts.config);
+    });
+
+  registerCommands(program);
+  return program;
+}
+
+export async function runCLI(): Promise<void> {
+  const program = createCLI();
+  await program.parseAsync(process.argv);
+}
+
+function registerCommands(program: Command): void {
+  registerCoreCommands(program);
+  registerHelpCommands(program);
+}
+
+function registerCoreCommands(program: Command): void {
+  registerOverlayCommands(program);
+  registerUtilityCommands(program);
+}
+
+function registerOverlayCommands(program: Command): void {
+  program
+    .command("init")
+    .description(
+      `Initialize a new clank overlay repository ${defaultOverlayMsg}`,
+    )
+    .argument(
+      "[overlay-path]",
+      `Path to overlay repository ${defaultOverlayMsg}`,
+    )
+    .action(withErrorHandling(initCommand));
+
+  program
+    .command("link")
+    .description("Link overlay repository to target directory")
+    .argument("[target]", "Target directory (default: current directory)")
+    .action(withErrorHandling(linkCommand));
+
+  program
+    .command("add")
+    .description("Add file(s) to overlay and create symlinks")
+    .argument(
+      "<files...>",
+      "File path(s) (e.g., style.md, .claude/commands/review.md)",
+    )
+    .option("-g, --global", "Add to global location (all projects)")
+    .option("-p, --project", "Add to project location (default)")
+    .option("-w, --worktree", "Add to worktree location (this branch only)")
+    .action(withErrorHandling(addCommand));
+
+  program
+    .command("unlink")
+    .description("Remove all clank symlinks from target directory")
+    .argument("[target]", "Target directory (default: current directory)")
+    .action(withErrorHandling(unlinkCommand));
+
+  registerRmCommand(program);
+  registerMvCommand(program);
+
+  program
+    .command("commit")
+    .description("Commit all changes in the overlay repository")
+    .option("-m, --message <message>", "Commit message")
+    .action(withErrorHandling(commitCommand));
+}
+
+function registerUtilityCommands(program: Command): void {
+  program
+    .command("check")
+    .alias("status")
+    .description("Show overlay status and check for issues")
+    .action(withErrorHandling(checkCommand));
+
+  program
+    .command("vscode")
+    .description("Generate VS Code settings to show clank files")
+    .option("--remove", "Remove clank-generated VS Code settings")
+    .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 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

@@ -0,0 +1,98 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+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[];
+  /** Generate .vscode/settings.json to make clank files visible in search/explorer */
+  vscodeSettings?: "auto" | "always" | "never";
+  /** Add .vscode/settings.json to .git/info/exclude (default: true) */
+  vscodeGitignore?: boolean;
+}
+
+const defaultConfig: ClankConfig = {
+  overlayRepo: join(homedir(), defaultOverlayDir),
+  agents: ["agents", "claude", "gemini"],
+};
+
+const explorer = cosmiconfig("clank");
+let customConfigPath: string | undefined;
+
+/** path to user's clank config file */
+export function setConfigPath(path: string | undefined): void {
+  customConfigPath = path;
+}
+
+/** Load global clank configuration from ~/.config/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) {
+      return defaultConfig;
+    }
+    return { ...defaultConfig, ...result.config };
+  }
+
+  const result = await explorer.search(getConfigDir());
+  if (!result || result.isEmpty) {
+    return defaultConfig;
+  }
+  return { ...defaultConfig, ...result.config };
+}
+
+/** Create default configuration file at ~/.config/clank/config.js */
+export async function createDefaultConfig(overlayRepo?: string): Promise<void> {
+  const configDir = getConfigDir();
+  const configPath = customConfigPath || join(configDir, "config.js");
+
+  const config = {
+    ...defaultConfig,
+    ...(overlayRepo && { overlayRepo }),
+  };
+
+  const content = `export default ${JSON.stringify(config, null, 2)};\n`;
+
+  if (!customConfigPath) {
+    await mkdir(configDir, { recursive: true });
+  }
+
+  await writeFile(configPath, content, "utf-8");
+  console.log(`Config file created at: ${configPath}`);
+}
+
+/** Expand ~ in paths to home directory */
+export function expandPath(path: string): string {
+  if (path.startsWith("~/") || path === "~") {
+    return join(homedir(), path.slice(1));
+  }
+  return path;
+}
+
+/** Get the expanded overlay repository path from config */
+export async function getOverlayPath(): Promise<string> {
+  const config = await loadConfig();
+  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): Promise<void> {
+  if (!(await fileExists(overlayRoot))) {
+    throw new Error(
+      `Overlay repository not found at ${overlayRoot}\nRun 'clank init' to create it`,
+    );
+  }
+}

package/src/Exclude.ts

@@ -0,0 +1,154 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { agentFiles, targetManagedDirs } from "./AgentFiles.ts";
+import { execFileAsync } from "./Exec.ts";
+import { isTrackedByGit, readFileIfExists } from "./FsUtil.ts";
+import { getGitCommonDir, getGitDir } from "./Git.ts";
+
+export const clankMarkerStart = "# Added by clank";
+export const clankMarkerEnd = "# End clank";
+
+/** Add clank entries to .git/info/exclude */
+export async function addGitExcludes(targetRoot: string): Promise<void> {
+  const gitDir = await getGitCommonDir(targetRoot);
+  if (!gitDir) return;
+
+  const infoDir = join(gitDir, "info");
+  const excludePath = join(infoDir, "exclude");
+
+  // Ensure info directory exists (may not exist in worktrees)
+  await mkdir(infoDir, { recursive: true });
+
+  let content = (await readFileIfExists(excludePath)) ?? "";
+
+  // Remove existing clank section to rebuild with current entries
+  if (content.includes(clankMarkerStart)) {
+    content = removeClankSection(content);
+  }
+
+  // Build exclude list dynamically based on what's not tracked
+  const excludeList: string[] = [];
+
+  // Only exclude managed directories if they have no tracked files
+  for (const dir of targetManagedDirs) {
+    if (!(await hasTrackedFiles(dir, targetRoot))) {
+      excludeList.push(`${dir}/`);
+    }
+  }
+
+  // Only exclude agent files if not tracked
+  for (const agentFile of agentFiles) {
+    const agentPath = join(targetRoot, agentFile);
+    if (!(await isTrackedByGit(agentPath, targetRoot))) {
+      excludeList.push(agentFile);
+    }
+  }
+
+  const clankSection = [
+    "",
+    clankMarkerStart,
+    ...excludeList,
+    clankMarkerEnd,
+    "",
+  ].join("\n");
+
+  await writeFile(excludePath, content + clankSection, "utf-8");
+  console.log("Added clank entries to .git/info/exclude");
+}
+
+/** Add a single entry to the clank block in .git/info/exclude */
+export async function addToGitExclude(
+  targetRoot: string,
+  entry: string,
+): Promise<void> {
+  const gitDir = await getGitCommonDir(targetRoot);
+  if (!gitDir) return;
+
+  const infoDir = join(gitDir, "info");
+  const excludePath = join(infoDir, "exclude");
+
+  await mkdir(infoDir, { recursive: true });
+
+  let content = (await readFileIfExists(excludePath)) ?? "";
+  if (content.includes(entry)) return;
+
+  if (content.includes(clankMarkerStart)) {
+    content = content.replace(clankMarkerEnd, `${entry}\n${clankMarkerEnd}`);
+  } else {
+    content += `\n${clankMarkerStart}\n${entry}\n${clankMarkerEnd}\n`;
+  }
+
+  await writeFile(excludePath, content, "utf-8");
+}
+
+/** Remove clank entries from .git/info/exclude */
+export async function removeGitExcludes(targetRoot: string): Promise<void> {
+  // Don't modify shared excludes from a worktree
+  if (await isWorktree(targetRoot)) return;
+
+  const gitDir = await getGitCommonDir(targetRoot);
+  if (!gitDir) return;
+
+  const excludePath = join(gitDir, "info/exclude");
+  const content = await readFileIfExists(excludePath);
+
+  if (!content || !content.includes(clankMarkerStart)) {
+    return; // No clank entries
+  }
+
+  const newContent = removeClankSection(content);
+
+  await writeFile(excludePath, newContent, "utf-8");
+  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[] = [];
+  let inClankSection = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === clankMarkerStart) {
+      inClankSection = true;
+    } else if (trimmed === clankMarkerEnd) {
+      inClankSection = false;
+    } else if (!inClankSection) {
+      result.push(line);
+    }
+  }
+  return result;
+}
+
+/** Check if a directory has any tracked files */
+async function hasTrackedFiles(
+  dirPath: string,
+  repoRoot: string,
+): Promise<boolean> {
+  try {
+    const { stdout } = await execFileAsync("git", ["ls-files", "--", dirPath], {
+      cwd: repoRoot,
+    });
+    return stdout.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Check if we're in a worktree (git-dir differs from git-common-dir) */
+async function isWorktree(targetRoot: string): Promise<boolean> {
+  const [gitDir, commonDir] = await Promise.all([
+    getGitDir(targetRoot),
+    getGitCommonDir(targetRoot),
+  ]);
+  return gitDir !== commonDir;
+}

package/src/Exec.ts

@@ -0,0 +1,5 @@
+import { exec as execCallback, execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+export const exec = promisify(execCallback);
+export const execFileAsync = promisify(execFile);

package/src/FsUtil.ts

@@ -0,0 +1,154 @@
+import { lstat, mkdir, readdir, readFile, readlink, symlink, unlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { execFileAsync } from "./Exec.ts";
+
+/**
+ * Create a symbolic link, removing existing link/file first
+ * @param target - The path the symlink should point to (absolute)
+ * @param linkPath - The location of the symlink itself (absolute)
+ */
+export async function createSymlink(
+  target: string,
+  linkPath: string,
+): Promise<void> {
+  await ensureDir(dirname(linkPath));
+
+  try {
+    await unlink(linkPath);
+  } catch {
+    // File doesn't exist, which is fine
+  }
+
+  await symlink(target, linkPath);
+}
+
+/** Remove a symlink if it exists */
+export async function removeSymlink(linkPath: string): Promise<void> {
+  try {
+    const stats = await lstat(linkPath);
+    if (stats.isSymbolicLink()) {
+      await unlink(linkPath);
+    }
+  } catch {
+    // Symlink doesn't exist, which is fine
+  }
+}
+
+/**
+ * Get the symlink target path (absolute)
+ * @param _from - The location of the symlink (unused, kept for API compatibility)
+ * @param to - The target of the symlink (absolute)
+ * @returns Absolute path to the target
+ */
+export function getLinkTarget(_from: string, to: string): string {
+  return to;
+}
+
+/** Recursively walk a directory, yielding all files and directories */
+export async function* walkDirectory(
+  dir: string,
+  options: { skipDirs?: 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 };
+      }
+    }
+  } catch (_error) {
+    // Directory doesn't exist or can't be read
+    return;
+  }
+}
+
+/** Ensure directory exists, creating it recursively if needed */
+export async function ensureDir(dirPath: string): Promise<void> {
+  await mkdir(dirPath, { recursive: true });
+}
+
+/** Check if a file exists */
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await lstat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Check if a file is tracked by git */
+export async function isTrackedByGit(
+  filePath: string,
+  repoRoot: string,
+): Promise<boolean> {
+  try {
+    const relPath = relative(repoRoot, filePath);
+    await execFileAsync("git", ["ls-files", "--error-unmatch", relPath], {
+      cwd: repoRoot,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Check if a path is a symlink */
+export async function isSymlink(filePath: string): Promise<boolean> {
+  try {
+    const stats = await lstat(filePath);
+    return stats.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** Get path relative to cwd, or "." if same directory */
+export function relativePath(cwd: string, path: string): string {
+  return relative(cwd, path) || ".";
+}
+
+/** Resolve a symlink to its absolute target path */
+export async function resolveSymlinkTarget(linkPath: string): Promise<string> {
+  const target = await readlink(linkPath);
+  return isAbsolute(target) ? target : join(dirname(linkPath), target);
+}
+
+/** Read a file if it exists, returning null if not found */
+export async function readFileIfExists(
+  filePath: string,
+): Promise<string | null> {
+  if (!(await fileExists(filePath))) return null;
+  return await readFile(filePath, "utf-8");
+}
+
+/** Read and parse a JSON file */
+export async function readJsonFile<T = Record<string, unknown>>(
+  filePath: string,
+): Promise<T | null> {
+  const content = await readFileIfExists(filePath);
+  if (!content) return null;
+  try {
+    return JSON.parse(content) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Write an object as formatted JSON */
+export async function writeJsonFile(
+  filePath: string,
+  data: unknown,
+): Promise<void> {
+  await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}