clank-cli 0.1.52

package/README.md

@@ -0,0 +1,312 @@
+# Clank
+
+Store AI agent files and notes in a separate git repository. Git-ignored symlinks make the files visible in your projects.
+
+- **`clank add`** to move files to the overlay.
+- **`clank link`** to connect overlay files to your project.
+- **`clank unlink`** to disconnect.
+- **`clank commit`** to commit changes in the overlay repository.
+- **`clank check`** to show overlay status and help realign overlay files when your project restructures.
+
+## Why a Separate Repository?
+
+Clank stores your AI agent files (CLAUDE.md, commands, notes) in a separate git repository 
+symlinks them into your project. This separation provides key advantages:
+
+- **Different Review Cadence**: Update agent instructions, commands, and notes without requiring the same review process as production code.
+- **Work on Repos You Don't Control**: Add agent context to open source projects or third-party codebases without forking or modifying.
+- **Persist Knowledge Across Forks**: Keep your agent context when working across multiple forks of the same project.
+
+## Features
+
+- **Separate Tracking**: Agent files live in their own repository with independent version control.
+- **Multi-Agent Support**: Single source file, multiple symlinks (AGENTS.md, CLAUDE.md, GEMINI.md).
+- **Worktree-Aware**: Works seamlessly with git worktrees.
+- **Git Ignored**: Agent files are ignored in the main repo, tracked in the overlay repo.
+- **Three Scopes**: Global (all projects), Project (all branches), Worktree (this branch only).
+
+## Installation
+
+```bash
+npm install -g clank
+```
+
+Or use directly with npx:
+
+```bash
+npx clank init
+```
+
+## Quick Start
+
+### 1. Initialize Overlay Repository
+
+```bash
+clank init
+# Creates ~/clankover with default structure
+# Creates ~/.config/clank/config.js
+```
+
+### 2. Link to Your Project
+
+```bash
+cd ~/my-project
+clank link
+# Auto-detects project name from git
+# Creates symlinks from overlay to current directory
+```
+
+### 3. Add Files with `clank add`
+
+The `clank add` command moves files to the overlay and creates symlinks.
+Agent files (CLAUDE.md, AGENTS.md) stay in place; other files go in `clank/`.
+
+> You can run `clank add` from any subdirectory. Agent files and `clank/` folders work at any level in your project tree.
+
+```bash
+# Add to project scope (default) - shared across all branches
+clank add CLAUDE.md
+
+# Add to global scope - shared across all projects
+clank add style.md --global
+
+# Add to worktree scope - this branch only
+clank add notes.md --worktree
+
+# Add commands
+clank add .claude/commands/review.md --global   # All projects
+clank add .claude/commands/build.md             # This project
+
+# Add a directory (all files inside)
+clank add clank/
+```
+
+## Commands
+
+### `clank init [overlay-path]`
+
+Run once to create the overlay repository (default: `~/clankover`) and config file.
+
+```bash
+clank init                      # Default: ~/clankover
+clank init ~/my-clankover       # Custom location
+```
+
+### `clank link [target]`
+
+Create symlinks from the overlay's agent files and notes into your project (current project by default).
+
+```bash
+clank link              # Link current project to clank
+clank link ~/my-project # Link to specific project
+```
+
+### `clank add <file> [options]`
+
+Move a file to the overlay and replace it with a symlink.
+If the file doesn't exist, an empty file is created.
+
+**Scope Options:**
+
+| Flag | Scope | Shared Across |
+|------|-------|---------------|
+| `--global` | Global | All projects |
+| `--project` | Project (default) | All branches in project |
+| `--worktree` | Worktree | This branch only |
+
+**Examples:**
+```bash
+clank add style.md                            # Project scope (default)
+clank add style.md --global                   # Global scope
+clank add notes.md --worktree                 # Worktree scope
+clank add .claude/commands/review.md --global # Global command
+clank add .claude/commands/build.md           # Project command (default)
+clank add CLAUDE.md                           # Creates agents.md + agent symlinks
+```
+
+### `clank unlink [target]`
+
+Remove all clank symlinks from target directory.
+
+**Example:**
+```bash
+clank unlink            # Unlink current directory
+clank unlink ~/my-project
+```
+
+### `clank commit [-m message]`
+
+Commit all changes in the overlay repository.
+
+**Options:**
+- `-m, --message <message>` - Commit message (default: "update")
+
+All commits are prefixed with `[clank]` and include a summary of changed files.
+
+**Example:**
+```bash
+clank commit                        # Commits with "[clank] update"
+clank commit -m "add style guide"   # Commits with "[clank] add style guide"
+```
+
+### `clank check`
+
+Check for orphaned overlay paths that don't match the target project structure.
+Useful when a target project has renamed directories and the overlay needs updating.
+
+Outputs an agent-friendly prompt to help fix mismatches.
+
+**Example:**
+```bash
+clank check
+# Found 2 orphaned overlay path(s):
+#   notes.md (my-project)
+#     Expected dir: packages/old-name
+# ...
+# To fix with an agent, copy this prompt:
+# ──────────────────────────────────────────────────
+# The following overlay files no longer match...
+```
+
+### `clank help structure`
+
+Show the overlay directory structure and mapping rules.
+
+```bash
+clank help structure
+```
+
+### `--config <path>` (global option)
+
+Specify a custom config file location (default `~/.config/clank/config.js`).
+
+```bash
+clank --config /tmp/test-config.js init /tmp/test-overlay
+clank --config /tmp/test-config.js link
+```
+
+## Project Symlinks
+
+Clank places symlinks in your project referencing the relevant files in the overlay repository.
+
+```
+~/my-project/
+├── CLAUDE.md                        # Agent file (→ overlay)
+├── GEMINI.md                        # Same content, different name
+├── .claude/commands/                # Claude commands (→ overlay)
+├── clank/notes.md                   # Notes and other files (→ overlay)
+└── packages/core/
+    ├── CLAUDE.md                    # Package-level agent file
+    ├── GEMINI.md
+    └── clank/architecture.md        # Package-level notes
+```
+
+`clank link` configures git to ignore the symlinks.
+
+### Scope Suffixes
+
+If you add a file with the same name at different scopes (e.g., `notes.md` with both `--global` and `--worktree`), Clank distinguishes them with suffixes:
+
+```
+clank/
+├── notes.md           # Global (no suffix)
+├── notes-project.md   # Project
+└── notes-worktree.md  # Worktree
+```
+
+## Configuration
+
+Global configuration is stored by default in `~/.config/clank/config.js`:
+
+```javascript
+export default {
+  overlayRepo: "~/clankover",
+  agents: ["agents", "claude", "gemini"],
+  vscodeSettings: "auto",  // "auto" | "always" | "never"
+  vscodeGitignore: true
+};
+```
+
+- `agents` - which symlinks to create for agent files like CLAUDE.md
+- `vscodeSettings` - when to generate `.vscode/settings.json` to show clank files in VS Code
+  - `"auto"` (default): only if project already has a `.vscode` directory
+  - `"always"`: always generate settings
+  - `"never"`: never auto-generate (you can still run `clank vscode` manually)
+- `vscodeGitignore` - add `.vscode/settings.json` to `.git/info/exclude` (default: true)
+
+By default, clank creates symlinks for AGENTS.md, CLAUDE.md, and GEMINI.md.
+Run `clank unlink` then `clank link` to apply config changes.
+
+## Worktree Templates
+
+Customize `overlay/global/init/` to create starter notes and planning files 
+for worktrees. 
+When you run `clank link` in a new worktree, 
+these templates are copied into your overlay.
+
+Available placeholders:
+
+- `{{worktree_message}}` - "This is git worktree {branch} of project {project}."
+- `{{project_name}}` - Project name from git
+- `{{branch_name}}` - Current branch/worktree name
+
+## Design Principles
+
+1. **Everything is linked, nothing is copied** - Single source of truth in overlay
+2. **Git-aware** - Automatic project and worktree detection
+3. **Explicit scopes** - Three clear levels: global, project, worktree
+4. **Flat target structure** - All clank notes show up together in `clank/`
+5. **Simple commands** - mostly `clank add` and `clank link`
+
+## Reference
+
+### Overlay Repository Structure
+
+```
+~/clankover/
+├── global/
+│   ├── clank/                # Global files (--global)
+│   │   └── style.md
+│   ├── prompts/              # -> .claude/prompts/, .gemini/prompts/
+│   │   └── review.md
+│   ├── claude/               # Claude Code specific
+│   │   ├── commands/         # -> .claude/commands/
+│   │   └── agents/           # -> .claude/agents/
+│   ├── gemini/               # Gemini specific
+│   │   └── commands/         # -> .gemini/commands/
+│   └── init/                 # Templates for new worktrees
+│       └── clank/
+│           └── notes.md
+└── targets/
+    └── my-project/
+        ├── agents.md         # Agent instructions (source of truth)
+        ├── clank/            # Project files (--project)
+        │   └── overview.md
+        ├── prompts/          # -> .claude/prompts/, .gemini/prompts/
+        │   └── manifest.md
+        ├── claude/           # Claude Code specific
+        │   ├── settings.json # -> .claude/settings.json
+        │   ├── commands/     # -> .claude/commands/
+        │   └── agents/       # -> .claude/agents/
+        ├── gemini/           # Gemini specific
+        │   └── commands/     # -> .gemini/commands/
+        └── worktrees/
+            ├── main/
+            │   ├── clank/    # Worktree files (--worktree)
+            │   │   └── notes.md
+            │   ├── prompts/  # Worktree-specific prompts
+            │   └── agents.md # Worktree agents file (optional)
+            └── feature-auth/
+                └── clank/
+                    └── notes.md
+```
+
+## Requirements
+
+- Node.js >= 22.6.0
+- Git repository (for project/worktree detection)
+- macOS, Linux, or [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)
+
+## License
+
+MIT

