clank-cli 0.1.52

package/src/Git.ts

@@ -0,0 +1,140 @@
+import { basename, isAbsolute, join } from "node:path";
+import { exec } from "./Exec.ts";
+
+/** Selected git project/worktree metadata */
+export interface GitContext {
+  projectName: string;
+  worktreeName: string;
+  isWorktree: boolean;
+  gitRoot: string;
+}
+
+/** @return metadata about the current git project and worktree */
+export async function getGitContext(
+  cwd: string = process.cwd(),
+): Promise<GitContext> {
+  const [projectName, worktreeName, isWorktree, gitRoot] = await Promise.all([
+    detectProjectName(cwd),
+    detectWorktreeName(cwd),
+    isGitWorktree(cwd),
+    detectGitRoot(cwd),
+  ]);
+
+  return {
+    projectName,
+    worktreeName,
+    isWorktree,
+    gitRoot,
+  };
+}
+
+/** Get the git repository root directory */
+export async function detectGitRoot(
+  cwd: string = process.cwd(),
+): Promise<string> {
+  const toplevel = await gitCommand("rev-parse --show-toplevel", cwd);
+  if (toplevel) {
+    return toplevel;
+  }
+  throw new Error("Not in a git repository");
+}
+
+/** Detect project name from git remote or repository directory */
+export async function detectProjectName(
+  cwd: string = process.cwd(),
+): Promise<string> {
+  // Try git remote first (works for clones and worktrees)
+  const remoteUrl = await gitCommand("config --get remote.origin.url", cwd);
+  if (remoteUrl) {
+    const repoName = parseRepoName(remoteUrl);
+    if (repoName) {
+      return repoName;
+    }
+  }
+
+  // Fall back to git toplevel directory name
+  const toplevel = await gitCommand("rev-parse --show-toplevel", cwd);
+  if (toplevel) {
+    return basename(toplevel);
+  }
+
+  throw new Error("Not in a git repository");
+}
+
+/** Detect worktree/branch name */
+export async function detectWorktreeName(
+  cwd: string = process.cwd(),
+): Promise<string> {
+  const branch = await gitCommand("branch --show-current", cwd);
+  if (branch) {
+    return branch;
+  }
+
+  // Fallback: detached HEAD or other edge case
+  const rev = await gitCommand("rev-parse --short HEAD", cwd);
+  if (rev) {
+    return `detached-${rev}`;
+  }
+
+  throw new Error("Could not determine branch/worktree name");
+}
+
+/** Check if current directory is a git worktree (not the main repository) */
+export async function isGitWorktree(
+  cwd: string = process.cwd(),
+): Promise<boolean> {
+  const gitDir = await gitCommand("rev-parse --git-dir", cwd);
+  if (!gitDir) {
+    return false;
+  }
+
+  // Worktrees have .git/worktrees/* in their git-dir path
+  return gitDir.includes("/worktrees/");
+}
+
+/** Parse repository name from git remote URL (handles HTTPS and SSH formats) */
+export function parseRepoName(url: string): string | null {
+  // Remove trailing .git
+  const normalizedUrl = url.replace(/\.git$/, "");
+
+  // Handle HTTPS: https://github.com/user/repo
+  const httpsMatch = normalizedUrl.match(
+    /https?:\/\/[^/]+\/(?:[^/]+\/)?([\w-]+)$/,
+  );
+  if (httpsMatch) {
+    return httpsMatch[1];
+  }
+
+  // Handle SSH: git@github.com:user/repo
+  const sshMatch = normalizedUrl.match(/:(?:[^/]+\/)?([\w-]+)$/);
+  if (sshMatch) {
+    return sshMatch[1];
+  }
+
+  // Last resort: take last path component
+  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);
+  if (!gitDir) return null;
+  return isAbsolute(gitDir) ? gitDir : join(cwd, gitDir);
+}
+
+/** Get the common .git directory (shared across worktrees) */
+export async function getGitCommonDir(cwd: string): Promise<string | null> {
+  const gitDir = await gitCommand("rev-parse --git-common-dir", cwd);
+  if (!gitDir) return null;
+  return isAbsolute(gitDir) ? gitDir : join(cwd, gitDir);
+}

