clank-cli 0.1.67 → 0.1.74

package/README.md

@@ -24,6 +24,7 @@ Clank stores your AI agent files (CLAUDE.md, commands, notes) in a separate git
 - **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.
+- **Rules Consolidation**: Use `.claude/rules/` for modular instructions; clank auto-generates AGENTS.md/GEMINI.md with consolidated content for cross-agent compatibility.
 - **Three Scopes**: Global (all projects), Project (all branches), Worktree (this branch only).
 
 ## Installation
@@ -300,6 +301,12 @@ Available placeholders:
 - `{{project_name}}` - Project name from git
 - `{{branch_name}}` - Current branch/worktree name
 
+## Rules Consolidation
+
+If you use Claude Code's `.claude/rules/` for modular instructions, clank automatically generates AGENTS.md and GEMINI.md by consolidating `agents.md` with all your rules. Claude reads rules natively via symlinks; other agents get everything in one file.
+
+Store rules in `claude/rules/` in your overlay, then run `clank link`. Consolidation activates automatically when rules files exist -- when there are no rules, all agent files remain symlinks as before.
+
 ## Design Principles
 
 1. **Everything is linked, nothing is copied** - Single source of truth in overlay
@@ -336,7 +343,8 @@ Available placeholders:
         ├── claude/           # Claude Code specific
         │   ├── settings.json # -> .claude/settings.json
         │   ├── commands/     # -> .claude/commands/
-        │   └── agents/       # -> .claude/agents/
+        │   ├── agents/       # -> .claude/agents/
+        │   └── rules/        # -> .claude/rules/ (also consolidated into AGENTS.md/GEMINI.md)
         ├── gemini/           # Gemini specific
         │   └── commands/     # -> .gemini/commands/
         └── worktrees/

package/package.json

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

package/src/AgentFiles.ts

@@ -1,7 +1,7 @@
 import { join } from "node:path";
 
 /** Base agent directory names (without leading dot) */
-export const agentDirNames = ["claude", "gemini"];
+export const agentDirNames = ["claude", "gemini", "codex"];
 
 /** Agent directories as they appear in target (with leading dot) */
 export const managedAgentDirs = agentDirNames.map((d) => `.${d}`);

package/src/ClassifyFiles.ts

@@ -1,10 +1,12 @@
 import { lstat } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { agentFiles } from "./AgentFiles.ts";
+import { isGeneratedByClank } from "./Consolidate.ts";
 import {
   isTrackedByGit,
   relativePath,
   resolveSymlinkTarget,
+  toSlash,
   walkDirectory,
 } from "./FsUtil.ts";
 import type { GitContext } from "./Git.ts";
@@ -90,11 +92,14 @@ ${commands.join("\n")}`);
   }
 
   if (classified.untracked.length > 0) {
-    const commands = classified.untracked.map((p) => `  clank add ${rel(p)}`);
+    const files = classified.untracked.map((p) => `  ${rel(p)}`);
     sections.push(`Found untracked agent files.
 
 Add them to clank:
