syncdotfile 1.0.0

package/README.md

@@ -0,0 +1,137 @@
+# 🥷 SDF: Shadow Directory Framework
+
+**Bring your AI agent's brain to any Git repository. Leave absolutely no trace.**
+
+As AI coding agents (like Cursor, Aider, and Copilot Workspace) become more advanced, developers are building up extensive personal libraries of custom skills, prompt templates, and `agents.md` files.
+
+But bringing your personal AI context into a shared team repository causes friction:
+1. **Context Drift:** Copy-pasting your `agents.md` across 10 different repos means your agent's brain gets fragmented. Discover a new trick in Repo A? Repo B won't know about it.
+2. **Repo Pollution:** Adding `.agent` folders and `.cursorrules` to shared codebases annoys teammates who don't use the same AI workflow.
+
+**SDF solves both.** It is a zero-dependency Node.js CLI that dynamically projects your global AI skills into any local project invisibly.
+
+## ✨ How It Works
+
+SDF operates on three principles: **Symlinks**, an **Invisibility Cloak**, and **Stash/Restore**.
+
+When you run `sdf mount`, the CLI creates symlinks at your project root pointing to files in your global registry (`~/.sdf-registry`). Your `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md`, or any other context files appear exactly where every AI tool expects them.
+
+If a file already exists locally (e.g., the project already has an `AGENTS.md`), SDF backs it up to a hidden `.sdf-stash` directory before replacing it with your global version. When you `sdf unmount`, every original file is restored exactly as it was.
+
+All mounted files and the stash directory are added to `.git/info/exclude` — a local-only exclusion that never touches `.gitignore` and is never tracked by Git. Your agent gets the context it needs, Git ignores it entirely, and your teammates never even know it is there.
+
+Because it uses symlinks, any improvements your agent makes to a file locally are instantly saved to your global registry and available in all your other projects.
+
+## 🚀 Installation
+
+Install globally via npm:
+
+```bash
+npm install -g syncdotfile
+```
+
+## 🛠️ Usage
+
+### 1. Initialize your global registry
+
+**Option A:** Start fresh.
+```bash
+sdf init
+```
+
+**Option B:** Clone your existing `dotagent` repo.
+```bash
+sdf init https://github.com/yourname/dotagent.git
+```
+
+Populate `~/.sdf-registry` with the files you want mounted everywhere:
+```
+~/.sdf-registry/
+├── AGENTS.md
+├── CLAUDE.md
+├── .cursorrules
+├── .github/
+│   └── copilot-instructions.md
+└── skills/
+    ├── debugging.md
+    └── code-review.md
+```
+
+### 2. Mount your AI context
+
+Navigate to any local Git repository and mount.
+```bash
+cd my-team-project
+sdf mount
+```
+
+If files collide, SDF prompts you interactively:
+```
+⚠ AGENTS.md already exists in this project.
+   Local:    1284 bytes
+   Registry: 3502 bytes
+   [o]verwrite (stash original)  [s]kip  [d]iff  >
+```
+
+Or use flags for non-interactive workflows:
+```bash
+sdf mount --force           # Overwrite all conflicts (stashes originals)
+sdf mount --skip-conflicts  # Skip all conflicts
+```
+
+### 3. Check status
+```bash
+sdf status
+```
+```
+🟢 3 files mounted:
+   AGENTS.md -> ~/.sdf-registry/AGENTS.md
+   CLAUDE.md -> ~/.sdf-registry/CLAUDE.md
+   .cursorrules -> ~/.sdf-registry/.cursorrules
+📦 1 original stashed:
+   AGENTS.md (2026-03-17)
+ℹ Registry git: main (clean)
+```
+
+### 4. Unmount and clean up
+
+Sever the symlinks and restore stashed originals.
+```bash
+sdf unmount
+```
+```
+✔ Unlinked AGENTS.md
+✔ Unlinked CLAUDE.md
+✔ Unlinked .cursorrules
+✔ Restored AGENTS.md from stash
+✔ Unmounted: 3 symlinks removed, 1 original restored.
+```
+
+### 5. Sync with Git
+
+If you initialised your registry from a Git repo (like `dotagent`), SDF provides thin wrappers to keep it synced:
+
+```bash
+sdf pull          # Pull latest changes from remote
+sdf push          # Stage, commit, and push all local changes
+sdf diff          # Show uncommitted changes in the registry
+```
+
+## 🥊 SDF vs. Dotfile Managers (Chezmoi, Stow)
+
+Dotfile managers are designed to permanently deploy system configurations (like `~/.zshrc`) to your home directory. SDF is designed to temporarily inject personalized AI context into individual, shared workspaces without polluting version control.
+
+SDF doesn't copy files; it tethers them. It is a live brain connection for your AI tools.
+
+## 🗺️ Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for the full product roadmap, including planned features:
+- **Selective mounting** — mount subsets with globs or exclude patterns
+- **Profiles** — named file sets for different project types (Go, React, etc.)
+- **Project context generation** — auto-generate project-specific instructions by scanning the codebase
+- **Drift detection** — flag when local instructions are stale after registry updates
+- **Multi-source registries** — layer team + personal repos
+
+## 📄 License
+
+MIT