package/src/Gitignore.ts

@@ -0,0 +1,226 @@
+import { readFile } from "node:fs/promises";
+import { basename, dirname, join, relative } from "node:path";
+import { agentFiles, targetManagedDirs } from "./AgentFiles.ts";
+import { filterClankLines } from "./Exclude.ts";
+import { fileExists, walkDirectory } from "./FsUtil.ts";
+import { getGitDir } from "./Git.ts";
+import { partition } from "./Util.ts";
+
+/** A parsed gitignore pattern with context */
+export interface GitignorePattern {
+  /** The gitignore pattern (e.g., "node_modules/", "*.log") */
+  pattern: string;
+  /** Directory containing the .gitignore, relative to repo root (empty for root) */
+  basePath: string;
+  /** Whether this is a negation pattern (starts with !) */
+  negation: boolean;
+  /** Path to the source file this pattern came from */
+  source: string;
+}
+
+/** Result of collecting patterns, including warnings */
+export interface CollectResult {
+  /** All collected gitignore patterns */
+  patterns: GitignorePattern[];
+  /** Negation patterns that were skipped (can't be represented in VS Code) */
+  negationWarnings: string[];
+}
+
+/** Options for parsing a gitignore file */
+interface ParseOptions {
+  /** Directory containing the .gitignore, relative to repo root (default: "") */
+  basePath?: string;
+  /** Whether to skip the clank-managed section in .git/info/exclude */
+  skipClankSection?: boolean;
+}
+
+/** Collect all gitignore patterns from a repository */
+export async function collectGitignorePatterns(
+  targetRoot: string,
+): Promise<CollectResult> {
+  const result: CollectResult = { patterns: [], negationWarnings: [] };
+
+  // 1. Read .git/info/exclude
+  const gitDir = await getGitDir(targetRoot);
+  if (gitDir) {
+    const excludePath = join(gitDir, "info/exclude");
+    await parseGitignoreFile(excludePath, result, { skipClankSection: true });
+  }
+
+  // 2. Read root .gitignore
+  await parseGitignoreFile(join(targetRoot, ".gitignore"), result);
+
+  // 3. Find nested .gitignore files
+  for (const path of await findNestedGitignores(targetRoot)) {
+    const basePath = relative(targetRoot, dirname(path));
+    await parseGitignoreFile(path, result, { basePath });
+  }
+
+  return result;
+}
+
+/** Convert a gitignore pattern to VS Code glob format */
+export function gitignoreToVscodeGlob(pattern: GitignorePattern): string {
+  let glob = pattern.pattern;
+
+  // Handle trailing slash (directory only) - strip it
+  if (glob.endsWith("/")) {
+    glob = glob.slice(0, -1);
+  }
+
+  // Handle leading slash (anchored to base directory)
+  if (glob.startsWith("/")) {
+    glob = glob.slice(1);
+    // If in subdirectory, prefix with basePath
+    if (pattern.basePath) {
+      glob = `${pattern.basePath}/${glob}`;
+    }
+    // Anchored patterns don't need ** prefix
+    return glob;
+  }
+
+  // Unanchored patterns in subdirectories
+  if (pattern.basePath) {
+    // Pattern can match anywhere under basePath
+    return `${pattern.basePath}/**/${glob}`;
+  }
+
+  // Unanchored patterns at root - can match anywhere
+  if (!glob.startsWith("**/") && !glob.includes("/")) {
+    glob = `**/${glob}`;
+  }
+
+  return glob;
+}
+
+/** Check if a pattern matches clank-managed files */
+export function isClankPattern(glob: string): boolean {
+  // Normalize: remove leading **/ and trailing /
+  const normalized = glob.replace(/^\*\*\//, "").replace(/\/$/, "");
+
+  // Check against managed directories
+  for (const dir of targetManagedDirs) {
+    if (
+      normalized === dir ||
+      normalized.startsWith(`${dir}/`) ||
+      normalized.endsWith(`/${dir}`)
+    ) {
+      return true;
+    }
+  }
+
+  // Check against agent files
+  for (const agentFile of agentFiles) {
+    if (normalized === agentFile || normalized.endsWith(`/${agentFile}`)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/** Convert collected patterns to VS Code exclude globs, filtering clank patterns */
+export function patternsToVscodeExcludes(
+  patterns: GitignorePattern[],
+): string[] {
+  const globs = patterns
+    .filter((p) => !p.negation)
+    .map(gitignoreToVscodeGlob)
+    .filter((glob) => !isClankPattern(glob));
+
+  return deduplicateGlobs([...new Set(globs)]);
+}
+
+/**
+ * Remove globs that are already covered by broader patterns.
+ * e.g., if `** /node_modules` exists, remove `tools/** /node_modules`
+ */
+export function deduplicateGlobs(globs: string[]): string[] {
+  // Partition into universal (**/) and specific patterns
+  const [universal, specific] = partition(globs, (g) => g.startsWith("**/"));
+
+  // Get suffixes that universal patterns cover (without **/ prefix)
+  const coveredSuffixes = new Set(universal.map((g) => g.slice(3)));
+
+  // Keep specific patterns not covered by a universal pattern
+  const uncovered = specific.filter((glob) => {
+    for (const suffix of coveredSuffixes) {
+      if (glob.endsWith(`/**/${suffix}`) || glob.endsWith(`/${suffix}`)) {
+        return false;
+      }
+    }
+    return true;
+  });
+
+  return [...universal, ...uncovered];
+}
+
+/** Parse a gitignore file and accumulate results */
+async function parseGitignoreFile(
+  source: string,
+  result: CollectResult,
+  options: ParseOptions = {},
+): Promise<void> {
+  if (!(await fileExists(source))) return;
+
+  const content = await readFile(source, "utf-8");
+  const parsed = parseGitignoreContent(content, source, options);
+  result.patterns.push(...parsed.patterns);
+  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;
+
+  if (isNegation) {
+    return { negation: pattern };
+  }
+  return { pattern: { pattern, basePath, negation: false, source } };
+}
+
+/** Parse gitignore file content into patterns */
+function parseGitignoreContent(
+  content: string,
+  source: string,
+  options: ParseOptions,
+): { patterns: GitignorePattern[]; negationWarnings: string[] } {
+  const rawLines = content.split("\n");
+  const lines = options.skipClankSection ? filterClankLines(rawLines) : rawLines;
+  const basePath = options.basePath ?? "";
+
+  const patterns: GitignorePattern[] = [];
+  const negationWarnings: string[] = [];
+
+  for (const line of lines) {
+    const { pattern, negation } = parseLine(line.trim(), source, basePath);
+    if (pattern) patterns.push(pattern);
+    if (negation) negationWarnings.push(negation);
+  }
+
+  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");
+
+  for await (const { path, isDirectory } of walkDirectory(targetRoot)) {
+    if (isDirectory) continue;
+    if (basename(path) === ".gitignore" && path !== rootGitignore) {
+      gitignores.push(path);
+    }
+  }
+
+  return gitignores;
+}

package/src/Mapper.ts

@@ -0,0 +1,330 @@
+import { basename, dirname, join, relative } from "node:path";
+import { managedAgentDirs } from "./AgentFiles.ts";
+import type { GitContext } from "./Git.ts";
+
+/** overlay mappings can be cross project, per project, or per worktree */
+export type Scope = "global" | "project" | "worktree";
+
+/** CLI options for scope selection */
+export interface ScopeOptions {
+  global?: boolean;
+  project?: boolean;
+  worktree?: boolean;
+}
+
+/** Resolve scope from CLI options
+ * @param options - The CLI options
+ * @param defaultScope - Default scope if none specified, or "require" to throw
+ */
+export function resolveScopeFromOptions(
+  options: ScopeOptions,
+  defaultScope: Scope | "require" = "project",
+): Scope {
+  if (options.global) return "global";
+  if (options.project) return "project";
+  if (options.worktree) return "worktree";
+
+  if (defaultScope === "require") {
+    throw new Error(
+      "Must specify target scope: --global, --project, or --worktree",
+    );
+  }
+  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,
+  projectName: string,
+): string {
+  return join(overlayRoot, "targets", projectName);
+}
+
+/** Get overlay path for a worktree: overlay/targets/{project}/worktrees/{branch} */
+export function overlayWorktreeDir(
+  overlayRoot: string,
+  gitContext: GitContext,
+): string {
+  const { projectName, worktreeName } = gitContext;
+  return join(overlayRoot, "targets", projectName, "worktrees", worktreeName);
+}
+
+/**
+ * Map overlay path to target path
+ *
+ * Structure:
+ * - overlay/global/clank/ ==> target/clank/
+ * - overlay/global/claude/commands/ ==> target/.claude/commands/
+ * - overlay/global/claude/agents/ ==> target/.claude/agents/
+ * - overlay/targets/{project}/clank/ ==> target/clank/
+ * - overlay/targets/{project}/claude/settings.json ==> target/.claude/settings.json
+ * - overlay/targets/{project}/claude/commands/ ==> target/.claude/commands/
+ * - overlay/targets/{project}/claude/agents/ ==> target/.claude/agents/
+ * - overlay/targets/{project}/agents.md ==> target/agents.md (etc.)
+ * - overlay/targets/{project}/worktrees/{branch}/clank/ ==> target/clank/
+ * - overlay/targets/{project}/worktrees/{branch}/claude/commands/ ==> target/.claude/commands/
+ * - overlay/targets/{project}/worktrees/{branch}/agents.md ==> target/agents.md
+ */
+export function overlayToTarget(
+  overlayPath: string,
+  context: MapperContext,
+): TargetMapping | null {
+  const { overlayRoot, targetRoot, gitContext } = context;
+  const projectPrefix = join(overlayRoot, "targets", gitContext.projectName);
+  const globalPrefix = join(overlayRoot, "global");
+
+  if (overlayPath.startsWith(globalPrefix)) {
+    return mapGlobalOverlay(overlayPath, globalPrefix, targetRoot);
+  }
+
+  if (overlayPath.startsWith(projectPrefix)) {
+    return mapProjectOverlay(overlayPath, projectPrefix, context);
+  }
+
+  return null;
+}
+
+/**
+ * Map target path to overlay path (for clank add command)
+ *
+ * Files go to overlay based on scope:
+ * - --global: overlay/global/clank/
+ * - --project: overlay/targets/{project}/clank/
+ * - --worktree: overlay/targets/{project}/worktrees/{branch}/clank/
+ *
+ * .claude/ files:
+ * - --global: overlay/global/claude/{commands,agents}/
+ * - --project: overlay/targets/{project}/claude/{commands,agents}/
+ * - --worktree: overlay/targets/{project}/worktrees/{branch}/claude/{commands,agents}/
+ *
+ * agents.md files stay at their natural path in the overlay
+ */
+export function targetToOverlay(
+  targetPath: string,
+  scope: Scope,
+  context: MapperContext,
+): string {
+  const { overlayRoot, targetRoot, gitContext } = context;
+  const relPath = relative(targetRoot, targetPath);
+
+  let overlayBase: string;
+  if (scope === "global") {
+    overlayBase = join(overlayRoot, "global");
+  } else if (scope === "worktree") {
+    overlayBase = overlayWorktreeDir(overlayRoot, gitContext);
+  } else {
+    overlayBase = overlayProjectDir(overlayRoot, gitContext.projectName);
+  }
+
+  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 (relPath.includes("clank/")) {
+    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)
+ *
+ * @param input - The file path provided by the user
+ * @param cwd - The current working directory
+ * @param gitRoot - The git repository root
+ */
+export function normalizeAddPath(
+  input: string,
+  cwd: string,
+  gitRoot: string,
+): string {
+  const normalized = input.replace(/^\.\//, "");
+
+  // Treat agent files (CLAUDE.md, GEMINI.md) as aliases for agents.md
+  // Support both relative paths (packages/foo/CLAUDE.md) and running from subdirectory
+  if (isAgentFile(normalized)) {
+    const inputDir = dirname(normalized);
+    const targetDir = inputDir === "." ? cwd : join(cwd, inputDir);
+    return join(targetDir, "agents.md");
+  }
+
+  // .claude/ and .gemini/ files keep their path (relative to git root)
+  for (const agentDir of managedAgentDirs) {
+    if (normalized.startsWith(`${agentDir}/`)) {
+      return join(gitRoot, normalized);
+    }
+  }
+
+  // If path already contains /clank/ in the middle, preserve its structure
+  if (normalized.includes("/clank/")) {
+    return join(cwd, normalized);
+  }
+
+  // Strip clank/ prefix if present at start
+  const filename = normalized.startsWith("clank/")
+    ? normalized.slice("clank/".length)
+    : normalized;
+
+  // Strip trailing /clank from cwd to avoid clank/clank nesting
+  // But don't strip if we're at the git root (project might be named "clank")
+  const inClankSubdir = cwd.endsWith("/clank") && cwd !== gitRoot;
+  const normalizedCwd = inClankSubdir ? cwd.slice(0, -"/clank".length) : cwd;
+
+  return join(normalizedCwd, "clank", filename);
+}
+
+/** Check if a filename is an agent file (CLAUDE.md, GEMINI.md, AGENTS.md) */
+export function isAgentFile(filename: string): boolean {
+  const name = basename(filename).toLowerCase();
+  return name === "claude.md" || name === "gemini.md" || name === "agents.md";
+}
+
+/** Check if a path is a prompt file in an agent's prompts directory */
+export function isPromptFile(normalizedPath: string): boolean {
+  for (const agentDir of managedAgentDirs) {
+    if (normalizedPath.includes(`/${agentDir}/prompts/`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Extract the prompt-relative path from a full prompt path */
+export function getPromptRelPath(normalizedPath: string): string | null {
+  for (const agentDir of managedAgentDirs) {
+    const marker = `/${agentDir}/prompts/`;
+    const idx = normalizedPath.indexOf(marker);
+    if (idx !== -1) {
+      return normalizedPath.slice(idx + marker.length);
+    }
+  }
+  return null;
+}
+
+/**
+ * Add scope suffix to filename for conflict resolution
+ * e.g., "notes.md" + "project" => "notes-project.md"
+ */
+export function addScopeSuffix(filename: string, scope: Scope): string {
+  if (scope === "global") return filename;
+  const dotIndex = filename.lastIndexOf(".");
+  const base = dotIndex === -1 ? filename : filename.slice(0, dotIndex);
+  const ext = dotIndex === -1 ? "" : filename.slice(dotIndex);
+  return `${base}-${scope}${ext}`;
+}
+
+/** Map global overlay files to target */
+function mapGlobalOverlay(
+  overlayPath: string,
+  globalPrefix: string,
+  targetRoot: string,
+): TargetMapping | null {
+  const relPath = relative(globalPrefix, overlayPath);
+
+  // Skip init templates
+  if (relPath.startsWith("init/")) return null;
+
+  return decodeOverlayPath(relPath, targetRoot, "global");
+}
+
+/** Decode an overlay-relative path to target (shared by all scopes) */
+function decodeOverlayPath(
+  relPath: string,
+  targetRoot: string,
+  scope: Scope,
+): TargetMapping | null {
+  // clank/ files (at root or in subdirectories)
+  if (relPath.startsWith("clank/") || relPath.includes("/clank/")) {
+    return { targetPath: join(targetRoot, relPath), scope };
+  }
+
+  // prompts/ files → map to .claude/prompts/ (primary target, multiplexed in Link.ts)
+  if (relPath.startsWith("prompts/")) {
+    const promptRelPath = relPath.slice("prompts/".length);
+    return {
+      targetPath: join(targetRoot, ".claude/prompts", promptRelPath),
+      scope,
+    };
+  }
+
+  // claude/, gemini/ files → map to .claude/, .gemini/ in target
+  for (const agentDir of managedAgentDirs) {
+    const overlayDir = agentDir.slice(1); // "claude" or "gemini"
+    if (relPath.startsWith(`${overlayDir}/`)) {
+      const subPath = relPath.slice(overlayDir.length + 1);
+      return { targetPath: join(targetRoot, agentDir, subPath), scope };
+    }
+  }
+
+  // Agent files (agents.md at any level)
+  if (basename(relPath) === "agents.md") {
+    return { targetPath: join(targetRoot, relPath), scope };
+  }
+
+  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");
+}