clank-cli 0.1.65 → 0.1.67

package/package.json

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

package/src/Cli.ts

@@ -171,6 +171,7 @@ function registerUtilityCommands(program: Command): void {
     .command("vscode")
     .description("Generate VS Code settings to show clank files")
     .option("--remove", "Remove clank-generated VS Code settings")
+    .option("--force", "Generate even if settings.json is tracked by git")
     .action(withErrorHandling(vscodeCommand));
 }
 

package/src/OverlayLinks.ts

@@ -1,14 +1,16 @@
-import { lstat } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { lstat, unlink } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
 import picomatch from "picomatch";
-import { managedAgentDirs } from "./AgentFiles.ts";
+import { managedAgentDirs, targetManagedDirs } from "./AgentFiles.ts";
 import {
   createSymlink,
   ensureDir,
   getLinkTarget,
+  isSymlink,
   resolveSymlinkTarget,
   walkDirectory,
 } from "./FsUtil.ts";
+import type { GitContext } from "./Git.ts";
 import {
   getPromptRelPath,
   type MapperContext,
@@ -139,3 +141,44 @@ function isMatchingPromptPath(
   const canonical = getPromptRelPath(canonicalPath);
   return canonical !== null && canonical === getPromptRelPath(actualPath);
 }
+
+/** Find and remove symlinks pointing to wrong worktree in the overlay.
+ *  Returns paths that were removed. */
+export async function cleanStaleWorktreeSymlinks(
+  targetRoot: string,
+  overlayRoot: string,
+  gitContext: GitContext,
+): Promise<string[]> {
+  const removed: string[] = [];
+  const currentWorktree = gitContext.worktreeName;
+  const projectName = gitContext.projectName;
+  const worktreesPrefix = `${overlayRoot}/targets/${projectName}/worktrees/`;
+
+  for await (const { path, isDirectory } of walkDirectory(targetRoot)) {
+    if (isDirectory) continue;
+
+    const relPath = relative(targetRoot, path);
+    if (!isInManagedDir(relPath)) continue;
+    if (!(await isSymlink(path))) continue;
+
+    const target = await resolveSymlinkTarget(path);
+    if (!target.startsWith(worktreesPrefix)) continue;
+
+    // Extract worktree name from path like .../worktrees/main/clank/notes.md
+    const afterPrefix = target.slice(worktreesPrefix.length);
+    const worktreeName = afterPrefix.split("/")[0];
+
+    if (worktreeName && worktreeName !== currentWorktree) {
+      await unlink(path);
+      removed.push(relPath);
+    }
+  }
+
+  return removed;
+}
+
+/** Check if a path is inside a clank-managed directory */
+function isInManagedDir(relPath: string): boolean {
+  const parts = relPath.split("/");
+  return parts.some((part) => targetManagedDirs.includes(part));
+}

package/src/commands/Check.ts

@@ -250,7 +250,7 @@ function showUnaddedFiles(
       `Found ${outsideOverlay.length} stale symlink(s) in ${targetName}:\n`,
     );
     console.log("These symlinks point outside the clank overlay.");
-    console.log("Remove them, then run `clank link` to recreate:\n");
+    console.log("Remove them manually, then run `clank link` to recreate:\n");
     for (const file of outsideOverlay) {
       console.log(`  rm ${relativePath(cwd, file.targetPath)}`);
     }
@@ -262,12 +262,11 @@ function showUnaddedFiles(
       `Found ${wrongMapping.length} mislinked symlink(s) in ${targetName}:\n`,
     );
     console.log("These symlinks point to the wrong overlay location.");
-    console.log("Remove them, then run `clank link` to recreate:\n");
+    console.log("Run `clank link` to fix them.\n");
     for (const file of wrongMapping) {
-      console.log(`  rm ${relativePath(cwd, file.targetPath)}`);
-      if (file.currentTarget && file.expectedTarget) {
+      console.log(`  ${relativePath(cwd, file.targetPath)}`);
+      if (file.currentTarget) {
         console.log(`    points to: ${file.currentTarget}`);
-        console.log(`    expected:  ${file.expectedTarget}`);
       }
     }
     console.log();

package/src/commands/Link.ts

@@ -32,6 +32,7 @@ import {
   type TargetMapping,
 } from "../Mapper.ts";
 import {
+  cleanStaleWorktreeSymlinks,
   createPromptLinks as createPromptLinksShared,
   walkOverlayFiles,
 } from "../OverlayLinks.ts";
@@ -40,7 +41,11 @@ import {
   isWorktreeInitialized,
 } from "../Templates.ts";
 import { findOrphans } from "./Check.ts";
-import { generateVscodeSettings, isVscodeProject } from "./VsCode.ts";
+import {
+  checkVscodeTracking,
+  generateVscodeSettings,
+  isVscodeProject,
+} from "./VsCode.ts";
 
 interface FileMapping extends TargetMapping {
   overlayPath: string;
@@ -68,6 +73,19 @@ export async function linkCommand(targetDir?: string): Promise<void> {
   const overlayRoot = expandPath(config.overlayRepo);
   await validateOverlayExists(overlayRoot);
 
+  // Clean up symlinks pointing to wrong worktree before linking
+  const staleRemoved = await cleanStaleWorktreeSymlinks(
+    targetRoot,
+    overlayRoot,
+    gitContext,
+  );
+  if (staleRemoved.length > 0) {
+    console.log(`\nCleaned ${staleRemoved.length} stale worktree symlink(s):`);
+    for (const path of staleRemoved) {
+      console.log(`  ${path}`);
+    }
+  }
+
   // Check for problematic agent files before proceeding
   await checkAgentFiles(targetRoot, overlayRoot);
 
@@ -291,6 +309,7 @@ async function maybeGenerateVscodeSettings(
 ): Promise<void> {
   const setting = config.vscodeSettings ?? "auto";
 
+  // User opted out - skip silently
   if (setting === "never") return;
 
   if (setting === "auto") {
@@ -298,7 +317,14 @@ async function maybeGenerateVscodeSettings(
     if (!isVscode) return;
   }
 
-  // setting === "always" or (setting === "auto" && isVscodeProject)
+  // Check if settings.json is tracked and show appropriate warning
+  const check = await checkVscodeTracking(targetRoot);
+  if (!check.canGenerate) {
+    console.log(`\n${check.warning}`);
+    return;
+  }
+
+  // Generate: "always" mode, or "auto" with untracked/layered settings
   console.log("");
   await generateVscodeSettings(targetRoot);
 }

package/src/commands/VsCode.ts

@@ -16,6 +16,95 @@ import {
 
 export interface VscodeOptions {
   remove?: boolean;
+  force?: boolean;
+}
+
+/** Result of checking if VS Code settings can be generated */
+export interface VscodeTrackingCheck {
+  canGenerate: boolean;
+  warning?: string;
+  hasBase: boolean;
+}
+
+/** Check if settings.base.json exists */
+export async function hasBaseSettings(targetRoot: string): Promise<boolean> {
+  return fileExists(join(targetRoot, ".vscode/settings.base.json"));
+}
+
+/** Read layered settings (base + local) if base exists */
+async function readLayeredSettings(
+  targetRoot: string,
+): Promise<Record<string, unknown> | null> {
+  const basePath = join(targetRoot, ".vscode/settings.base.json");
+  const localPath = join(targetRoot, ".vscode/settings.local.json");
+
+  if (!(await fileExists(basePath))) return null;
+
+  let base: Record<string, unknown> = {};
+  const baseContent = await readFile(basePath, "utf-8");
+  try {
+    base = JSON.parse(baseContent);
+  } catch {
+    console.warn("Warning: Could not parse settings.base.json, ignoring");
+    return null;
+  }
+
+  let local: Record<string, unknown> = {};
+  if (await fileExists(localPath)) {
+    const localContent = await readFile(localPath, "utf-8");
+    try {
+      local = JSON.parse(localContent);
+    } catch {
+      console.warn("Warning: Could not parse settings.local.json, ignoring");
+    }
+  }
+
+  // Merge exclude patterns specially (combine, don't replace)
+  const baseSearch = (base["search.exclude"] as Record<string, boolean>) || {};
+  const localSearch =
+    (local["search.exclude"] as Record<string, boolean>) || {};
+  const baseFiles = (base["files.exclude"] as Record<string, boolean>) || {};
+  const localFiles = (local["files.exclude"] as Record<string, boolean>) || {};
+
+  return {
+    ...base,
+    ...local,
+    "search.exclude": { ...baseSearch, ...localSearch },
+    "files.exclude": { ...baseFiles, ...localFiles },
+  };
+}
+
+/** Check if settings.json is tracked and return appropriate warning */
+export async function checkVscodeTracking(
+  targetRoot: string,
+): Promise<VscodeTrackingCheck> {
+  const settingsPath = join(targetRoot, ".vscode/settings.json");
+  const hasBase = await hasBaseSettings(targetRoot);
+  const isTracked = await isTrackedByGit(settingsPath, targetRoot);
+
+  if (!isTracked) {
+    return { canGenerate: true, hasBase };
+  }
+
+  // settings.json is tracked
+  if (hasBase) {
+    return {
+      canGenerate: false,
+      hasBase,
+      warning:
+        "settings.base.json found but settings.json is still tracked.\n" +
+        "Complete migration: git rm --cached .vscode/settings.json",
+    };
+  }
+
+  return {
+    canGenerate: false,
+    hasBase,
+    warning:
+      "Skipping: .vscode/settings.json is tracked.\n" +
+      "Use `clank vscode --force` to override, or migrate:\n" +
+      "  mv .vscode/settings.json .vscode/settings.base.json && git rm --cached .vscode/settings.json",
+  };
 }
 
 /** Generate VS Code settings to show clank files in search and explorer */
@@ -27,6 +116,19 @@ export async function vscodeCommand(options?: VscodeOptions): Promise<void> {
     return;
   }
 
+  // Check if we can generate (tracking check)
+  const check = await checkVscodeTracking(targetRoot);
+  if (!check.canGenerate && !options?.force) {
+    console.log(check.warning);
+    return;
+  }
+
+  if (options?.force && !check.canGenerate) {
+    console.log(
+      "Note: settings.json is tracked, this will create uncommitted changes.\n",
+    );
+  }
+
   await generateVscodeSettings(targetRoot);
 }
 
@@ -70,10 +172,38 @@ export async function generateVscodeSettings(
   );
 }
 
+/** Regenerate settings.json from base+local only (remove clank additions) */
+async function removeLayeredSettings(
+  settingsPath: string,
+  layered: Record<string, unknown>,
+): Promise<void> {
+  delete layered["search.useIgnoreFiles"];
+
+  if (Object.keys(layered).length === 0) {
+    if (await fileExists(settingsPath)) {
+      await unlink(settingsPath);
+      console.log("Removed .vscode/settings.json (base+local were empty)");
+    }
+  } else {
+    await writeJsonFile(settingsPath, layered);
+    console.log(
+      "Regenerated .vscode/settings.json from base+local (removed clank patterns)",
+    );
+  }
+}
+
 /** Remove clank-generated VS Code settings */
 export async function removeVscodeSettings(targetRoot: string): Promise<void> {
   const settingsPath = join(targetRoot, ".vscode/settings.json");
 
+  // If layered settings exist, regenerate from base+local only
+  const layered = await readLayeredSettings(targetRoot);
+  if (layered) {
+    await removeLayeredSettings(settingsPath, layered);
+    return;
+  }
+
+  // Legacy mode: selectively remove clank patterns
   if (!(await fileExists(settingsPath))) {
     return;
   }
@@ -123,11 +253,30 @@ export async function isVscodeProject(targetRoot: string): Promise<boolean> {
   }
 }
 
-/** Merge clank exclude patterns with existing .vscode/settings.json */
+/** Merge clank exclude patterns with layered or existing settings */
 async function mergeVscodeSettings(
   targetRoot: string,
   excludePatterns: Record<string, boolean>,
 ): Promise<Record<string, unknown>> {
+  // Try layered settings first (base + local)
+  const layered = await readLayeredSettings(targetRoot);
+
+  if (layered) {
+    // Layered mode: base + local + clank
+    const layeredSearch =
+      (layered["search.exclude"] as Record<string, boolean>) || {};
+    const layeredFiles =
+      (layered["files.exclude"] as Record<string, boolean>) || {};
+
+    return {
+      ...layered,
+      "search.useIgnoreFiles": false,
+      "search.exclude": { ...layeredSearch, ...excludePatterns },
+      "files.exclude": { ...layeredFiles, ...excludePatterns },
+    };
+  }
+
+  // Legacy mode: read existing settings.json
   const settingsPath = join(targetRoot, ".vscode/settings.json");
 
   let existingSettings: Record<string, unknown> = {};
@@ -170,11 +319,17 @@ async function writeVscodeSettings(
   console.log(`Wrote ${settingsPath}`);
 }
 
-/** Add .vscode/settings.json to .git/info/exclude */
+/** Add .vscode/settings.json and settings.local.json to .git/info/exclude */
 async function addVscodeToGitExclude(targetRoot: string): Promise<void> {
   const settingsPath = join(targetRoot, ".vscode/settings.json");
-  if (await isTrackedByGit(settingsPath, targetRoot)) return;
-  await addToGitExclude(targetRoot, ".vscode/settings.json");
+  const localPath = join(targetRoot, ".vscode/settings.local.json");
+
+  if (!(await isTrackedByGit(settingsPath, targetRoot))) {
+    await addToGitExclude(targetRoot, ".vscode/settings.json");
+  }
+  if (!(await isTrackedByGit(localPath, targetRoot))) {
+    await addToGitExclude(targetRoot, ".vscode/settings.local.json");
+  }
 }
 
 /** Remove patterns from an exclude object, deleting the key if empty */