-${commands.join("\n")}`);
+${files.join("\n")}
+
+  clank add -i                  # add interactively
+  clank add <file> [<file>...]  # add specific files`);
   }
 
   if (classified.staleSymlinks.length > 0) {
@@ -153,6 +158,7 @@ async function classifySingleAgentFile(
     return classifyAgentSymlink(filePath, overlayRoot, mapperCtx);
   }
   if (stat.isFile()) {
+    if (await isGeneratedByClank(filePath)) return {};
     const isTracked = await isTrackedByGit(filePath, targetRoot);
     return isTracked ? { tracked: [filePath] } : { untracked: [filePath] };
   }
@@ -180,7 +186,7 @@ async function classifyAgentSymlink(
   const absoluteTarget = await resolveSymlinkTarget(filePath);
 
   // Symlink doesn't point to overlay at all
-  if (!absoluteTarget.startsWith(overlayRoot)) {
+  if (!toSlash(absoluteTarget).startsWith(toSlash(overlayRoot))) {
     return { staleSymlinks: [filePath] };
   }
 

package/src/Cli.ts

@@ -36,6 +36,8 @@ Clank Overlay Directory Structure
         │   ├── settings.json    # -> .claude/settings.json
         │   ├── commands/        # -> .claude/commands/
         │   └── agents/          # -> .claude/agents/
+        ├── codex/               # Codex specific
+        │   └── config.toml      # -> .codex/config.toml
         ├── <subdir>/clank/      # Subdirectory files (monorepo support)
         │   └── notes.md         # -> <subdir>/clank/notes.md
         └── worktrees/
@@ -51,6 +53,7 @@ Mapping Rules
   global/claude/commands/<file>       -> .claude/commands/<file>
   targets/<proj>/clank/<file>         -> clank/<file>
   targets/<proj>/claude/commands/     -> .claude/commands/
+  targets/<proj>/codex/config.toml    -> .codex/config.toml
   targets/<proj>/agents.md            -> CLAUDE.md, AGENTS.md, GEMINI.md
   targets/<proj>/<sub>/clank/<file>   -> <sub>/clank/<file>
   targets/<proj>/worktrees/<br>/clank -> clank/
@@ -84,31 +87,9 @@ export async function runCLI(): Promise<void> {
 }
 
 function registerCommands(program: Command): void {
-  registerCoreCommands(program);
-  registerHelpCommands(program);
-}
-
-function registerCoreCommands(program: Command): void {
   registerOverlayCommands(program);
   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));
+  registerHelpCommands(program);
 }
 
 function registerOverlayCommands(program: Command): void {
@@ -163,6 +144,7 @@ function registerUtilityCommands(program: Command): void {
     .command("check")
     .alias("status")
     .description("Show overlay status and check for issues")
+    .option("--prompt", "Print the agent fix prompt for orphaned paths")
     .action(withErrorHandling(checkCommand));
 
   registerFilesCommand(program);
@@ -175,6 +157,24 @@ function registerUtilityCommands(program: Command): void {
     .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) 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 withErrorHandling<T extends unknown[]>(
   fn: (...args: T) => Promise<void>,
 ): (...args: T) => Promise<void> {

package/src/Consolidate.ts

@@ -0,0 +1,250 @@
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { agentFiles, forEachAgentPath } from "./AgentFiles.ts";
+import { fileExists, isSymlink, walkDirectory } from "./FsUtil.ts";
+import type { GitContext } from "./Git.ts";
+import { overlayProjectDir, overlayWorktreeDir } from "./Mapper.ts";
+
+/** Params for the consolidation entry point */
+export interface ConsolidateParams {
+  overlayRoot: string;
+  targetRoot: string;
+  gitContext: GitContext;
+  agents: string[];
+}
+
+/** A rules file with its parsed metadata and content */
+interface RuleFile {
+  filename: string;
+  content: string;
+  description?: string;
+  paths?: string;
+}
+
+/** First-line marker for generated agent files */
+export const generatedMarker = "<!-- Generated by clank";
+
+/**
+ * Consolidate agents.md + .claude/rules/ into generated AGENTS.md/GEMINI.md.
+ *
+ * Only runs when rules files exist in the overlay. Root-level only --
+ * subdirectory agents.md files continue as pure symlinks.
+ */
+export async function consolidateRulesIntoAgentFiles(
+  params: ConsolidateParams,
+): Promise<string[]> {
+  const { overlayRoot, targetRoot, gitContext, agents } = params;
+
+  // Collect rules from all applicable overlay scopes
+  const rulesFiles = await collectRulesFiles(overlayRoot, gitContext);
+  if (rulesFiles.length === 0) return [];
+
+  // Read root-level agents.md from overlay (if exists)
+  const agentsMdContent = await readRootAgentsMd(overlayRoot, gitContext);
+
+  // Build the consolidated content
+  const overlayPaths = getOverlayPaths(overlayRoot, gitContext);
+  const merged = buildConsolidatedContent(
+    agentsMdContent,
+    rulesFiles,
+    overlayPaths,
+  );
+
+  // For each non-claude agent, replace the symlink with a generated file
+  const generated: string[] = [];
+  await forEachAgentPath(targetRoot, agents, async (agentPath, agentName) => {
+    if (agentName.toLowerCase() === "claude") return;
+    // Remove existing symlink if present
+    if (await isSymlink(agentPath)) {
+      await unlink(agentPath);
+    }
+    await writeFile(agentPath, merged, "utf-8");
+    generated.push(basename(agentPath));
+  });
+
+  return generated;
+}
+
+/** Check if a file is generated by clank (first line starts with marker) */
+export async function isGeneratedByClank(filePath: string): Promise<boolean> {
+  if (!(await fileExists(filePath))) return false;
+  if (await isSymlink(filePath)) return false;
+  try {
+    const content = await readFile(filePath, "utf-8");
+    return content.startsWith(generatedMarker);
+  } catch {
+    return false;
+  }
+}
+
+/** Strip YAML frontmatter and extract description/paths */
+export function stripFrontmatter(raw: string): {
+  content: string;
+  description?: string;
+  paths?: string;
+} {
+  const fence = "---";
+  const fenceNewline = `\n${fence}`;
+
+  if (!raw.startsWith(fence)) {
+    return { content: raw };
+  }
+
+  const endIndex = raw.indexOf(fenceNewline, fence.length);
+  if (endIndex === -1) {
+    return { content: raw };
+  }
+
+  const frontmatter = raw.slice(fence.length, endIndex).trim();
+  const content = raw.slice(endIndex + fenceNewline.length).replace(/^\n+/, "");
+
+  let description: string | undefined;
+  let paths: string | undefined;
+
+  for (const line of frontmatter.split("\n")) {
+    const descMatch = line.match(/^description:\s*(.+)/);
+    if (descMatch) {
+      description = descMatch[1].trim().replace(/^["']|["']$/g, "");
+    }
+    const pathsMatch = line.match(/^paths:\s*(.+)/);
+    if (pathsMatch) {
+      // paths can be inline array: ["src/**/*.ts"] or plain string
+      paths = pathsMatch[1]
+        .trim()
+        .replace(/^\[|\]$/g, "")
+        .replace(/["']/g, "");
+    }
+  }
+
+  return { content, description, paths };
+}
+
+/** Convert a filename to a human-readable heading */
+export function humanizeFilename(filename: string): string {
+  return filename.replace(/\.md$/, "").replace(/[-_]/g, " ");
+}
+
+/** Remove generated agent files from target (for unlink) */
+export async function removeGeneratedAgentFiles(
+  targetRoot: string,
+): Promise<string[]> {
+  const removed: string[] = [];
+  for (const name of agentFiles) {
+    const path = join(targetRoot, name);
+    if (await isGeneratedByClank(path)) {
+      await unlink(path);
+      removed.push(name);
+    }
+  }
+  return removed;
+}
+
+/** Collect all .md files from claude/rules/ across overlay scopes */
+async function collectRulesFiles(
+  overlayRoot: string,
+  gitContext: GitContext,
+): Promise<RuleFile[]> {
+  const dirs = [
+    join(overlayRoot, "global/claude/rules"),
+    join(
+      overlayProjectDir(overlayRoot, gitContext.projectName),
+      "claude/rules",
+    ),
+    join(overlayWorktreeDir(overlayRoot, gitContext), "claude/rules"),
+  ];
+
+  const allFiles: RuleFile[] = [];
+  for (const dir of dirs) {
+    if (!(await fileExists(dir))) continue;
+    for await (const { path, isDirectory } of walkDirectory(dir)) {
+      if (isDirectory) continue;
+      if (!path.endsWith(".md")) continue;
+      const raw = await readFile(path, "utf-8");
+      const parsed = stripFrontmatter(raw);
+      allFiles.push({
+        filename: basename(path),
+        ...parsed,
+      });
+    }
+  }
+
+  // Sort alphabetically by filename for deterministic output
+  allFiles.sort((a, b) => a.filename.localeCompare(b.filename));
+  return allFiles;
+}
+
+/** Read root-level agents.md from the overlay (project scope, then global) */
+async function readRootAgentsMd(
+  overlayRoot: string,
+  gitContext: GitContext,
+): Promise<string | null> {
+  const projectPath = join(
+    overlayProjectDir(overlayRoot, gitContext.projectName),
+    "agents.md",
+  );
+  if (await fileExists(projectPath)) {
+    return readFile(projectPath, "utf-8");
+  }
+
+  // Fall back to global agents.md
+  const globalPath = join(overlayRoot, "global/agents.md");
+  if (await fileExists(globalPath)) {
+    return readFile(globalPath, "utf-8");
+  }
+
+  return null;
+}
+
+/** Get overlay paths for the header comments */
+function getOverlayPaths(
+  overlayRoot: string,
+  gitContext: GitContext,
+): { agentsMdPath: string; rulesDir: string } {
+  const projectDir = overlayProjectDir(overlayRoot, gitContext.projectName);
+  return {
+    agentsMdPath: join(projectDir, "agents.md"),
+    rulesDir: join(projectDir, "claude/rules"),
+  };
+}
+
+/** Build the consolidated markdown content */
+function buildConsolidatedContent(
+  agentsMdContent: string | null,
+  rules: RuleFile[],
+  overlayPaths: { agentsMdPath: string; rulesDir: string },
+): string {
+  const lines: string[] = [];
+
+  // Header comments
+  lines.push(`${generatedMarker} - do not edit -->`);
+  if (agentsMdContent) {
+    lines.push(`<!-- Source: ${overlayPaths.agentsMdPath} -->`);
+  }
+  lines.push(`<!-- Rules: ${overlayPaths.rulesDir} -->`);
+  lines.push("");
+
+  // Base agents.md content
+  if (agentsMdContent) {
+    lines.push(agentsMdContent.trimEnd());
+  }
+
+  // Append each rule as a section
+  for (const rule of rules) {
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+
+    const heading = rule.description || humanizeFilename(rule.filename);
+    lines.push(`## ${heading}`);
+
+    if (rule.paths) {
+      lines.push(`Applies to: ${rule.paths}`);
+    }
+
+    lines.push("");
+    lines.push(rule.content.trimEnd());
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}

package/src/FsUtil.ts

@@ -5,6 +5,7 @@ import {
   readdir,
   readFile,
   readlink,
+  realpath,
   symlink,
   unlink,
   writeFile,
@@ -28,6 +29,27 @@ interface WalkContext {
   skip?: (relPath: string, isDirectory: boolean) => boolean;
 }
 
+/** Normalize path separators to forward slashes (for cross-platform string comparisons) */
+export function toSlash(p: string): string {
+  return p.replaceAll("\\", "/");
+}
+
+/** Resolve Windows 8.3 short names to canonical long paths.
+ *  On non-Windows, returns the path unchanged. */
+export async function resolveWindowsPath(p: string): Promise<string> {
+  if (process.platform !== "win32") return p;
+  try {
+    return await realpath(p);
+  } catch {
+    return p;
+  }
+}
+
+/** Get the current working directory, resolving Windows 8.3 short names */
+export async function getCwd(): Promise<string> {
+  return resolveWindowsPath(process.cwd());
+}
+
 /**
  * Create a symbolic link, removing existing link/file first
  * @param target - The path the symlink should point to (absolute)
@@ -45,7 +67,24 @@ export async function createSymlink(
     // File doesn't exist, which is fine
   }
 
-  await symlink(target, linkPath);
+  try {
+    await symlink(target, linkPath);
+  } catch (error: unknown) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      error.code === "EPERM" &&
+      process.platform === "win32"
+    ) {
+      throw new Error(
+        `Permission denied creating symlink.\n` +
+          `On Windows, symlinks require Developer Mode or administrator privileges.\n` +
+          `Enable Developer Mode: Settings > Update & Security > For Developers\n` +
+          `Or use clank from WSL.`,
+      );
+    }
+    throw error;
+  }
 }
 
 /** Remove a symlink if it exists */
@@ -62,12 +101,13 @@ export async function removeSymlink(linkPath: string): Promise<void> {
 
 /**
  * Get the symlink target path (absolute)
+ * Uses forward slashes so readlink returns consistent paths across platforms.
  * @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;
+  return toSlash(to);
 }
 
 /** Recursively walk a directory, yielding all files and directories */
@@ -118,7 +158,7 @@ export async function isTrackedByGit(
   repoRoot: string,
 ): Promise<boolean> {
   try {
-    const relPath = relative(repoRoot, filePath);
+    const relPath = toSlash(relative(repoRoot, filePath));
     await execFileAsync("git", ["ls-files", "--error-unmatch", relPath], {
       cwd: repoRoot,
     });
@@ -138,6 +178,16 @@ export async function isSymlink(filePath: string): Promise<boolean> {
   }
 }
 
+/** Check if a path is a real (non-symlink) file tracked by git */
+export async function isTrackedRealFile(
+  filePath: string,
+  repoRoot: string,
+): Promise<boolean> {
+  if (!(await fileExists(filePath))) return false;
+  if (await isSymlink(filePath)) return false;
+  return isTrackedByGit(filePath, repoRoot);
+}
+
 /** Get path relative to cwd, or "." if same directory */
 export function relativePath(cwd: string, path: string): string {
   return relative(cwd, path) || ".";
@@ -195,7 +245,7 @@ function* processEntry(
   | { recurse: string; options: WalkOptions; root: string }
 > {
   const fullPath = join(dir, entry.name);
-  const relPath = relative(ctx.root, fullPath);
+  const relPath = toSlash(relative(ctx.root, fullPath));
 
   if (entry.isDirectory()) {
     if (shouldSkipDir(entry.name, ctx.skipDirs, ctx.includeHidden)) return;

package/src/Git.ts

@@ -1,5 +1,6 @@
 import { basename, isAbsolute, join } from "node:path";
 import { exec } from "./Exec.ts";
+import { resolveWindowsPath } from "./FsUtil.ts";
 
 /** Selected git project/worktree metadata */
 export interface GitContext {
@@ -34,7 +35,9 @@ export async function detectGitRoot(
 ): Promise<string> {
   const toplevel = await gitCommand("rev-parse --show-toplevel", cwd);
   if (toplevel) {
-    return toplevel;
+    // On Windows, git returns forward-slash paths that may use long names
+    // while cwd uses 8.3 short names. Resolve to canonical form.
+    return await resolveWindowsPath(toplevel);
   }
   throw new Error("Not in a git repository");
 }
@@ -89,7 +92,7 @@ export async function isGitWorktree(
   }
 
   // Worktrees have .git/worktrees/* in their git-dir path
-  return gitDir.includes("/worktrees/");
+  return gitDir.replaceAll("\\", "/").includes("/worktrees/");
 }
 
 /** Parse repository name from git remote URL (handles HTTPS and SSH formats) */

package/src/Gitignore.ts

@@ -1,8 +1,9 @@
 import { readFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
+import picomatch from "picomatch";
 import { agentFiles, targetManagedDirs } from "./AgentFiles.ts";
 import { filterClankLines } from "./Exclude.ts";
-import { fileExists, walkDirectory } from "./FsUtil.ts";
+import { fileExists, toSlash, walkDirectory } from "./FsUtil.ts";
 import { getGitDir } from "./Git.ts";
 import { partition } from "./Util.ts";
 
@@ -52,7 +53,7 @@ export async function collectGitignorePatterns(
 
   // 3. Find nested .gitignore files
   for (const path of await findNestedGitignores(targetRoot)) {
-    const basePath = relative(targetRoot, dirname(path));
+    const basePath = toSlash(relative(targetRoot, dirname(path)));
     await parseGitignoreFile(path, result, { basePath });
   }
 
@@ -144,6 +145,23 @@ export function deduplicateGlobs(globs: string[]): string[] {
   return [...universal, ...uncovered];
 }
 
+/** Load a repo's .gitignore and return a matcher for ignored filenames */
+export async function loadGitignore(
+  repoRoot: string,
+): Promise<(name: string) => boolean> {
+  const gitignorePath = join(repoRoot, ".gitignore");
+  if (!(await fileExists(gitignorePath))) return () => false;
+
+  const content = await readFile(gitignorePath, "utf-8");
+  const patterns = content
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#") && !line.startsWith("!"));
+
+  if (patterns.length === 0) return () => false;
+  return picomatch(patterns);
+}
+
 /** Parse a gitignore file and accumulate results */
 async function parseGitignoreFile(
   source: string,