package/bin/clank.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env -S node --experimental-strip-types
+
+import { runCLI } from "../src/Cli.ts";
+
+runCLI().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "clank-cli",
+  "version": "0.1.52",
+  "description": "Keep AI files in a separate overlay repository",
+  "type": "module",
+  "bin": {
+    "clank": "./bin/clank.ts"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "keywords": [
+    "ai",
+    "assistant",
+    "claude",
+    "gemini",
+    "copilot",
+    "configuration",
+    "worktree",
+    "git"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^14.0.2",
+    "cosmiconfig": "^9.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.8",
+    "@types/node": "^24.10.1",
+    "execa": "^9.6.1",
+    "monobump": "^0.1.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.14"
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "typecheck": "tsc --noEmit",
+    "bump": "monobump",
+    "global": "pnpm link --global",
+    "build": "tsc",
+    "lint": "biome check",
+    "fix": "biome check --fix --unsafe"
+  }
+}

package/src/AgentFiles.ts

@@ -0,0 +1,40 @@
+import { join } from "node:path";
+
+/** Base agent directory names (without leading dot) */
+export const agentDirNames = ["claude", "gemini"];
+
+/** Agent directories as they appear in target (with leading dot) */
+export const managedAgentDirs = agentDirNames.map((d) => `.${d}`);
+
+/** Agent file names that clank manages */
+export const agentFiles = ["AGENTS.md", "CLAUDE.md", "GEMINI.md"];
+
+/** Directory names managed by clank (as stored in overlay, without leading dot) */
+export const managedDirs = ["clank", "prompts", ...agentDirNames];
+
+/** Directory names managed by clank (as stored in target, with leading dot) */
+export const targetManagedDirs = ["clank", ...managedAgentDirs];
+
+/** Build agent file paths mapping for a directory */
+export function getAgentFilePaths(dir: string): Record<string, string> {
+  return {
+    agents: join(dir, "AGENTS.md"),
+    claude: join(dir, "CLAUDE.md"),
+    gemini: join(dir, "GEMINI.md"),
+  };
+}
+
+/** Iterate over agent file paths, calling fn for each configured agent */
+export async function forEachAgentPath(
+  dir: string,
+  agents: string[],
+  fn: (agentPath: string, agentName: string) => Promise<void>,
+): Promise<void> {
+  const agentPaths = getAgentFilePaths(dir);
+  for (const agent of agents) {
+    const key = agent.toLowerCase();
+    const agentPath = agentPaths[key];
+    if (!agentPath) continue;
+    await fn(agentPath, agent);
+  }
+}

