clank-cli 0.1.52 → 0.1.58

package/README.md

@@ -2,16 +2,16 @@
 
 Store AI agent files and notes in a separate git repository. Git-ignored symlinks make the files visible in your projects.
 
+Common commands:
 - **`clank add`** to move files to the overlay.
+- **`clank rm`** to remove files from 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.
+- **`clank check`** to show overlay status and find misaligned files.
 
 ## 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:
+Clank stores your AI agent files (CLAUDE.md, commands, notes) in a separate git repository and 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.
@@ -39,49 +39,27 @@ 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
+clank init                    # Create overlay repository (~/.clankover)
 cd ~/my-project
-clank link
-# Auto-detects project name from git
-# Creates symlinks from overlay to current directory
+clank link                    # Connect project to overlay
+clank add CLAUDE.md           # Add agent file (creates symlinks)
+clank add notes.md --global   # Add global file (shared across projects)
 ```
 
-### 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
+Agent files (CLAUDE.md, AGENTS.md, GEMINI.md) stay in place; other files go in `clank/`. You can run `clank add` from any subdirectory.
 
-# Add to worktree scope - this branch only
-clank add notes.md --worktree
+## Commands
 
-# Add commands
-clank add .claude/commands/review.md --global   # All projects
-clank add .claude/commands/build.md             # This project
+### Scope Options
 
-# Add a directory (all files inside)
-clank add clank/
-```
+Several commands (`add`, `rm`, `mv`) accept scope flags to specify where files are stored:
 
-## Commands
+| Flag | Scope | Shared Across |
+|------|-------|---------------|
+| `--global`, `-g` | Global | All projects |
+| `--project`, `-p` | Project (default) | All branches in project |
+| `--worktree`, `-w` | Worktree | This branch only |
 
 ### `clank init [overlay-path]`
 
@@ -103,16 +81,7 @@ 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 |
+Move a file to the overlay and replace it with a symlink. If the file doesn't exist, an empty file is created. Accepts [scope options](#scope-options).
 
 **Examples:**
 ```bash
@@ -149,7 +118,7 @@ clank commit                        # Commits with "[clank] update"
 clank commit -m "add style guide"   # Commits with "[clank] add style guide"
 ```
 
-### `clank check`
+### `clank check` (alias: `status`)
 
 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.
@@ -168,6 +137,40 @@ clank check
 # The following overlay files no longer match...
 ```
 
+### `clank rm <files...>` (alias: `remove`)
+
+Remove file(s) from both the overlay repository and the local project symlinks. Accepts [scope options](#scope-options); if omitted, clank detects the scope from the symlink.
+
+**Example:**
+```bash
+clank rm clank/notes.md            # Remove from whatever scope it belongs to
+clank rm style.md --global         # Remove global style guide
+```
+
+### `clank mv <files...>` (alias: `move`)
+
+Move file(s) between overlay scopes. Requires one [scope option](#scope-options) to specify the destination.
+
+**Example:**
+```bash
+# Promote a worktree note to project scope
+clank mv clank/notes.md --project
+
+# Share a local command globally
+clank mv .claude/commands/test.md --global
+```
+
+### `clank vscode`
+
+Generate `.vscode/settings.json` to make clank files visible in VS Code's explorer and search, while still respecting your `.gitignore` rules.
+
+Since clank relies on symlinked files that are git-ignored, VS Code often hides them by default. This command explicitly excludes your gitignored files in `settings.json` while un-hiding the clank folders.
+
+**Options:**
+- `--remove` - Remove the clank-generated settings
+
+See [Configuration](#configuration) for `vscodeSettings` and `vscodeGitignore` options.
+
 ### `clank help structure`
 
 Show the overlay directory structure and mapping rules.
@@ -239,10 +242,7 @@ 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.
+Customize `global/init/clank/` in your overlay to create starter notes and planning files for new worktrees. When you run `clank link` in a new worktree, these templates are copied into the worktree's overlay directory.
 
 Available placeholders:
 
@@ -254,9 +254,8 @@ Available placeholders:
 
 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`
+3. **Explicit scopes** - Three levels: global, project, worktree
+4. **Flat target structure** - All notes show up together in `clank/`
 
 ## Reference
 

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "clank-cli",
-  "version": "0.1.52",
   "description": "Keep AI files in a separate overlay repository",
+  "version": "0.1.58",
+  "author": "",
   "type": "module",
   "bin": {
     "clank": "./bin/clank.ts"
@@ -10,21 +11,7 @@
     "bin/",
     "src/"
   ],
-  "engines": {
-    "node": ">=22.6.0"
-  },
-  "keywords": [
-    "ai",
-    "assistant",
-    "claude",
-    "gemini",
-    "copilot",
-    "configuration",
-    "worktree",
-    "git"
-  ],
-  "author": "",
-  "license": "MIT",
+  "repository": "github:mighdoll/clank",
   "dependencies": {
     "commander": "^14.0.2",
     "cosmiconfig": "^9.0.0"
@@ -32,19 +19,38 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.8",
     "@types/node": "^24.10.1",
+    "@typescript/native-preview": "7.0.0-dev.20251221.1",
+    "@vitest/ui": "^4.0.16",
     "execa": "^9.6.1",
     "monobump": "^0.1.5",
-    "typescript": "^5.9.3",
+    "npm-run-all2": "^7.0.2",
+    "syncpack": "^13.0.4",
     "vitest": "^4.0.14"
   },