package/index.js

@@ -0,0 +1,645 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import readline from "node:readline";
+import { execSync } from "node:child_process";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+const REGISTRY_DIR = path.join(os.homedir(), ".sdf-registry");
+const STASH_DIR_NAME = ".sdf-stash";
+const STASH_MANIFEST = "manifest.json";
+const GIT_DIR = path.resolve(".git");
+const GIT_EXCLUDE_FILE = path.join(GIT_DIR, "info", "exclude");
+
+const SDF_MANAGED_COMMENT = "# sdf-managed";
+
+// ---------------------------------------------------------------------------
+// ANSI helpers
+// ---------------------------------------------------------------------------
+const color = {
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+};
+
+function success(msg) {
+  console.log(color.green(`✔ ${msg}`));
+}
+function warn(msg) {
+  console.log(color.yellow(`⚠ ${msg}`));
+}
+function info(msg) {
+  console.log(color.cyan(`ℹ ${msg}`));
+}
+function error(msg) {
+  console.error(color.red(`✖ ${msg}`));
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function requireGitRepo() {
+  if (!fs.existsSync(GIT_DIR) || !fs.statSync(GIT_DIR).isDirectory()) {
+    error("Must be run at the root of a Git repository.");
+    process.exit(1);
+  }
+}
+
+function requireRegistry() {
+  if (!fs.existsSync(REGISTRY_DIR)) {
+    error("Global registry does not exist. Run `sdf init` first.");
+    process.exit(1);
+  }
+}
+
+function registryEntries(dir = REGISTRY_DIR, prefix = "") {
+  const results = [];
+  for (const entry of fs.readdirSync(dir)) {
+    if (entry === ".git") continue;
+    const fullPath = path.join(dir, entry);
+    const relativePath = prefix ? path.join(prefix, entry) : entry;
+    const stat = fs.statSync(fullPath);
+    if (stat.isDirectory()) {
+      results.push(...registryEntries(fullPath, relativePath));
+    } else {
+      results.push(relativePath);
+    }
+  }
+  return results;
+}
+
+function gitCmd(args, cwd = REGISTRY_DIR) {
+  return execSync(`git ${args}`, { cwd, encoding: "utf-8", stdio: "pipe" }).trim();
+}
+
+function isRegistryAGitRepo() {
+  return fs.existsSync(path.join(REGISTRY_DIR, ".git"));
+}
+
+function requireRegistryGit() {
+  requireRegistry();
+  if (!isRegistryAGitRepo()) {
+    error("Registry is not a Git repository. Use `sdf init <git-url>` to set one up.");
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Git exclude management
+// ---------------------------------------------------------------------------
+function readExclude() {
+  ensureDir(path.join(GIT_DIR, "info"));
+  if (!fs.existsSync(GIT_EXCLUDE_FILE)) return [];
+  return fs.readFileSync(GIT_EXCLUDE_FILE, "utf-8").split("\n");
+}
+
+function writeExclude(lines) {
+  const content = lines.join("\n");
+  fs.writeFileSync(GIT_EXCLUDE_FILE, content.endsWith("\n") ? content : content + "\n");
+}
+
+function addExclusion(filename) {
+  const lines = readExclude();
+  if (lines.some((l) => l.trim() === filename)) return false;
+  const needsNewline = lines.length > 0 && lines[lines.length - 1] !== "";
+  if (needsNewline) lines.push("");
+  lines.push(SDF_MANAGED_COMMENT);
+  lines.push(filename);
+  writeExclude(lines);
+  return true;
+}
+
+function removeExclusion(filename) {
+  const lines = readExclude();
+  const filtered = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === filename) {
+      if (filtered.length > 0 && filtered[filtered.length - 1].trim() === SDF_MANAGED_COMMENT) {
+        filtered.pop();
+      }
+      continue;
+    }
+    filtered.push(lines[i]);
+  }
+  const cleaned = filtered.join("\n").replace(/\n{3,}/g, "\n\n");
+  fs.writeFileSync(GIT_EXCLUDE_FILE, cleaned.endsWith("\n") ? cleaned : cleaned + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Stash management
+// ---------------------------------------------------------------------------
+function stashDir() {
+  return path.resolve(STASH_DIR_NAME);
+}
+
+function manifestPath() {
+  return path.join(stashDir(), STASH_MANIFEST);
+}
+
+function readManifest() {
+  const mp = manifestPath();
+  if (!fs.existsSync(mp)) return {};
+  return JSON.parse(fs.readFileSync(mp, "utf-8"));
+}
+
+function writeManifest(manifest) {
+  ensureDir(stashDir());
+  fs.writeFileSync(manifestPath(), JSON.stringify(manifest, null, 2) + "\n");
+}
+
+function stashFile(filePath) {
+  const sd = stashDir();
+  const stashedPath = path.join(sd, filePath);
+  ensureDir(path.dirname(stashedPath));
+
+  const sourcePath = path.resolve(filePath);
+  fs.copyFileSync(sourcePath, stashedPath);
+
+  const manifest = readManifest();
+  manifest[filePath] = {
+    stashedAt: new Date().toISOString(),
+    size: fs.statSync(stashedPath).size,
+  };
+  writeManifest(manifest);
+}
+
+function restoreFile(filePath) {
+  const stashedPath = path.join(stashDir(), filePath);
+  const targetPath = path.resolve(filePath);
+
+  if (!fs.existsSync(stashedPath)) return false;
+
+  ensureDir(path.dirname(targetPath));
+  fs.copyFileSync(stashedPath, targetPath);
+
+  const manifest = readManifest();
+  delete manifest[filePath];
+  writeManifest(manifest);
+
+  return true;
+}
+
+function cleanupStash() {
+  const sd = stashDir();
+  if (!fs.existsSync(sd)) return;
+  const manifest = readManifest();
+  if (Object.keys(manifest).length === 0) {
+    fs.rmSync(sd, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Interactive prompt
+// ---------------------------------------------------------------------------
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+function init() {
+  const url = process.argv[3];
+
+  if (url) {
+    if (fs.existsSync(REGISTRY_DIR)) {
+      error(`Registry already exists at ${REGISTRY_DIR}. Remove it first to re-clone.`);
+      process.exit(1);
+    }
+    info(`Cloning ${url} into ${REGISTRY_DIR}...`);
+    try {
+      execSync(`git clone ${url} "${REGISTRY_DIR}"`, { stdio: "inherit" });
+    } catch {
+      error("Git clone failed.");
+      process.exit(1);
+    }
+    success(`Registry cloned from ${url}`);
+    return;
+  }
+
+  const created = !fs.existsSync(REGISTRY_DIR);
+  ensureDir(REGISTRY_DIR);
+
+  if (created) {
+    success(`Created global registry at ${REGISTRY_DIR}`);
+  } else {
+    info(`Registry already exists at ${REGISTRY_DIR}`);
+  }
+
+  const placeholder = path.join(REGISTRY_DIR, "default-agent.md");
+  if (!fs.existsSync(placeholder)) {
+    fs.writeFileSync(
+      placeholder,
+      [
+        "# Default Agent",
+        "",
+        "You are a helpful coding assistant.",
+        "",
+        "## Guidelines",
+        "",
+        "- Write clean, well-structured code.",
+        "- Prefer simple solutions over clever ones.",
+        "- Always explain your reasoning.",
+        "",
+      ].join("\n"),
+    );
+    success(`Created placeholder prompt: ${placeholder}`);
+  } else {
+    info("Placeholder prompt already exists — skipped.");
+  }
+
+  success("Registry initialised. Add your prompt files to ~/.sdf-registry (or use `sdf init <url>` to clone your dotagent repo).");
+}
+
+async function mount() {
+  requireGitRepo();
+  requireRegistry();
+
+  const entries = registryEntries();
+  if (entries.length === 0) {
+    warn("Registry is empty — nothing to mount.");
+    return;
+  }
+
+  const isWin = os.platform() === "win32";
+  const forceAll = process.argv.includes("--force");
+  const skipAll = process.argv.includes("--skip-conflicts");
+  let linked = 0;
+  let stashed = 0;
+
+  for (const entry of entries) {
+    const source = path.join(REGISTRY_DIR, entry);
+    const target = path.resolve(entry);
+
+    // Already a symlink pointing to our registry
+    if (fs.existsSync(target)) {
+      const stat = fs.lstatSync(target);
+      if (stat.isSymbolicLink()) {
+        const linkTarget = fs.readlinkSync(target);
+        if (linkTarget === source) {
+          info(`Already linked: ${entry}`);
+          continue;
+        }
+      }
+
+      // Collision: a real file exists
+      let action = "skip";
+
+      if (forceAll) {
+        action = "overwrite";
+      } else if (skipAll) {
+        action = "skip";
+      } else if (process.stdin.isTTY) {
+        console.log("");
+        warn(`${color.bold(entry)} already exists in this project.`);
+
+        const localSize = fs.statSync(target).size;
+        const registrySize = fs.statSync(source).size;
+        console.log(`   Local:    ${localSize} bytes`);
+        console.log(`   Registry: ${registrySize} bytes`);
+
+        const answer = await ask(
+          `   ${color.cyan("[o]")}verwrite (stash original)  ${color.cyan("[s]")}kip  ${color.cyan("[d]")}iff  > `,
+        );
+
+        if (answer === "d" || answer === "diff") {
+          try {
+            const diff = execSync(
+              `diff --unified "${target}" "${source}"`,
+              { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
+            );
+            console.log(diff || "   (files are identical)");
+          } catch (e) {
+            console.log(e.stdout || "   (binary or incomparable files)");
+          }
+          const answer2 = await ask(
+            `   ${color.cyan("[o]")}verwrite (stash original)  ${color.cyan("[s]")}kip  > `,
+          );
+          if (answer2 === "o" || answer2 === "overwrite") action = "overwrite";
+        } else if (answer === "o" || answer === "overwrite") {
+          action = "overwrite";
+        }
+      }
+
+      if (action === "skip") {
+        info(`Skipped ${entry}`);
+        continue;
+      }
+
+      // Stash the original before overwriting
+      stashFile(entry);
+      success(`Stashed original ${entry} → ${STASH_DIR_NAME}/${entry}`);
+
+      // Remove the original (file or directory)
+      const lstat = fs.lstatSync(target);
+      if (lstat.isDirectory()) {
+        fs.rmSync(target, { recursive: true, force: true });
+      } else {
+        fs.unlinkSync(target);
+      }
+      stashed++;
+    }
+
+    // Create parent directories if needed (for nested registry files like .github/copilot-instructions.md)
+    ensureDir(path.dirname(target));
+
+    const stat = fs.statSync(source);
+    const symlinkType = stat.isDirectory() ? (isWin ? "junction" : "dir") : "file";
+
+    fs.symlinkSync(source, target, symlinkType);
+
+    // Exclude the top-level entry (for nested paths, exclude the top dir)
+    const topLevel = entry.includes(path.sep) ? entry.split(path.sep)[0] : entry;
+    addExclusion(topLevel);
+
+    success(`Linked ${entry}`);
+    linked++;
+  }
+
+  // Exclude stash dir itself
+  if (fs.existsSync(stashDir())) {
+    addExclusion(STASH_DIR_NAME);
+  }
+
+  if (linked === 0) {
+    info("All registry entries already linked or skipped.");
+  } else {
+    const stashMsg = stashed > 0 ? ` (${stashed} original${stashed === 1 ? "" : "s"} stashed)` : "";
+    success(`Mounted ${linked} file${linked === 1 ? "" : "s"} from registry.${stashMsg}`);
+  }
+}
+
+function unmount() {
+  requireGitRepo();
+
+  const cwd = process.cwd();
+  let removed = 0;
+
+  // Find and remove all symlinks pointing to the registry (including nested)
+  function removeSymlinks(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir)) {
+      const fullPath = path.join(dir, entry);
+      const stat = fs.lstatSync(fullPath);
+
+      if (stat.isSymbolicLink()) {
+        const linkTarget = fs.readlinkSync(fullPath);
+        if (linkTarget.startsWith(REGISTRY_DIR)) {
+          const relative = path.relative(cwd, fullPath);
+          fs.unlinkSync(fullPath);
+          success(`Unlinked ${relative}`);
+          removed++;
+        }
+      } else if (stat.isDirectory() && entry !== ".git" && entry !== STASH_DIR_NAME && entry !== "node_modules") {
+        removeSymlinks(fullPath);
+        // Clean up empty parent directories left behind
+        try {
+          const remaining = fs.readdirSync(fullPath);
+          if (remaining.length === 0) fs.rmdirSync(fullPath);
+        } catch {
+          // ignore
+        }
+      }
+    }
+  }
+
+  removeSymlinks(cwd);
+
+  // Restore stashed files
+  const manifest = readManifest();
+  const stashedFiles = Object.keys(manifest);
+  let restored = 0;
+
+  for (const filePath of stashedFiles) {
+    if (restoreFile(filePath)) {
+      success(`Restored ${filePath} from stash`);
+      restored++;
+    }
+  }
+
+  cleanupStash();
+
+  // Clean git exclude of all sdf-managed entries
+  if (fs.existsSync(GIT_EXCLUDE_FILE)) {
+    const lines = readExclude();
+    const filtered = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (
+        i + 1 < lines.length &&
+        lines[i].trim() === SDF_MANAGED_COMMENT
+      ) {
+        // Check if next line is an sdf-managed entry — skip both
+        i++;
+        continue;
+      }
+      if (lines[i].trim() === SDF_MANAGED_COMMENT) continue;
+      filtered.push(lines[i]);
+    }
+    const cleaned = filtered.join("\n").replace(/\n{3,}/g, "\n\n");
+    fs.writeFileSync(GIT_EXCLUDE_FILE, cleaned.endsWith("\n") ? cleaned : cleaned + "\n");
+  }
+
+  if (removed === 0 && restored === 0) {
+    info("No SDF symlinks or stashed files found.");
+  } else {
+    const parts = [];
+    if (removed > 0) parts.push(`${removed} symlink${removed === 1 ? "" : "s"} removed`);
+    if (restored > 0) parts.push(`${restored} original${restored === 1 ? "" : "s"} restored`);
+    success(`Unmounted: ${parts.join(", ")}.`);
+  }
+}
+
+function status() {
+  const cwd = process.cwd();
+  const mounted = [];
+
+  function findMounted(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir)) {
+      const fullPath = path.join(dir, entry);
+      const stat = fs.lstatSync(fullPath);
+
+      if (stat.isSymbolicLink()) {
+        const linkTarget = fs.readlinkSync(fullPath);
+        if (linkTarget.startsWith(REGISTRY_DIR)) {
+          mounted.push(path.relative(cwd, fullPath));
+        }
+      } else if (stat.isDirectory() && entry !== ".git" && entry !== STASH_DIR_NAME && entry !== "node_modules") {
+        findMounted(fullPath);
+      }
+    }
+  }
+
+  findMounted(cwd);
+
+  if (mounted.length > 0) {
+    console.log(color.green(`🟢 ${mounted.length} file${mounted.length === 1 ? "" : "s"} mounted:`));
+    for (const f of mounted) {
+      console.log(`   ${color.cyan(f)} -> ~/.sdf-registry/${f}`);
+    }
+  } else {
+    console.log("⚪️ No SDF symlinks detected in this directory.");
+  }
+
+  // Show stash info
+  const manifest = readManifest();
+  const stashedFiles = Object.keys(manifest);
+  if (stashedFiles.length > 0) {
+    console.log(color.yellow(`📦 ${stashedFiles.length} original${stashedFiles.length === 1 ? "" : "s"} stashed:`));
+    for (const f of stashedFiles) {
+      console.log(`   ${color.dim(f)} (${manifest[f].stashedAt.slice(0, 10)})`);
+    }
+  }
+
+  if (isRegistryAGitRepo()) {
+    try {
+      const branch = gitCmd("rev-parse --abbrev-ref HEAD");
+      const dirty = gitCmd("status --porcelain");
+      const label = dirty ? color.yellow("(uncommitted changes)") : color.green("(clean)");
+      info(`Registry git: ${branch} ${label}`);
+    } catch {
+      // not a concern if this fails
+    }
+  }
+}
+
+function pull() {
+  requireRegistryGit();
+  info("Pulling latest from remote...");
+  try {
+    const output = gitCmd("pull");
+    console.log(color.dim(output));
+    success("Registry updated.");
+  } catch (e) {
+    error(`Pull failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function push() {
+  requireRegistryGit();
+
+  const dirty = gitCmd("status --porcelain");
+  if (!dirty) {
+    info("Nothing to push — registry is clean.");
+    return;
+  }
+
+  info("Staging all changes...");
+  gitCmd("add -A");
+
+  const timestamp = new Date().toISOString().replace("T", " ").slice(0, 19);
+  const msg = `sdf: sync ${timestamp}`;
+  gitCmd(`commit -m "${msg}"`);
+  success(`Committed: ${msg}`);
+
+  info("Pushing to remote...");
+  try {
+    const output = gitCmd("push");
+    if (output) console.log(color.dim(output));
+    success("Registry pushed.");
+  } catch (e) {
+    error(`Push failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+function diff() {
+  requireRegistryGit();
+  const output = gitCmd("diff");
+  const untrackedRaw = gitCmd("ls-files --others --exclude-standard");
+  const untracked = untrackedRaw ? untrackedRaw.split("\n") : [];
+
+  if (!output && untracked.length === 0) {
+    info("No local changes in registry.");
+    return;
+  }
+
+  if (output) console.log(output);
+  if (untracked.length > 0) {
+    console.log(color.yellow("\nUntracked files:"));
+    for (const f of untracked) {
+      console.log(`  ${color.cyan(f)}`);
+    }
+  }
+}
+
+function usage() {
+  console.log(`
+${color.bold("sdf")} — Shadow Directory Framework
+
+${color.cyan("Usage:")}
+  sdf init [url]   Initialise registry, or clone from a repo (e.g. your dotagent repo)
+  sdf mount        Symlink registry files into the current Git repo root
+  sdf unmount      Remove SDF symlinks, restore stashed originals
+  sdf status       Show mounted files, stashed originals, and registry git state
+
+${color.cyan("Mount options:")}
+  --force          Overwrite all conflicts without prompting (stashes originals)
+  --skip-conflicts Skip all conflicts without prompting
+
+${color.cyan("Git sync:")}
+  sdf pull         Pull latest changes into the registry
+  sdf push         Commit and push local registry changes
+  sdf diff         Show uncommitted changes in the registry
+
+${color.cyan("Example:")}
+  sdf init https://github.com/yourname/dotagent.git
+  cd my-project && sdf mount
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Router
+// ---------------------------------------------------------------------------
+const command = process.argv[2];
+
+switch (command) {
+  case "init":
+    init();
+    break;
+  case "mount":
+    mount();
+    break;
+  case "unmount":
+    unmount();
+    break;
+  case "status":
+    status();
+    break;
+  case "pull":
+    pull();
+    break;
+  case "push":
+    push();
+    break;
+  case "diff":
+    diff();
+    break;
+  default:
+    if (command) {
+      error(`Unknown command: ${command}`);
+    }
+    usage();
+    break;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "syncdotfile",
+  "version": "1.0.0",
+  "description": "Shadow Directory Framework — project AI agent prompts via symlinks, invisible to Git.",
+  "type": "module",
+  "bin": {
+    "sdf": "index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "keywords": [
+    "cli",
+    "symlink",
+    "dotfiles",
+    "ai",
+    "agents",
+    "cursor",
+    "copilot",
+    "codex",
+    "claude",
+    "agentic"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NicholasCullenCooper/syncdotfile.git"
+  },
+  "homepage": "https://github.com/NicholasCullenCooper/syncdotfile#readme",
+  "author": "Nicholas Cullen Cooper",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}