clank-cli 0.1.52

package/src/OverlayGit.ts

@@ -0,0 +1,78 @@
+import { execa } from "execa";
+import { managedDirs } from "./AgentFiles.ts";
+
+/** Get git status of the overlay repository */
+export async function getOverlayStatus(
+  overlayRoot: string,
+): Promise<{ lines: string[]; raw: string }> {
+  const { stdout } = await execa({
+    cwd: overlayRoot,
+  })`git status --porcelain -uall`;
+
+  const lines = stdout.trimEnd() ? stdout.trimEnd().split("\n") : [];
+  return { lines, raw: stdout };
+}
+
+/** Format git status --porcelain output into readable lines */
+export function formatStatusLines(lines: string[]): string[] {
+  return lines.map((line) => {
+    const statusCode = formatStatusCode(line.slice(0, 2));
+    const filePath = line.slice(3);
+    const { scope, pathParts } = parseScopedPath(filePath);
+    const displayPath = shortPath(pathParts);
+    return `${statusCode} ${displayPath} (${scope})`;
+  });
+}
+
+/** Format git status code to single letter */
+export function formatStatusCode(code: string): string {
+  const c = code.trim();
+  if (c === "??") return "A";
+  if (c.includes("D")) return "D";
+  if (c.includes("M")) return "M";
+  if (c.includes("A")) return "A";
+  if (c.includes("R")) return "R";
+  return "?";
+}
+
+/** Parse overlay path into scope and path parts within that scope */
+function parseScopedPath(filePath: string): {
+  scope: string;
+  pathParts: string[];
+} {
+  const segments = filePath.split("/");
+  if (segments[0] === "global") {
+    return { scope: "global", pathParts: segments.slice(1) };
+  }
+  if (segments[0] === "targets") {
+    const project = segments[1];
+    if (segments[2] === "worktrees") {
+      // worktrees/<branch>/ - branch is max 2 segments (main, feat/foo)
+      const afterWorktrees = segments.slice(3);
+      const branchSegments = Math.min(
+        2,
+        Math.max(0, afterWorktrees.length - 1),
+      );
+      const branch = afterWorktrees.slice(0, branchSegments).join("/");
+      return {
+        scope: `${project}/${branch}`,
+        pathParts: afterWorktrees.slice(branchSegments),
+      };
+    }
+    return { scope: project || "unknown", pathParts: segments.slice(2) };
+  }
+  return { scope: "unknown", pathParts: segments };
+}
+
+/** Shorten path parts to last 2-3 meaningful segments for display */
+function shortPath(pathParts: string[]): string {
+  if (pathParts.length <= 2) return pathParts.join("/");
+
+  // If file is in a managed dir, show 3 segments (parent/clank/file)
+  const parentDir = pathParts[pathParts.length - 2];
+  if (managedDirs.includes(parentDir)) {
+    return pathParts.slice(-3).join("/");
+  }
+  // Otherwise show 2 segments (parent/file)
+  return pathParts.slice(-2).join("/");
+}

package/src/OverlayLinks.ts

