vectorvesper 2.1.0 → 2.3.0

package/dist/index.js

@@ -23,8 +23,122 @@ import { Command } from "commander";
 // src/commands/init.ts
 import { intro, outro, select, text, confirm, isCancel } from "@clack/prompts";
 import pc from "picocolors";
+import fs2 from "fs";
+import path2 from "path";
+
+// src/utils/agent-rules.ts
 import fs from "fs";
 import path from "path";
+var BEGIN = "<!-- BEGIN:vectorvesper -->";
+var END = "<!-- END:vectorvesper -->";
+function renderBlock({ targetDir, alias, components = [] }) {
+  const installed = components.length > 0 ? components.slice().sort().map((c) => `\`${c}\``).join(", ") : "_none yet_";
+  return `# Vector Vesper motion
+
+<!-- Managed by \`vv init\`. Put your own rules OUTSIDE this block \u2014 \`vv init\`
+     rewrites everything between the markers. \`vv add\` only touches the
+     "Installed" line below. -->
+
+This project uses [\`@vectorvesper/motion\`](https://vectorvesper.dev/docs) \u2014 a
+motion runtime where every animation shares **one frame loop**, one pointer and
+scroll sensor layer, and one performance budget.
+
+## The rule that matters
+
+**Never start a \`requestAnimationFrame\` loop.** Subscribe to the shared
+conductor instead:
+
+\`\`\`ts
+import { getConductor } from "@vectorvesper/motion";
+
+const stop = getConductor().subscribe("render", (dt) => {
+  // dt is seconds since this subscriber last ran
+});
+// call stop() on cleanup \u2014 always
+\`\`\`
+
+A private loop runs outside the shared budget, so it cannot be throttled,
+prioritised or shed when frames run long. Nothing errors when this is wrong;
+it shows up later as jank on mid-range devices.
+
+Same rule for pointer and scroll: read \`getSensorBus().state\` rather than
+attaching your own listeners.
+
+## Where things are
+
+- Installed components: \`${targetDir}\`, imported from \`${alias}\`
+- Installed: ${installed}
+- Never edit files in that directory expecting updates to survive \u2014 \`vv add\`
+  rewrites them.
+
+## Before writing animation code
+
+If the \`vectorvesper\` MCP server is connected, use it \u2014 it has the full
+contract for every primitive:
+
+- \`search\` or \`list_hooks\` \u2014 find the primitive that already does this
+- \`get_hook\` \u2014 its lane, what it conflicts with, when *not* to use it
+- \`list_patterns\` / \`get_pattern\` \u2014 for anything combining primitives
+  (scrollytelling, marquees, adaptive heroes)
+- \`check_motion\` \u2014 run it on files you changed; it catches unmanaged loops,
+  missing cleanup, per-frame state writes and missing reduced-motion guards
+
+If it is not connected, the same material is at
+<https://vectorvesper.dev/docs>. Run \`npx vectorvesper mcp status\` to check.
+
+## Non-negotiable
+
+- Autonomous motion must respect \`prefers-reduced-motion\`. User-driven
+  navigation may keep working; things that move on their own must stop.
+- Never copy a hook's implementation into the project. A copy runs its own
+  loop, which is the problem this runtime exists to solve.`;
+}
+function writeAgentRules(cwd, input) {
+  const file = path.join(cwd, "AGENTS.md");
+  const block = `${BEGIN}
+${renderBlock(input)}
+${END}`;
+  if (!fs.existsSync(file)) {
+    fs.writeFileSync(file, `${block}
+`, "utf-8");
+    return { action: "created", file: "AGENTS.md" };
+  }
+  const existing = fs.readFileSync(file, "utf-8");
+  const start = existing.indexOf(BEGIN);
+  const end = existing.indexOf(END);
+  if (start === -1 || end === -1 || end < start) {
+    const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+    fs.writeFileSync(file, `${existing}${sep}${block}
+`, "utf-8");
+    return { action: "updated", file: "AGENTS.md" };
+  }
+  const next = existing.slice(0, start) + block + existing.slice(end + END.length);
+  if (next === existing) return { action: "unchanged", file: "AGENTS.md" };
+  fs.writeFileSync(file, next, "utf-8");
+  return { action: "updated", file: "AGENTS.md" };
+}
+var INSTALLED_LINE = /^- Installed: .*$/m;
+function refreshAgentRules(cwd, input) {
+  try {
+    const file = path.join(cwd, "AGENTS.md");
+    if (!fs.existsSync(file)) return false;
+    const existing = fs.readFileSync(file, "utf-8");
+    const start = existing.indexOf(BEGIN);
+    const end = existing.indexOf(END);
+    if (start === -1 || end === -1 || end < start) return false;
+    const block = existing.slice(start, end);
+    if (!INSTALLED_LINE.test(block)) return false;
+    const installed = (input.components ?? []).length > 0 ? input.components.slice().sort().map((c) => `\`${c}\``).join(", ") : "_none yet_";
+    const nextBlock = block.replace(INSTALLED_LINE, `- Installed: ${installed}`);
+    if (nextBlock === block) return false;
+    fs.writeFileSync(file, existing.slice(0, start) + nextBlock + existing.slice(end), "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/commands/init.ts
 async function initCommand(options = {}) {
   console.log("");
   intro(pc.cyan(pc.bold("  Vector Vesper Setup  ")));
@@ -114,14 +228,18 @@ async function initCommand(options = {}) {
   try {
     writeConfig(config);
     const targetLocalDir = resolveAlias(aliasInput, projectInfo.hasSrcDir);
-    const absoluteTargetDir = path.join(process.cwd(), targetLocalDir);
-    if (!fs.existsSync(absoluteTargetDir)) {
-      fs.mkdirSync(absoluteTargetDir, { recursive: true });
+    const absoluteTargetDir = path2.join(process.cwd(), targetLocalDir);
+    if (!fs2.existsSync(absoluteTargetDir)) {
+      fs2.mkdirSync(absoluteTargetDir, { recursive: true });
     }
-    const manifestPath = path.join(process.cwd(), "vv-manifest.json");
-    if (!fs.existsSync(manifestPath)) {
-      fs.writeFileSync(manifestPath, JSON.stringify({ components: {} }, null, 2), "utf-8");
+    const manifestPath = path2.join(process.cwd(), "vv-manifest.json");
+    if (!fs2.existsSync(manifestPath)) {
+      fs2.writeFileSync(manifestPath, JSON.stringify({ components: {} }, null, 2), "utf-8");
     }
+    const rules = options.agentRules === false ? null : writeAgentRules(process.cwd(), {
+      targetDir: targetLocalDir,
+      alias: aliasInput
+    });
     console.log("");
     outro(
       `${pc.green(pc.bold("\u2714 Success!"))} Vector Vesper initialized.
@@ -129,7 +247,9 @@ async function initCommand(options = {}) {
   \u2022 Configuration written to ${pc.cyan("vv.config.json")}
   \u2022 Target directory created at ${pc.cyan(targetLocalDir)}
   \u2022 Manifest created at ${pc.cyan("vv-manifest.json")}
-
+` + (rules ? `  \u2022 Agent rules ${rules.action} in ${pc.cyan(rules.file)}
+` : `  \u2022 Agent rules skipped ${pc.dim("(--no-agent-rules)")}
+`) + `
   \u{1F449} Next, run: ${pc.bold(pc.cyan("npx vectorvesper add <slug>"))} to add a component.`
     );
   } catch (error) {
@@ -188,8 +308,8 @@ async function listCommand() {
 }
 
 // src/commands/add.ts
-import fs4 from "fs";
-import path4 from "path";
+import fs5 from "fs";
+import path5 from "path";
 import ora2 from "ora";
 import pc5 from "picocolors";
 import { confirm as confirm2, isCancel as isCancel2 } from "@clack/prompts";
@@ -200,8 +320,8 @@ function isInteractive() {
 }
 
 // src/utils/installer.ts
-import fs2 from "fs";
-import path2 from "path";
+import fs3 from "fs";
+import path3 from "path";
 import pc3 from "picocolors";
 var MAX_DEPTH = 20;
 function toForwardSlash(p) {
@@ -236,12 +356,12 @@ async function resolveComponentTree(slug) {
 }
 function planFiles(components, installDir, projectRoot) {
   const planned = [];
-  const compDir = path2.join(projectRoot, installDir);
+  const compDir = path3.join(projectRoot, installDir);
   for (const component of components) {
     for (const file of component.files) {
-      const absolutePath = path2.resolve(compDir, file.target);
-      const relativeFromRoot = path2.relative(projectRoot, absolutePath);
-      if (relativeFromRoot.startsWith("..") || path2.isAbsolute(relativeFromRoot)) {
+      const absolutePath = path3.resolve(compDir, file.target);
+      const relativeFromRoot = path3.relative(projectRoot, absolutePath);
+      if (relativeFromRoot.startsWith("..") || path3.isAbsolute(relativeFromRoot)) {
         throw new Error(
           `Security Error: component target tries to escape project root: ${file.target}`
         );
@@ -251,7 +371,7 @@ function planFiles(components, installDir, projectRoot) {
         relativePath: relativeFromRoot,
         target: file.target,
         content: file.content,
-        exists: fs2.existsSync(absolutePath)
+        exists: fs3.existsSync(absolutePath)
       });
     }
   }
@@ -259,28 +379,28 @@ function planFiles(components, installDir, projectRoot) {
 }
 function writeFiles(files) {
   for (const file of files) {
-    const folder = path2.dirname(file.absolutePath);
-    if (!fs2.existsSync(folder)) {
-      fs2.mkdirSync(folder, { recursive: true });
+    const folder = path3.dirname(file.absolutePath);
+    if (!fs3.existsSync(folder)) {
+      fs3.mkdirSync(folder, { recursive: true });
     }
-    fs2.writeFileSync(file.absolutePath, file.content, "utf-8");
+    fs3.writeFileSync(file.absolutePath, file.content, "utf-8");
   }
 }
 var MANIFEST_NAME = "vv-manifest.json";
 function getManifestPath(projectRoot) {
-  return path2.join(projectRoot, MANIFEST_NAME);
+  return path3.join(projectRoot, MANIFEST_NAME);
 }
 function readManifest(projectRoot) {
   const manifestPath = getManifestPath(projectRoot);
-  if (!fs2.existsSync(manifestPath)) {
+  if (!fs3.existsSync(manifestPath)) {
     return { components: {} };
   }
-  const parsed = JSON.parse(fs2.readFileSync(manifestPath, "utf-8"));
+  const parsed = JSON.parse(fs3.readFileSync(manifestPath, "utf-8"));
   if (!parsed.components) parsed.components = {};
   return parsed;
 }
 function writeManifest(projectRoot, manifest) {
-  fs2.writeFileSync(getManifestPath(projectRoot), JSON.stringify(manifest, null, 2), "utf-8");
+  fs3.writeFileSync(getManifestPath(projectRoot), JSON.stringify(manifest, null, 2), "utf-8");
 }
 function recordInstall(components, installDir, projectRoot) {
   const manifest = readManifest(projectRoot);
@@ -288,7 +408,7 @@ function recordInstall(components, installDir, projectRoot) {
   for (const component of components) {
     manifest.components[component.slug] = {
       version: component.version,
-      installedAt: toForwardSlash(path2.join(installDir, component.slug)),
+      installedAt: toForwardSlash(path3.join(installDir, component.slug)),
       installedOn: today,
       files: component.files.map((f) => f.target)
     };
@@ -296,7 +416,7 @@ function recordInstall(components, installDir, projectRoot) {
   writeManifest(projectRoot, manifest);
 }
 function findOrphanedFiles(components, installDir, projectRoot, previousManifest) {
-  const compDir = path2.join(projectRoot, installDir);
+  const compDir = path3.join(projectRoot, installDir);
   const currentTargets = /* @__PURE__ */ new Set();
   for (const component of components) {
     for (const file of component.files) currentTargets.add(file.target);
@@ -310,10 +430,10 @@ function findOrphanedFiles(components, installDir, projectRoot, previousManifest
       if (currentTargets.has(target)) continue;
       if (seen.has(target)) continue;
       seen.add(target);
-      const absolutePath = path2.resolve(compDir, target);
-      const relativeFromRoot = path2.relative(projectRoot, absolutePath);
-      if (relativeFromRoot.startsWith("..") || path2.isAbsolute(relativeFromRoot)) continue;
-      if (!fs2.existsSync(absolutePath)) continue;
+      const absolutePath = path3.resolve(compDir, target);
+      const relativeFromRoot = path3.relative(projectRoot, absolutePath);
+      if (relativeFromRoot.startsWith("..") || path3.isAbsolute(relativeFromRoot)) continue;
+      if (!fs3.existsSync(absolutePath)) continue;
       orphans.push({ absolutePath, relativePath: relativeFromRoot, target });
     }
   }
@@ -321,26 +441,26 @@ function findOrphanedFiles(components, installDir, projectRoot, previousManifest
 }
 function removeFiles(files) {
   for (const file of files) {
-    if (fs2.existsSync(file.absolutePath)) {
-      fs2.rmSync(file.absolutePath, { force: true });
+    if (fs3.existsSync(file.absolutePath)) {
+      fs3.rmSync(file.absolutePath, { force: true });
     }
   }
 }
 
 // src/utils/install.ts
-import fs3 from "fs";
-import path3 from "path";
+import fs4 from "fs";
+import path4 from "path";
 import { spawnSync } from "child_process";
 var NPM_NAME_REGEX = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i;
 function isValidPackageName(name) {
   return NPM_NAME_REGEX.test(name);
 }
 function getMissingDependencies(components, projectRoot) {
-  const pkgPath = path3.join(projectRoot, "package.json");
-  if (!fs3.existsSync(pkgPath)) return [];
+  const pkgPath = path4.join(projectRoot, "package.json");
+  if (!fs4.existsSync(pkgPath)) return [];
   let installed = {};
   try {
-    const pkg = JSON.parse(fs3.readFileSync(pkgPath, "utf-8"));
+    const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf-8"));
     installed = {
       ...pkg.dependencies,
       ...pkg.devDependencies,
@@ -692,7 +812,7 @@ async function addCommand(slug, options = {}) {
     });
   }
   const targetComponent = resolvedComponents[resolvedComponents.length - 1];
-  const installPath = toForwardSlash(path4.join(componentInstallDir, targetComponent.slug));
+  const installPath = toForwardSlash(path5.join(componentInstallDir, targetComponent.slug));
   let orphans = [];
   try {
     const previousManifest = readManifest(projectRoot);
@@ -704,7 +824,7 @@ async function addCommand(slug, options = {}) {
     spinner.succeed(pc5.yellow("Dry-run: simulation completed. No files were written."));
     console.log(pc5.bold(pc5.yellow("\n[Dry Run] Files that would be created/modified:")));
     for (const file of filesToWrite) {
-      const status = fs4.existsSync(file.absolutePath) ? pc5.yellow("(exists, would overwrite)") : pc5.green("(new)");
+      const status = fs5.existsSync(file.absolutePath) ? pc5.yellow("(exists, would overwrite)") : pc5.green("(new)");
       console.log(`  ${pc5.cyan(file.relativePath)} ${status}`);
     }
     if (orphans.length > 0) {
@@ -746,6 +866,15 @@ async function addCommand(slug, options = {}) {
     logger.warn(`Failed to update vv-manifest.json: ${message}`);
     logger.warn("Component was installed but may not appear in 'npx vectorvesper info' or 'npx vectorvesper diff'.");
   }
+  try {
+    const installed = Object.keys(readManifest(projectRoot).components ?? {});
+    refreshAgentRules(projectRoot, {
+      targetDir: componentInstallDir,
+      alias: config.aliases.vv,
+      components: installed
+    });
+  } catch {
+  }
   spinner.succeed(pc5.green("Files written successfully!"));
   console.log(pc5.dim("\nCreated files:"));
   for (const file of filesToWrite) {
@@ -893,8 +1022,8 @@ async function updateCommand(slug, options = {}) {
 }
 
 // src/commands/remove.ts
-import fs5 from "fs";
-import path5 from "path";
+import fs6 from "fs";
+import path6 from "path";
 import pc7 from "picocolors";
 import { confirm as confirm3, isCancel as isCancel3 } from "@clack/prompts";
 async function removeCommand(slug, options = {}) {
@@ -935,15 +1064,15 @@ async function removeCommand(slug, options = {}) {
   }
   const projectInfo = detectProject();
   const installDir = resolveAlias(config.aliases.vv, projectInfo.hasSrcDir);
-  const baseDir = path5.join(projectRoot, installDir);
+  const baseDir = path6.join(projectRoot, installDir);
   const targets = entry.files ?? [];
-  const absoluteFiles = targets.map((t) => path5.resolve(baseDir, t));
+  const absoluteFiles = targets.map((t) => path6.resolve(baseDir, t));
   console.log(pc7.bold(pc7.cyan(`
 Remove ${slug}
 `)));
   console.log(pc7.dim("  The following files will be deleted:"));
   for (const f of absoluteFiles) {
-    console.log(`    ${fs5.existsSync(f) ? pc7.red("\u2212") : pc7.dim("\xB7")} ${pc7.cyan(path5.relative(projectRoot, f))}`);
+    console.log(`    ${fs6.existsSync(f) ? pc7.red("\u2212") : pc7.dim("\xB7")} ${pc7.cyan(path6.relative(projectRoot, f))}`);
   }
   if (!options.yes) {
     const answer = await confirm3({
@@ -958,19 +1087,19 @@ Remove ${slug}
   let deleted = 0;
   for (const f of absoluteFiles) {
     try {
-      if (fs5.existsSync(f)) {
-        fs5.rmSync(f);
+      if (fs6.existsSync(f)) {
+        fs6.rmSync(f);
         deleted++;
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      console.log(pc7.yellow(`  \u26A0\uFE0F  Could not delete ${path5.relative(projectRoot, f)}: ${message}`));
+      console.log(pc7.yellow(`  \u26A0\uFE0F  Could not delete ${path6.relative(projectRoot, f)}: ${message}`));
     }
   }
-  const componentDir = path5.resolve(baseDir, slug);
+  const componentDir = path6.resolve(baseDir, slug);
   try {
-    if (fs5.existsSync(componentDir) && fs5.readdirSync(componentDir).length === 0) {
-      fs5.rmdirSync(componentDir);
+    if (fs6.existsSync(componentDir) && fs6.readdirSync(componentDir).length === 0) {
+      fs6.rmdirSync(componentDir);
     }
   } catch {
   }
@@ -990,10 +1119,10 @@ Remove ${slug}
 }
 
 // src/commands/info.ts
-import fs6 from "fs";
-import path6 from "path";
+import fs7 from "fs";
+import path7 from "path";
 import pc8 from "picocolors";
-var CLI_VERSION = true ? "2.1.0" : "0.0.0-dev";
+var CLI_VERSION = true ? "2.3.0" : "0.0.0-dev";
 async function infoCommand() {
   console.log(pc8.bold(pc8.cyan("\nVector Vesper Diagnostics\n")));
   const projectInfo = detectProject();
@@ -1023,10 +1152,10 @@ async function infoCommand() {
   }
   console.log("");
   console.log(pc8.bold(pc8.white("Installed Components (vv-manifest.json):")));
-  const manifestPath = path6.join(process.cwd(), "vv-manifest.json");
-  if (fs6.existsSync(manifestPath)) {
+  const manifestPath = path7.join(process.cwd(), "vv-manifest.json");
+  if (fs7.existsSync(manifestPath)) {
     try {
-      const manifest = JSON.parse(fs6.readFileSync(manifestPath, "utf-8"));
+      const manifest = JSON.parse(fs7.readFileSync(manifestPath, "utf-8"));
       const components = manifest.components || {};
       const slugs = Object.keys(components);
       if (slugs.length === 0) {
@@ -1053,14 +1182,14 @@ async function infoCommand() {
 }
 
 // src/commands/diff.ts
-import fs7 from "fs";
-import path7 from "path";
+import fs8 from "fs";
+import path8 from "path";
 import pc9 from "picocolors";
 import ora4 from "ora";
 async function diffCommand(slug) {
   const projectRoot = process.cwd();
-  const manifestPath = path7.join(projectRoot, "vv-manifest.json");
-  if (!fs7.existsSync(manifestPath)) {
+  const manifestPath = path8.join(projectRoot, "vv-manifest.json");
+  if (!fs8.existsSync(manifestPath)) {
     console.log(pc9.yellow(`
 \u26A0\uFE0F  No vv-manifest.json found in this directory.`));
     console.log(`\u{1F449} Add components first using ${pc9.bold(pc9.cyan("npx vectorvesper add <slug>"))}
@@ -1069,7 +1198,7 @@ async function diffCommand(slug) {
   }
   let manifest;
   try {
-    manifest = JSON.parse(fs7.readFileSync(manifestPath, "utf-8"));
+    manifest = JSON.parse(fs8.readFileSync(manifestPath, "utf-8"));
   } catch {
     console.error(pc9.red(`\u274C Error reading vv-manifest.json: Invalid JSON format.`));
     process.exit(1);
@@ -1291,7 +1420,7 @@ async function whoamiCommand() {
 }
 
 // src/index.ts
-var version = true ? "2.1.0" : "0.0.0-dev";
+var version = true ? "2.3.0" : "0.0.0-dev";
 var program = new Command();
 program.name("vv").description("Vector Vesper CLI \u2014 add visual components to your React project").version(version).option("--verbose", "Show detailed debug output").hook("preAction", (thisCommand) => {
   const opts = thisCommand.opts();
@@ -1299,7 +1428,7 @@ program.name("vv").description("Vector Vesper CLI \u2014 add visual components t
     setVerbose(true);
   }
 });
-program.command("init").description("Initialize Vector Vesper configuration in your project").option("-y, --yes", "Accept all default prompts based on project detection").action(async (options) => {
+program.command("init").description("Initialize Vector Vesper configuration in your project").option("-y, --yes", "Accept all default prompts based on project detection").option("--no-agent-rules", "Skip writing the AGENTS.md block for AI coding assistants").action(async (options) => {
   await initCommand(options);
 });
 program.command("list").description("List all available components in the registry").action(async () => {
@@ -1329,10 +1458,14 @@ program.command("logout", { hidden: true }).description("Clear stored license cr
 program.command("whoami", { hidden: true }).description("Show current authentication status").action(async () => {
   await whoamiCommand();
 });
-program.command("mcp [action]").description("Run as an MCP server (stdio) for AI coding agents. `vv mcp status` checks the setup.").option("--stdio", "Force server mode even from an interactive terminal").action(async (action, options) => {
-  const { mcpCommand } = await import("./mcp-OURIIFET.js");
-  await mcpCommand(action, options);
-});
+program.command("mcp [action] [client]").description(
+  "Run as an MCP server (stdio) for AI coding agents. `vv mcp install` wires it into your editor; `vv mcp status` checks the setup."
+).option("--stdio", "Force server mode even from an interactive terminal").option("-g, --global", "Write user-level config instead of project-level (install)").action(
+  async (action, client, options) => {
+    const { mcpCommand } = await import("./mcp-H5YYBZ5V.js");
+    await mcpCommand(action, { ...options, client });
+  }
+);
 process.on("unhandledRejection", (error) => {
   console.error("An unexpected error occurred:", error instanceof Error ? error.message : error);
   process.exit(1);