+  "license": "MIT",
+  "keywords": [
+    "agent",
+    "ai",
+    "assistant",
+    "claude",
+    "configuration",
+    "copilot",
+    "gemini",
+    "git",
+    "worktree"
+  ],
+  "engines": {
+    "node": ">=22.6.0"
+  },
   "scripts": {
-    "test": "vitest",
-    "test:ui": "vitest --ui",
-    "typecheck": "tsc --noEmit",
     "bump": "monobump",
+    "fix": "biome check --fix --unsafe",
+    "fix:pkgJsonFormat": "syncpack format",
     "global": "pnpm link --global",
-    "build": "tsc",
-    "lint": "biome check",
-    "fix": "biome check --fix --unsafe"
+    "lint": "biome check --error-on-warnings",
+    "test": "vitest",
+    "test:once": "vitest run",
+    "test:ui": "vitest --ui",
+    "typecheck": "tsgo"
   }
 }

package/src/ClassifyFiles.ts

@@ -1,7 +1,12 @@
 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 {
+  isTrackedByGit,
+  relativePath,
+  resolveSymlinkTarget,
+  walkDirectory,
+} from "./FsUtil.ts";
 import type { GitContext } from "./Git.ts";
 import { type MapperContext, targetToOverlay } from "./Mapper.ts";
 

package/src/Config.ts

@@ -89,7 +89,9 @@ function getConfigDir(): string {
 }
 
 /** Validate overlay repository exists, throw if not */
-export async function validateOverlayExists(overlayRoot: string): Promise<void> {
+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/FsUtil.ts

@@ -1,4 +1,13 @@
-import { lstat, mkdir, readdir, readFile, readlink, symlink, unlink, writeFile } from "node:fs/promises";
+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";
 

package/src/Gitignore.ts

@@ -169,7 +169,6 @@ async function parseGitignoreFile(
   result.negationWarnings.push(...parsed.negationWarnings);
 }
 
-
 /** Parse a single gitignore line */
 function parseLine(
   trimmed: string,
@@ -195,7 +194,9 @@ function parseGitignoreContent(
   options: ParseOptions,
 ): { patterns: GitignorePattern[]; negationWarnings: string[] } {
   const rawLines = content.split("\n");
-  const lines = options.skipClankSection ? filterClankLines(rawLines) : rawLines;
+  const lines = options.skipClankSection
+    ? filterClankLines(rawLines)
+    : rawLines;
   const basePath = options.basePath ?? "";
 
   const patterns: GitignorePattern[] = [];

package/src/OverlayLinks.ts

@@ -1,8 +1,18 @@
 import { lstat } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import { managedAgentDirs } from "./AgentFiles.ts";
-import { createSymlink, ensureDir, getLinkTarget, resolveSymlinkTarget, walkDirectory } from "./FsUtil.ts";
-import { getPromptRelPath, type MapperContext, overlayToTarget } from "./Mapper.ts";
+import {
+  createSymlink,
+  ensureDir,
+  getLinkTarget,
+  resolveSymlinkTarget,
+  walkDirectory,
+} from "./FsUtil.ts";
+import {
+  getPromptRelPath,
+  type MapperContext,
+  overlayToTarget,
+} from "./Mapper.ts";
 
 export type ManagedFileState =
   | { kind: "valid" }

package/src/commands/Add.ts

@@ -119,25 +119,50 @@ async function addSingleFile(
     const params = { overlayPath, symlinkDir, gitRoot, overlayRoot, agents };
     await createAgentLinks(params);
   } else if (isPromptFile(normalizedPath)) {
-    // Prompt files get symlinks in all agent directories
-    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(", ")}`);
-      }
-    }
+    await handlePromptFile(normalizedPath, overlayPath, gitRoot, cwd);
   } else {
-    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)}`);
+    await handleRegularFile(normalizedPath, overlayPath, overlayRoot, cwd);
+  }
+}
+
+/** Handle prompt file symlink creation */
+async function handlePromptFile(
+  normalizedPath: string,
+  overlayPath: string,
+  gitRoot: string,
+  cwd: string,
+): Promise<void> {
+  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(", ")}`,
+      );
     }
   }
 }
 
+/** 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();

package/src/commands/Link.ts

@@ -6,7 +6,12 @@ import {
   classifyAgentFiles,
   formatAgentFileProblems,
 } from "../ClassifyFiles.ts";
-import { type ClankConfig, expandPath, loadConfig, validateOverlayExists } from "../Config.ts";
+import {
+  type ClankConfig,
+  expandPath,
+  loadConfig,
+  validateOverlayExists,
+} from "../Config.ts";
 import { addGitExcludes } from "../Exclude.ts";
 import {
   createSymlink,

package/src/commands/Move.ts

@@ -167,6 +167,8 @@ async function recreatePromptLinks(
   const created = await createPromptLinks(overlayPath, promptRelPath, gitRoot);
 
   if (created.length > 0) {
-    console.log(`Updated symlinks: ${created.map((p) => relative(gitRoot, p)).join(", ")}`);
+    console.log(
+      `Updated symlinks: ${created.map((p) => relative(gitRoot, p)).join(", ")}`,
+    );
   }
 }