@@ -0,0 +1,125 @@
+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";
+
+export type ManagedFileState =
+  | { kind: "valid" }
+  | { kind: "unadded" }
+  | { kind: "outside-overlay"; currentTarget: string }
+  | {
+      kind: "wrong-mapping";
+      currentTarget: string;
+      expectedTarget: string;
+    };
+
+/** Check if a file in a managed directory is a valid symlink to the overlay.
+ *  Returns null if valid, or an issue object if not. */
+export async function verifyManaged(
+  linkPath: string,
+  context: MapperContext,
+): Promise<ManagedFileState> {
+  const { overlayRoot } = context;
+
+  try {
+    const stats = await lstat(linkPath);
+    if (!stats.isSymbolicLink()) {
+      return { kind: "unadded" };
+    }
+
+    const absoluteTarget = await resolveSymlinkTarget(linkPath);
+
+    // Check if symlink points to overlay at all
+    if (!absoluteTarget.startsWith(overlayRoot)) {
+      return { kind: "outside-overlay", currentTarget: absoluteTarget };
+    }
+
+    // Check if symlink points to correct overlay location
+    const mapping = overlayToTarget(absoluteTarget, context);
+    if (!mapping) {
+      return {
+        kind: "wrong-mapping",
+        currentTarget: absoluteTarget,
+        expectedTarget: "(no valid mapping)",
+      };
+    }
+
+    // Prompt files are fanned out to all agent directories (.claude/prompts/, .gemini/prompts/)
+    // Accept any agent's prompts dir as valid if the filename matches
+    if (mapping.targetPath !== linkPath) {
+      if (!isMatchingPromptPath(mapping.targetPath, linkPath)) {
+        return {
+          kind: "wrong-mapping",
+          currentTarget: absoluteTarget,
+          expectedTarget: mapping.targetPath,
+        };
+      }
+    }
+
+    return { kind: "valid" };
+  } catch {
+    return { kind: "unadded" };
+  }
+}
+
+/** Check if two paths are equivalent prompt files in different agent directories */
+function isMatchingPromptPath(
+  canonicalPath: string,
+  actualPath: string,
+): boolean {
+  const canonicalPrompt = getPromptRelPath(canonicalPath);
+  const actualPrompt = getPromptRelPath(actualPath);
+  return canonicalPrompt !== null && canonicalPrompt === actualPrompt;
+}
+
+/** Check if a path is a symlink pointing to the overlay repository */
+export async function isSymlinkToOverlay(
+  linkPath: string,
+  overlayRoot: string,
+): Promise<boolean> {
+  try {
+    const stats = await lstat(linkPath);
+    if (!stats.isSymbolicLink()) {
+      return false;
+    }
+
+    const absoluteTarget = await resolveSymlinkTarget(linkPath);
+    return absoluteTarget.startsWith(overlayRoot);
+  } catch {
+    return false;
+  }
+}
+
+/** Walk overlay directory and yield all files that should be linked (excludes init/ templates) */
+export async function* walkOverlayFiles(
+  overlayRoot: string,
+): AsyncGenerator<string> {
+  for await (const { path, isDirectory } of walkDirectory(overlayRoot, {
+    skipDirs: [".git", "node_modules"],
+  })) {
+    if (isDirectory) continue;
+
+    const relPath = relative(overlayRoot, path);
+    if (relPath.startsWith("clank/init/")) continue;
+
+    yield path;
+  }
+}
+
+/** Create prompt symlinks in all agent directories */
+export async function createPromptLinks(
+  overlayPath: string,
+  promptRelPath: string,
+  gitRoot: string,
+): Promise<string[]> {
+  const created: string[] = [];
+  for (const agentDir of managedAgentDirs) {
+    const targetPath = join(gitRoot, agentDir, "prompts", promptRelPath);
+    await ensureDir(dirname(targetPath));
+    const linkTarget = getLinkTarget(targetPath, overlayPath);
+    await createSymlink(linkTarget, targetPath);
+    created.push(targetPath);
+  }
+  return created;
+}

package/src/ScopeFromSymlink.ts

@@ -0,0 +1,22 @@
+import { lstat } from "node:fs/promises";
+import { resolveSymlinkTarget } from "./FsUtil.ts";
+import { type MapperContext, overlayToTarget, type Scope } from "./Mapper.ts";
+
+/** Get scope from symlink target if it points to overlay */
+export async function scopeFromSymlink(
+  targetPath: string,
+  context: MapperContext,
+): Promise<Scope | null> {
+  try {
+    const stats = await lstat(targetPath);
+    if (!stats.isSymbolicLink()) return null;
+
+    const overlayPath = await resolveSymlinkTarget(targetPath);
+    if (!overlayPath.startsWith(context.overlayRoot)) return null;
+
+    const mapping = overlayToTarget(overlayPath, context);
+    return mapping?.scope ?? null;
+  } catch {
+    return null;
+  }
+}

package/src/Templates.ts