package/src/ClassifyFiles.ts

@@ -0,0 +1,203 @@
+import { lstat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { agentFiles } from "./AgentFiles.ts";
+import { isTrackedByGit, relativePath, resolveSymlinkTarget, walkDirectory } from "./FsUtil.ts";
+import type { GitContext } from "./Git.ts";
+import { type MapperContext, targetToOverlay } from "./Mapper.ts";
+
+/** Agent files grouped by problem type */
+export interface AgentFileClassification {
+  /** Tracked in git - needs conversion (git rm --cached + clank add) */
+  tracked: string[];
+
+  /** Untracked real files - needs clank add first */
+  untracked: string[];
+
+  /** Symlinks pointing somewhere other than overlay - needs removal */
+  staleSymlinks: string[];
+
+  /** Symlinks pointing to wrong path in overlay (e.g., after rename) */
+  outdatedSymlinks: OutdatedSymlink[];
+}
+
+type PartialClassification = Partial<AgentFileClassification>;
+
+export interface OutdatedSymlink {
+  /** Path to the symlink in the target */
+  symlinkPath: string;
+
+  /** Where it currently points */
+  currentTarget: string;
+
+  /** Where it should point based on current location */
+  expectedTarget: string;
+}
+
+/** Find all agent files in the repository and classify them.
+ * Returns absolute paths in the classification.
+ */
+export async function classifyAgentFiles(
+  targetRoot: string,
+  overlayRoot: string,
+  gitContext?: GitContext,
+): Promise<AgentFileClassification> {
+  const allAgentFiles = await findAllAgentFiles(targetRoot);
+  const mapperCtx: MapperContext | undefined = gitContext
+    ? { overlayRoot, targetRoot, gitContext }
+    : undefined;
+
+  const classifications = await Promise.all(
+    allAgentFiles.map((f) =>
+      classifySingleAgentFile(f, targetRoot, overlayRoot, mapperCtx),
+    ),
+  );
+
+  return mergeClassifications(classifications);
+}
+
+/** @return true if classification has any problems */
+export function agentFileProblems(
+  classification: AgentFileClassification,
+): boolean {
+  return (
+    classification.tracked.length > 0 ||
+    classification.untracked.length > 0 ||
+    classification.staleSymlinks.length > 0 ||
+    classification.outdatedSymlinks.length > 0
+  );
+}
+
+/** Format all agent file problems as a single message.
+ * Paths are formatted relative to cwd for copy-paste convenience.
+ */
+export function formatAgentFileProblems(
+  classified: AgentFileClassification,
+  cwd: string,
+): string {
+  const sections: string[] = [];
+  const rel = (p: string) => relativePath(cwd, p);
+
+  if (classified.tracked.length > 0) {
+    const commands = [
+      ...classified.tracked.map((p) => `  git rm --cached ${rel(p)}`),
+      ...classified.tracked.map((p) => `  clank add ${rel(p)}`),
+    ];
+    sections.push(`Found tracked agent files. Clank manages agent files via symlinks.
+
+To convert to clank management:
+${commands.join("\n")}`);
+  }
+
+  if (classified.untracked.length > 0) {
+    const commands = classified.untracked.map((p) => `  clank add ${rel(p)}`);
+    sections.push(`Found untracked agent files.
+
+Add them to clank:
+${commands.join("\n")}`);
+  }
+
+  if (classified.staleSymlinks.length > 0) {
+    const commands = classified.staleSymlinks.map((p) => `  rm ${rel(p)}`);
+    sections.push(`Found stale agent symlinks (not pointing to clank overlay).
+
+Remove them, then run \`clank link\` to recreate:
+${commands.join("\n")}`);
+  }
+
+  if (classified.outdatedSymlinks.length > 0) {
+    const details = classified.outdatedSymlinks.map((s) => {
+      const symlinkRel = rel(s.symlinkPath);
+      return `  ${symlinkRel}\n    points to: ${s.currentTarget}\n    expected:  ${s.expectedTarget}`;
+    });
+    sections.push(`Found outdated agent symlinks (pointing to wrong overlay path).
+
+This typically happens after a directory rename. Remove symlinks and run \`clank link\`:
+${details.join("\n\n")}
+
+To fix:
+  rm ${classified.outdatedSymlinks.map((s) => rel(s.symlinkPath)).join(" ")}
+  clank link`);
+  }
+
+  return sections.join("\n\n");
+}
+
+/** Classify a single agent file */
+async function classifySingleAgentFile(
+  filePath: string,
+  targetRoot: string,
+  overlayRoot: string,
+  mapperCtx?: MapperContext,
+): Promise<PartialClassification> {
+  const stat = await lstat(filePath);
+
+  if (stat.isSymbolicLink()) {
+    return classifyAgentSymlink(filePath, overlayRoot, mapperCtx);
+  }
+  if (stat.isFile()) {
+    const isTracked = await isTrackedByGit(filePath, targetRoot);
+    return isTracked ? { tracked: [filePath] } : { untracked: [filePath] };
+  }
+  return {};
+}
+
+/** Classify an agent symlink - check if stale or outdated */
+async function classifyAgentSymlink(
+  filePath: string,
+  overlayRoot: string,
+  mapperCtx?: MapperContext,
+): Promise<PartialClassification> {
+  const absoluteTarget = await resolveSymlinkTarget(filePath);
+
+  // Symlink doesn't point to overlay at all
+  if (!absoluteTarget.startsWith(overlayRoot)) {
+    return { staleSymlinks: [filePath] };
+  }
+
+  // Check if it points to the correct path within overlay
+  if (mapperCtx) {
+    // Agent files (CLAUDE.md, etc.) map to agents.md in overlay
+    const agentsMdPath = join(dirname(filePath), "agents.md");
+    const expectedTarget = targetToOverlay(agentsMdPath, "project", mapperCtx);
+    if (absoluteTarget !== expectedTarget) {
+      return {
+        outdatedSymlinks: [
+          {
+            symlinkPath: filePath,
+            currentTarget: absoluteTarget,
+            expectedTarget,
+          },
+        ],
+      };
+    }
+  }
+
+  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;
+}