@@ -0,0 +1,87 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { ensureDir, fileExists, walkDirectory } from "./FsUtil.ts";
+import type { GitContext } from "./Git.ts";
+import { overlayWorktreeDir } from "./Mapper.ts";
+
+/**
+ * clank stores worktree specific files in the overlay repo
+ * intended for user notes and plans for each branch.
+ */
+
+/** Template variables that can be used in template files */
+export interface TemplateVars {
+  worktree_message: string;
+  project_name: string;
+  branch_name: string;
+  [key: string]: string;
+}
+
+/** Check if worktree has already been initialized */
+export async function isWorktreeInitialized(
+  overlayRoot: string,
+  gitContext: GitContext,
+): Promise<boolean> {
+  return await fileExists(overlayWorktreeDir(overlayRoot, gitContext));
+}
+
+/** Initialize worktree-specific files from templates (overlay/global/init/ ==> worktrees/{branch}/) */
+export async function initializeWorktreeOverlay(
+  overlayRoot: string,
+  gitContext: GitContext,
+): Promise<void> {
+  const templateDir = join(overlayRoot, "global/init");
+  const overlayWorktree = overlayWorktreeDir(overlayRoot, gitContext);
+
+  if (!(await fileExists(templateDir))) {
+    await ensureDir(overlayWorktree);
+    return;
+  }
+
+  const vars = generateTemplateVars(gitContext);
+
+  for await (const { path, isDirectory } of walkDirectory(templateDir)) {
+    if (isDirectory) continue;
+
+    const relPath = relative(templateDir, path);
+    const targetPath = join(overlayWorktree, relPath);
+    await createFromTemplate(path, targetPath, vars);
+  }
+}
+
+/** Generate template variables from git context */
+export function generateTemplateVars(gitContext: GitContext): TemplateVars {
+  const { worktreeName, projectName } = gitContext;
+  const worktreeMessage = `This is git worktree ${worktreeName} of project ${projectName}.`;
+
+  return {
+    worktree_message: worktreeMessage,
+    project_name: projectName,
+    branch_name: worktreeName,
+  };
+}
+
+/** Create a file from a template with variable substitution */
+export async function createFromTemplate(
+  templatePath: string,
+  targetPath: string,
+  vars: TemplateVars,
+): Promise<void> {
+  const templateContent = await readFile(templatePath, "utf-8");
+  const processedContent = applyTemplate(templateContent, vars);
+
+  await ensureDir(join(targetPath, ".."));
+  await writeFile(targetPath, processedContent, "utf-8");
+}
+
+/** Replace template variables in content (uses {{variable_name}} syntax) */
+export function applyTemplate(content: string, vars: TemplateVars): string {
+  let result = content;
+
+  for (const [key, value] of Object.entries(vars)) {
+    const pattern = new RegExp(`\\{\\{${key}\\}\\}`, "g");
+    result = result.replace(pattern, value);
+  }
+
+  return result;
+}

package/src/Util.ts

@@ -0,0 +1,13 @@
+/** Partition an array into two arrays based on a predicate */
+export function partition<T>(
+  arr: T[],
+  predicate: (item: T) => boolean,
+): [T[], T[]] {
+  const pass: T[] = [];
+  const fail: T[] = [];
+  for (const item of arr) {
+    if (predicate(item)) pass.push(item);
+    else fail.push(item);
+  }
+  return [pass, fail];
+}

package/src/commands/Add.ts

@@ -0,0 +1,301 @@
+import {
+  lstat,
+  readFile,
+  readlink,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
+import { basename, dirname, join, relative } from "node:path";
+import { forEachAgentPath } from "../AgentFiles.ts";
+import { expandPath, loadConfig, validateOverlayExists } from "../Config.ts";
+import {
+  createSymlink,
+  ensureDir,
+  fileExists,
+  getLinkTarget,
+  isSymlink,
+  isTrackedByGit,
+  walkDirectory,
+} from "../FsUtil.ts";
+import { type GitContext, getGitContext } from "../Git.ts";
+import {
+  getPromptRelPath,
+  isAgentFile,
+  isPromptFile,
+  type MapperContext,
+  normalizeAddPath,
+  resolveScopeFromOptions,
+  type Scope,
+  type ScopeOptions,
+  targetToOverlay,
+} from "../Mapper.ts";
+import { createPromptLinks, isSymlinkToOverlay } from "../OverlayLinks.ts";
+import { scopeFromSymlink } from "../ScopeFromSymlink.ts";
+
+const scopeLabels: Record<Scope, string> = {
+  global: "global",
+  project: "project",
+  worktree: "worktree",
+};
+
+export type AddOptions = ScopeOptions;
+
+/** Add file(s) to overlay and create symlinks in target */
+export async function addCommand(
+  filePaths: string[],
+  options: AddOptions = {},
+): Promise<void> {
+  const cwd = process.cwd();
+  const gitContext = await getGitContext(cwd);
+  const config = await loadConfig();
+  const overlayRoot = expandPath(config.overlayRepo);
+
+  await validateAddOptions(options, overlayRoot, gitContext);
+
+  const ctx = { cwd, gitContext, config, overlayRoot };
+
+  for (const filePath of filePaths) {
+    const inputPath = join(cwd, filePath);
+
+    if (await isDirectory(inputPath)) {
+      for await (const { path, isDirectory } of walkDirectory(inputPath)) {
+        if (isDirectory) continue;
+        await addSingleFile(relative(cwd, path), options, ctx);
+      }
+    } else {
+      await addSingleFile(filePath, options, ctx);
+    }
+  }
+}
+
+interface AddContext {
+  cwd: string;
+  gitContext: GitContext;
+  config: { overlayRepo: string; agents: string[] };
+  overlayRoot: string;
+}
+
+/** Add a single file to overlay and create symlink */
+async function addSingleFile(
+  filePath: string,
+  options: AddOptions,
+  ctx: AddContext,
+): Promise<void> {
+  const { cwd, gitContext, config, overlayRoot } = ctx;
+  const { gitRoot } = gitContext;
+
+  const scope = resolveScopeFromOptions(options);
+  /** Absolute path where symlink will be created in target repo */
+  const normalizedPath = normalizeAddPath(filePath, cwd, gitRoot);
+  const context: MapperContext = {
+    overlayRoot,
+    targetRoot: gitRoot,
+    gitContext,
+  };
+  const overlayPath = targetToOverlay(normalizedPath, scope, context);
+
+  const fileName = basename(normalizedPath);
+  const scopeLabel =
+    scope === "global" ? "global" : `${gitContext.projectName} ${scope}`;
+
+  // Only check barePath for symlink - we want the user's input file, not clank/foo.md
+  const barePath = join(cwd, filePath);
+
+  // Check if already in overlay at a different scope
+  await checkScopeConflict(barePath, scope, context, cwd);
+
+  if (await fileExists(overlayPath)) {
+    console.log(`${fileName} already exists in ${scopeLabel} overlay`);
+  } else if (await isSymlink(barePath)) {
+    await addSymlinkToOverlay(barePath, overlayPath, scopeLabel);
+  } else {
+    await addFileToOverlay(normalizedPath, barePath, overlayPath, scopeLabel);
+  }
+
+  // Check if this is an agent file (CLAUDE.md, AGENTS.md, GEMINI.md)
+  if (isAgentFile(filePath)) {
+    const symlinkDir = dirname(normalizedPath);
+    const { agents } = config;
+    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(", ")}`);
+      }
+    }
+  } 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)}`);
+    }
+  }
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await lstat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Copy a symlink to the overlay, preserving its target */
+async function addSymlinkToOverlay(
+  inputPath: string,
+  overlayPath: string,
+  scopeLabel: string,
+): Promise<void> {
+  const target = await readlink(inputPath);
+  await ensureDir(dirname(overlayPath));
+  await symlink(target, overlayPath);
+  console.log(`Copied symlink ${basename(inputPath)} to ${scopeLabel} overlay`);
+}
+
+/** Copy file content to overlay */
+async function addFileToOverlay(
+  normalizedPath: string,
+  barePath: string,
+  overlayPath: string,
+  scopeLabel: string,
+): Promise<void> {
+  await ensureDir(dirname(overlayPath));
+  const content = await findSourceContent(normalizedPath, barePath);
+  await writeFile(overlayPath, content, "utf-8");
+  const fileName = basename(overlayPath);
+  if (content) {
+    console.log(`Copied ${fileName} to ${scopeLabel} overlay`);
+  } else {
+    console.log(`Created empty ${fileName} in ${scopeLabel} overlay`);
+  }
+}
+
+/** Find content from normalized path or bare input path */
+async function findSourceContent(
+  normalizedPath: string,
+  barePath: string,
+): Promise<string> {
+  // Try normalized path first (e.g., cwd/clank/foo.md)
+  if (
+    (await fileExists(normalizedPath)) &&
+    !(await isSymlink(normalizedPath))
+  ) {
+    return await readFile(normalizedPath, "utf-8");
+  }
+  // Fall back to bare input path (e.g., cwd/foo.md)
+  if ((await fileExists(barePath)) && !(await isSymlink(barePath))) {
+    return await readFile(barePath, "utf-8");
+  }
+  return "";
+}
+
+/** fail if we can't do an add with the given options */
+async function validateAddOptions(
+  options: AddOptions,
+  overlayRoot: string,
+  gitContext: GitContext,
+): Promise<void> {
+  await validateOverlayExists(overlayRoot);
+
+  if (options.worktree && !gitContext.isWorktree) {
+    throw new Error(
+      `--worktree scope requires a git worktree.\n` +
+        `You're on branch '${gitContext.worktreeName}' in the main repository.\n` +
+        `Use 'git worktree add' to create a worktree, or use --project scope instead.`,
+    );
+  }
+}
+
+/** Create agent symlinks (CLAUDE.md, GEMINI.md, AGENTS.md → agents.md) */
+interface AgentLinkParams {
+  overlayPath: string;
+  symlinkDir: string;
+  gitRoot: string;
+  overlayRoot: string;
+  agents: string[];
+}
+
+async function createAgentLinks(p: AgentLinkParams): Promise<void> {
+  const { overlayPath, ...classifyParams } = p;
+  const { toCreate, existing, skipped } =
+    await classifyAgentLinks(classifyParams);
+
+  const promisedLinks = toCreate.map(({ targetPath }) => {
+    const linkTarget = getLinkTarget(targetPath, overlayPath);
+    return createSymlink(linkTarget, targetPath);
+  });
+  await Promise.all(promisedLinks);
+
+  if (toCreate.length) {
+    const created = toCreate.map(({ name }) => name);
+    console.log(`Created symlinks: ${created.join(", ")}`);
+  }
+
+  if (existing.length) {
+    console.log(`Symlinks already exist: ${existing.join(", ")}`);
+  }
+
+  if (skipped.length) {
+    console.log(`Skipped (already tracked in git): ${skipped.join(", ")}`);
+  }
+}
+
+/** Check if file is already in overlay at a different scope, throw helpful error */
+async function checkScopeConflict(
+  barePath: string,
+  requestedScope: Scope,
+  context: MapperContext,
+  cwd: string,
+): Promise<void> {
+  const currentScope = await scopeFromSymlink(barePath, context);
+  if (currentScope && currentScope !== requestedScope) {
+    const fileName = relative(cwd, barePath);
+    throw new Error(
+      `${fileName} is already in ${scopeLabels[currentScope]} overlay.\n` +
+        `To move it to ${scopeLabels[requestedScope]} scope, use: clank mv ${fileName} --${requestedScope}`,
+    );
+  }
+}
+
+interface AgentLinkClassification {
+  toCreate: { targetPath: string; name: string }[];
+  existing: string[];
+  skipped: string[];
+}
+
+/** Classify which agent symlinks to create vs skip */
+async function classifyAgentLinks(
+  p: Omit<AgentLinkParams, "overlayPath">,
+): Promise<AgentLinkClassification> {
+  const { symlinkDir, gitRoot, overlayRoot, agents } = p;
+  const skipped: string[] = [];
+  const existing: string[] = [];
+  const toCreate: { targetPath: string; name: string }[] = [];
+
+  await forEachAgentPath(symlinkDir, agents, async (targetPath) => {
+    // Check if symlink already points to overlay
+    if (await isSymlinkToOverlay(targetPath, overlayRoot)) {
+      existing.push(basename(targetPath));
+      return;
+    }
+
+    const isTrackedFile =
+      (await fileExists(targetPath)) &&
+      !(await isSymlink(targetPath)) &&
+      (await isTrackedByGit(targetPath, gitRoot));
+
+    if (isTrackedFile) {
+      skipped.push(basename(targetPath));
+    } else {
+      toCreate.push({ targetPath, name: basename(targetPath) });
+    }
+  });
+
+  return { toCreate, existing, skipped };
+}