vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/runLink.js

@@ -0,0 +1,785 @@
+/**
+ * vibecheck link - Instant Project Binding
+ *
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * ZERO QUESTIONS. MAXIMUM DETECTION. UNDER 10 SECONDS.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * Goal: "Project Bound" receipt in <10 seconds with smart next step suggestion.
+ *
+ * @version 1.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { parseGlobalFlags, shouldShowBanner } = require("./lib/global-flags");
+const { EXIT } = require("./lib/exit-codes");
+
+// Reuse existing detection modules
+const { detectPackageManager } = require("./lib/detect");
+const { detectMonorepo } = require("./context/monorepo");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const VERSION = "1.0.0";
+const CLI_VERSION = require("../../package.json").version || "4.0.0";
+const SCHEMA = "https://vibecheck.dev/schemas/project.v1.json";
+
+// ANSI colors (minimal, fast)
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  red: "\x1b[31m",
+  gray: "\x1b[90m",
+};
+
+const sym = {
+  success: "✓",
+  warning: "⚠",
+  error: "✗",
+  arrow: "→",
+  dot: "•",
+  link: "🔗",
+};
+
+// Link-specific exit codes
+const LINK_EXIT = {
+  SUCCESS: 0,
+  PARTIAL: 1,
+  USER_ERROR: 3,
+  NOT_FOUND: 4,
+  INTERNAL_ERROR: 10,
+  PERMISSION_DENIED: 11,
+  ALREADY_LINKED: 12,
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PROJECT ROOT DETECTION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function findProjectRoot(startDir) {
+  let current = path.resolve(startDir);
+  const root = path.parse(current).root;
+  let levels = 0;
+  const maxLevels = 10;
+
+  while (current !== root && levels < maxLevels) {
+    // package.json is the definitive marker
+    if (fs.existsSync(path.join(current, "package.json"))) {
+      return current;
+    }
+    // .git is acceptable fallback (monorepo root)
+    if (fs.existsSync(path.join(current, ".git"))) {
+      return current;
+    }
+    current = path.dirname(current);
+    levels++;
+  }
+
+  return null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// RUNTIME DETECTION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function detectRuntime(projectRoot) {
+  const sources = [
+    { file: ".nvmrc", parse: (content) => content.trim().replace(/^v/, "") },
+    { file: ".node-version", parse: (content) => content.trim().replace(/^v/, "") },
+    {
+      file: ".tool-versions",
+      parse: (content) => {
+        const match = content.match(/nodejs\s+(\S+)/);
+        return match ? match[1] : null;
+      },
+    },
+  ];
+
+  for (const { file, parse } of sources) {
+    const filePath = path.join(projectRoot, file);
+    if (fs.existsSync(filePath)) {
+      try {
+        const version = parse(fs.readFileSync(filePath, "utf-8"));
+        if (version) return { version, source: file };
+      } catch {
+        // Continue to next source
+      }
+    }
+  }
+
+  // Fallback to current process version
+  return {
+    version: process.version.replace(/^v/, ""),
+    source: "process",
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// FRAMEWORK DETECTION (Fast, dependency-based)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function detectFramework(projectRoot) {
+  const pkgPath = path.join(projectRoot, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    return { name: "node", confidence: "low", version: null };
+  }
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    // Priority order (most specific first)
+    const frameworks = [
+      { key: "next", name: "Next.js", configs: ["next.config.js", "next.config.mjs", "next.config.ts"] },
+      { key: "@remix-run/react", name: "Remix", configs: ["remix.config.js"] },
+      { key: "@sveltejs/kit", name: "SvelteKit", configs: ["svelte.config.js"] },
+      { key: "nuxt", name: "Nuxt", configs: ["nuxt.config.ts", "nuxt.config.js"] },
+      { key: "@nestjs/core", name: "NestJS", configs: [] },
+      { key: "fastify", name: "Fastify", configs: [] },
+      { key: "express", name: "Express", configs: [] },
+      { key: "hono", name: "Hono", configs: [] },
+      { key: "react", name: "React", configs: ["vite.config.ts", "vite.config.js"] },
+      { key: "vue", name: "Vue", configs: ["vite.config.ts", "vite.config.js"] },
+      { key: "svelte", name: "Svelte", configs: ["vite.config.ts", "vite.config.js"] },
+    ];
+
+    for (const fw of frameworks) {
+      if (deps[fw.key]) {
+        const version = deps[fw.key].replace(/[\^~]/, "");
+        const hasConfig = fw.configs.some((cfg) => fs.existsSync(path.join(projectRoot, cfg)));
+        return {
+          name: fw.name,
+          key: fw.key.replace(/^@/, "").replace(/\//g, "-"),
+          version,
+          confidence: hasConfig ? "high" : "medium",
+        };
+      }
+    }
+
+    // Check for TypeScript project
+    if (deps.typescript) {
+      return { name: "Node.js", key: "node", version: null, confidence: "medium", typescript: true };
+    }
+
+    return { name: "Node.js", key: "node", version: null, confidence: "low" };
+  } catch {
+    return { name: "Node.js", key: "node", version: null, confidence: "low" };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CI/CD DETECTION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function detectCI(projectRoot) {
+  const ciSystems = [
+    { path: ".github/workflows", name: "GitHub Actions", key: "github" },
+    { path: ".gitlab-ci.yml", name: "GitLab CI", key: "gitlab" },
+    { path: ".circleci/config.yml", name: "CircleCI", key: "circleci" },
+    { path: "Jenkinsfile", name: "Jenkins", key: "jenkins" },
+    { path: ".travis.yml", name: "Travis CI", key: "travis" },
+    { path: "azure-pipelines.yml", name: "Azure Pipelines", key: "azure" },
+    { path: "bitbucket-pipelines.yml", name: "Bitbucket Pipelines", key: "bitbucket" },
+  ];
+
+  const detected = [];
+  for (const ci of ciSystems) {
+    const fullPath = path.join(projectRoot, ci.path);
+    if (fs.existsSync(fullPath)) {
+      detected.push({ name: ci.name, key: ci.key });
+    }
+  }
+
+  // Check if vibecheck is already in CI
+  let hasVibecheckCI = false;
+  const ghWorkflowsDir = path.join(projectRoot, ".github", "workflows");
+  if (fs.existsSync(ghWorkflowsDir)) {
+    try {
+      const workflows = fs.readdirSync(ghWorkflowsDir);
+      for (const wf of workflows) {
+        if (wf.endsWith(".yml") || wf.endsWith(".yaml")) {
+          const content = fs.readFileSync(path.join(ghWorkflowsDir, wf), "utf-8");
+          if (content.includes("vibecheck")) {
+            hasVibecheckCI = true;
+            break;
+          }
+        }
+      }
+    } catch {
+      // Ignore read errors
+    }
+  }
+
+  return {
+    detected: detected.length > 0,
+    systems: detected,
+    hasVibecheckCI,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PERMISSION CHECK
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function checkPermissions(targetDir) {
+  const vibecheckDir = path.join(targetDir, ".vibecheck");
+  const testFile = path.join(vibecheckDir, ".write-test");
+  const warnings = [];
+
+  try {
+    // Ensure directory exists
+    if (!fs.existsSync(vibecheckDir)) {
+      fs.mkdirSync(vibecheckDir, { recursive: true });
+    }
+
+    // Test write
+    fs.writeFileSync(testFile, "vibecheck-permission-test");
+    fs.unlinkSync(testFile);
+
+    return { ok: true, warnings };
+  } catch (e) {
+    const isWindows = process.platform === "win32";
+    const fixes = isWindows
+      ? [
+          `icacls "${vibecheckDir}" /grant "%USERNAME%":F`,
+          `Remove-Item "${vibecheckDir}" -Recurse -Force; vibecheck link`,
+        ]
+      : [
+          `chmod 755 "${targetDir}"`,
+          `sudo chown -R $USER "${vibecheckDir}"`,
+          `rm -rf "${vibecheckDir}" && vibecheck link`,
+        ];
+
+    return {
+      ok: false,
+      error: e.code === "EACCES" || e.code === "EPERM" ? "PERMISSION_DENIED" : e.code,
+      message: e.message,
+      warnings,
+      fixes,
+    };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MANIFEST HASH GENERATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function generateManifestHash(projectRoot, detection) {
+  const hash = crypto.createHash("sha256");
+  const inputs = {};
+
+  // Hash package.json
+  const pkgPath = path.join(projectRoot, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    const pkgContent = fs.readFileSync(pkgPath);
+    hash.update(pkgContent);
+    inputs.packageJson = "sha256:" + crypto.createHash("sha256").update(pkgContent).digest("hex").slice(0, 12);
+  }
+
+  // Hash lockfile
+  const lockfiles = ["pnpm-lock.yaml", "yarn.lock", "package-lock.json", "bun.lockb"];
+  for (const lf of lockfiles) {
+    const lfPath = path.join(projectRoot, lf);
+    if (fs.existsSync(lfPath)) {
+      const lfContent = fs.readFileSync(lfPath);
+      hash.update(lfContent);
+      inputs.lockfile = "sha256:" + crypto.createHash("sha256").update(lfContent).digest("hex").slice(0, 12);
+      inputs.lockfileName = lf;
+      break;
+    }
+  }
+
+  // Hash detection result
+  const detectionStr = JSON.stringify(detection);
+  hash.update(detectionStr);
+  inputs.detection = "sha256:" + crypto.createHash("sha256").update(detectionStr).digest("hex").slice(0, 12);
+
+  return {
+    hash: "sha256:" + hash.digest("hex").slice(0, 16),
+    inputs,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SMART NEXT STEP
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function getNextCommand(detection, state) {
+  // 1. Permission issues → doctor
+  if (state.permissionWarnings && state.permissionWarnings.length > 0) {
+    return { cmd: "vibecheck doctor --fix", reason: "fix permission issues" };
+  }
+
+  // 2. Missing lockfile → doctor
+  if (!detection.manifest?.inputs?.lockfile) {
+    return { cmd: "vibecheck doctor", reason: "no lockfile detected" };
+  }
+
+  // 3. No CI detected → suggest CI setup
+  if (!detection.ci?.detected) {
+    return { cmd: "vibecheck packs ci", reason: "add CI/CD workflow" };
+  }
+
+  // 4. CI exists but no vibecheck in it → suggest adding
+  if (detection.ci?.detected && !detection.ci?.hasVibecheckCI) {
+    return { cmd: "vibecheck packs ci", reason: "add vibecheck to CI" };
+  }
+
+  // 5. Has legacy config → suggest doctor
+  if (state.hasLegacyConfig) {
+    return { cmd: "vibecheck doctor --migrate", reason: "migrate legacy config" };
+  }
+
+  // 6. Default → audit (happy path)
+  return { cmd: "vibecheck audit", reason: "run your first scan" };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// FILE WRITING
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function writeProjectFiles(projectRoot, projectName, detection, manifest) {
+  const created = [];
+  const vibecheckDir = path.join(projectRoot, ".vibecheck");
+
+  // Ensure directory exists
+  if (!fs.existsSync(vibecheckDir)) {
+    fs.mkdirSync(vibecheckDir, { recursive: true });
+  }
+
+  // 1. Write project.json (the receipt)
+  const projectJson = {
+    $schema: SCHEMA,
+    version: VERSION,
+    linkedAt: new Date().toISOString(),
+    linkedBy: `vibecheck@${CLI_VERSION}`,
+    project: {
+      name: projectName,
+      root: projectRoot,
+    },
+    detection: {
+      packageManager: detection.packageManager,
+      framework: detection.framework?.name || "Node.js",
+      frameworkKey: detection.framework?.key || "node",
+      frameworkVersion: detection.framework?.version || null,
+      runtime: "node",
+      runtimeVersion: detection.runtime?.version || process.version.replace(/^v/, ""),
+      monorepo: detection.monorepo?.isMonorepo
+        ? {
+            type: detection.monorepo.type,
+            workspaces: detection.monorepo.workspaces?.map((w) => w.path) || [],
+            packages: detection.monorepo.workspaces?.length || 0,
+            tools: detection.monorepo.tools || [],
+          }
+        : null,
+      ci: detection.ci?.detected
+        ? {
+            systems: detection.ci.systems?.map((s) => s.key) || [],
+            hasVibecheckCI: detection.ci.hasVibecheckCI || false,
+          }
+        : null,
+    },
+    manifestHash: manifest.hash,
+  };
+
+  fs.writeFileSync(path.join(vibecheckDir, "project.json"), JSON.stringify(projectJson, null, 2));
+  created.push(".vibecheck/project.json");
+
+  // 2. Write manifest.json (fingerprint)
+  const manifestJson = {
+    hash: manifest.hash,
+    computed: new Date().toISOString(),
+    inputs: manifest.inputs,
+  };
+
+  fs.writeFileSync(path.join(vibecheckDir, "manifest.json"), JSON.stringify(manifestJson, null, 2));
+  created.push(".vibecheck/manifest.json");
+
+  // 3. Write .gitignore for vibecheck outputs
+  const gitignorePath = path.join(vibecheckDir, ".gitignore");
+  if (!fs.existsSync(gitignorePath)) {
+    const gitignoreContent = `# VibeCheck generated outputs (safe to ignore)
+results/
+runs/
+checkpoints/
+*.log
+.write-test
+`;
+    fs.writeFileSync(gitignorePath, gitignoreContent);
+    created.push(".vibecheck/.gitignore");
+  }
+
+  return created;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// OUTPUT FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function formatDetectionSummary(detection) {
+  const parts = [];
+
+  // Framework
+  if (detection.framework?.name && detection.framework.name !== "Node.js") {
+    parts.push(detection.framework.name);
+  }
+
+  // Package manager
+  if (detection.packageManager && detection.packageManager !== "npm") {
+    parts.push(detection.packageManager);
+  }
+
+  // Runtime
+  if (detection.runtime?.version) {
+    const majorVersion = detection.runtime.version.split(".")[0];
+    parts.push(`Node ${majorVersion}`);
+  }
+
+  // Monorepo
+  if (detection.monorepo?.isMonorepo) {
+    const count = detection.monorepo.workspaces?.length || 0;
+    parts.push(`${detection.monorepo.type} monorepo (${count} packages)`);
+  }
+
+  return parts.length > 0 ? parts.join(" + ") : "Node.js";
+}
+
+function outputSuccess(projectName, detection, next, elapsed, opts) {
+  const summary = formatDetectionSummary(detection);
+
+  if (!opts.quiet) {
+    console.log();
+    console.log(`${c.green}${sym.success}${c.reset} ${c.bold}Project bound:${c.reset} ${projectName} ${c.dim}(${summary})${c.reset}`);
+    console.log(`  ${c.cyan}${sym.arrow}${c.reset} Next: ${c.cyan}${next.cmd}${c.reset}`);
+
+    if (opts.verbose) {
+      console.log();
+      console.log(`${c.dim}  Detection: ${elapsed}ms${c.reset}`);
+      console.log(`${c.dim}  Manifest: ${detection.manifest?.hash || "unknown"}${c.reset}`);
+    }
+
+    console.log();
+  }
+
+  return LINK_EXIT.SUCCESS;
+}
+
+function outputWarning(projectName, detection, warnings, next, elapsed, opts) {
+  const summary = formatDetectionSummary(detection);
+
+  if (!opts.quiet) {
+    console.log();
+    console.log(`${c.green}${sym.success}${c.reset} ${c.bold}Project bound:${c.reset} ${projectName} ${c.dim}(${summary})${c.reset}`);
+
+    for (const warn of warnings) {
+      console.log(`  ${c.yellow}${sym.warning}${c.reset} ${warn}`);
+    }
+
+    console.log(`  ${c.cyan}${sym.arrow}${c.reset} Next: ${c.cyan}${next.cmd}${c.reset}`);
+    console.log();
+  }
+
+  return LINK_EXIT.PARTIAL;
+}
+
+function outputJson(result) {
+  console.log(JSON.stringify(result, null, 2));
+  return result.success ? LINK_EXIT.SUCCESS : LINK_EXIT.PARTIAL;
+}
+
+function errorNotAProject(opts) {
+  if (opts.json) {
+    return outputJson({
+      success: false,
+      error: "NOT_A_PROJECT",
+      message: "No package.json found",
+      fixes: ["cd /path/to/your/project && vibecheck link", "npm init -y && vibecheck link"],
+    });
+  }
+
+  console.log();
+  console.log(`${c.red}${sym.error}${c.reset} ${c.bold}No package.json found${c.reset}`);
+  console.log();
+  console.log(`  This doesn't look like a JavaScript/TypeScript project.`);
+  console.log();
+  console.log(`  ${c.bold}Fix:${c.reset}`);
+  console.log(`    ${c.cyan}cd /path/to/your/project && vibecheck link${c.reset}`);
+  console.log(`    ${c.cyan}npm init -y && vibecheck link${c.reset}  ${c.dim}# Create new project${c.reset}`);
+  console.log();
+
+  return LINK_EXIT.NOT_FOUND;
+}
+
+function errorAlreadyLinked(projectJsonPath, opts) {
+  let linkedAt = "unknown";
+  try {
+    const content = JSON.parse(fs.readFileSync(projectJsonPath, "utf-8"));
+    if (content.linkedAt) {
+      const date = new Date(content.linkedAt);
+      const now = new Date();
+      const diffMs = now - date;
+      const diffHours = Math.floor(diffMs / (1000 * 60 * 60));
+      const diffDays = Math.floor(diffHours / 24);
+
+      if (diffDays > 0) {
+        linkedAt = `${diffDays} day${diffDays > 1 ? "s" : ""} ago`;
+      } else if (diffHours > 0) {
+        linkedAt = `${diffHours} hour${diffHours > 1 ? "s" : ""} ago`;
+      } else {
+        const diffMins = Math.floor(diffMs / (1000 * 60));
+        linkedAt = `${diffMins} minute${diffMins !== 1 ? "s" : ""} ago`;
+      }
+    }
+  } catch {
+    // Ignore parse errors
+  }
+
+  if (opts.json) {
+    return outputJson({
+      success: false,
+      error: "ALREADY_LINKED",
+      message: `Project already linked (${linkedAt})`,
+      linkedAt,
+      fixes: ["vibecheck link --force", "vibecheck doctor"],
+    });
+  }
+
+  console.log();
+  console.log(`${c.yellow}${sym.warning}${c.reset} ${c.bold}Project already linked${c.reset} ${c.dim}(${linkedAt})${c.reset}`);
+  console.log();
+  console.log(`  To re-link: ${c.cyan}vibecheck link --force${c.reset}`);
+  console.log(`  To check:   ${c.cyan}vibecheck doctor${c.reset}`);
+  console.log();
+
+  return LINK_EXIT.ALREADY_LINKED;
+}
+
+function errorPermissionDenied(permCheck, opts) {
+  if (opts.json) {
+    return outputJson({
+      success: false,
+      error: "PERMISSION_DENIED",
+      message: permCheck.message,
+      fixes: permCheck.fixes,
+    });
+  }
+
+  console.log();
+  console.log(`${c.red}${sym.error}${c.reset} ${c.bold}Cannot write to .vibecheck/${c.reset}`);
+  console.log();
+  console.log(`  ${c.bold}Fix:${c.reset} Run one of these commands:`);
+  for (const fix of permCheck.fixes) {
+    console.log(`    ${c.cyan}${fix}${c.reset}`);
+  }
+  console.log();
+
+  return LINK_EXIT.PERMISSION_DENIED;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ARGS PARSER
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function parseArgs(args) {
+  const { flags: globalFlags, cleanArgs } = parseGlobalFlags(args);
+
+  const opts = {
+    path: globalFlags.path || ".",
+    force: false,
+    dryRun: false,
+    json: globalFlags.json || false,
+    verbose: globalFlags.verbose || false,
+    quiet: globalFlags.quiet || false,
+    noBanner: globalFlags.noBanner || false,
+    help: globalFlags.help || false,
+  };
+
+  for (let i = 0; i < cleanArgs.length; i++) {
+    const arg = cleanArgs[i];
+    if (arg === "--force" || arg === "-f") opts.force = true;
+    if (arg === "--dry-run" || arg === "--dryrun") opts.dryRun = true;
+    if (arg.startsWith("--path=")) opts.path = arg.split("=")[1];
+    if ((arg === "--path" || arg === "-p") && cleanArgs[i + 1]) opts.path = cleanArgs[++i];
+  }
+
+  return opts;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELP
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function printHelp() {
+  console.log(`
+${c.bold}vibecheck link${c.reset} - Instant project binding
+
+${c.bold}Usage:${c.reset}
+  vibecheck link [options]
+
+${c.bold}Options:${c.reset}
+  ${c.cyan}--path, -p <dir>${c.reset}    Project path ${c.dim}(default: current directory)${c.reset}
+  ${c.cyan}--force, -f${c.reset}         Re-link even if already linked
+  ${c.cyan}--dry-run${c.reset}           Preview without writing files
+  ${c.cyan}--json${c.reset}              Output as JSON (CI-friendly)
+  ${c.cyan}--verbose, -v${c.reset}       Show detection details
+  ${c.cyan}--quiet, -q${c.reset}         Suppress all output except errors
+  ${c.cyan}--help, -h${c.reset}          Show this help
+
+${c.bold}What it does:${c.reset}
+  ${c.dim}1.${c.reset} Finds project root (package.json or .git)
+  ${c.dim}2.${c.reset} Detects: package manager, framework, runtime, monorepo, CI
+  ${c.dim}3.${c.reset} Creates .vibecheck/project.json (the "bound" receipt)
+  ${c.dim}4.${c.reset} Generates manifest hash for change detection
+  ${c.dim}5.${c.reset} Suggests smart next command based on findings
+
+${c.bold}Examples:${c.reset}
+  ${c.cyan}vibecheck link${c.reset}                  # Bind current project
+  ${c.cyan}vibecheck link -p ~/my-app${c.reset}      # Bind specific project
+  ${c.cyan}vibecheck link --force${c.reset}          # Re-bind existing project
+  ${c.cyan}vibecheck link --json${c.reset}           # JSON output for CI
+
+${c.bold}Exit Codes:${c.reset}
+  ${c.green}0${c.reset}   Success - project bound
+  ${c.yellow}1${c.reset}   Partial - bound with warnings
+  ${c.red}3${c.reset}   User error - invalid arguments
+  ${c.red}4${c.reset}   Not found - no package.json
+  ${c.red}11${c.reset}  Permission denied - can't write to .vibecheck/
+  ${c.red}12${c.reset}  Already linked - use --force to re-link
+`);
+  return 0;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAIN
+// ═══════════════════════════════════════════════════════════════════════════════
+
+async function runLink(args) {
+  const opts = parseArgs(args);
+
+  if (opts.help) {
+    return printHelp();
+  }
+
+  const startTime = Date.now();
+  const warnings = [];
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // 1. Find project root
+  // ─────────────────────────────────────────────────────────────────────────────
+  const projectRoot = findProjectRoot(opts.path);
+  if (!projectRoot) {
+    return errorNotAProject(opts);
+  }
+
+  const projectName = path.basename(projectRoot);
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // 2. Check if already linked
+  // ─────────────────────────────────────────────────────────────────────────────
+  const projectJsonPath = path.join(projectRoot, ".vibecheck", "project.json");
+  if (fs.existsSync(projectJsonPath) && !opts.force) {
+    return errorAlreadyLinked(projectJsonPath, opts);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // 3. Check permissions
+  // ─────────────────────────────────────────────────────────────────────────────
+  const permCheck = checkPermissions(projectRoot);
+  if (!permCheck.ok) {
+    return errorPermissionDenied(permCheck, opts);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // 4. Run detection pipeline (the fast part)
+  // ─────────────────────────────────────────────────────────────────────────────
+  const detection = {
+    packageManager: detectPackageManager(projectRoot),
+    framework: detectFramework(projectRoot),
+    runtime: detectRuntime(projectRoot),
+    monorepo: detectMonorepo(projectRoot),
+    ci: detectCI(projectRoot),
+  };
+
+  // Framework detection warnings
+  if (detection.framework?.confidence === "low") {
+    warnings.push("Could not detect framework (using Node.js defaults)");
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // 5. Generate manifest hash
+  // ─────────────────────────────────────────────────────────────────────────────
+  const manifest = generateManifestHash(projectRoot, detection);
+  detection.manifest = manifest;
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // 6. Write files (unless dry-run)
+  // ─────────────────────────────────────────────────────────────────────────────
+  let created = [];
+  if (!opts.dryRun) {
+    created = writeProjectFiles(projectRoot, projectName, detection, manifest);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // 7. Determine next command
+  // ─────────────────────────────────────────────────────────────────────────────
+  const state = {
+    permissionWarnings: permCheck.warnings,
+    hasLegacyConfig:
+      fs.existsSync(path.join(projectRoot, ".vibecheckrc")) ||
+      fs.existsSync(path.join(projectRoot, ".vibecheckrc.json")),
+  };
+  const next = getNextCommand(detection, state);
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // 8. Output
+  // ─────────────────────────────────────────────────────────────────────────────
+  const elapsed = Date.now() - startTime;
+
+  if (opts.json) {
+    return outputJson({
+      success: true,
+      elapsed,
+      project: {
+        name: projectName,
+        root: projectRoot,
+        hash: manifest.hash,
+      },
+      detection: {
+        packageManager: detection.packageManager,
+        framework: detection.framework?.name || "Node.js",
+        frameworkVersion: detection.framework?.version || null,
+        runtime: `node@${detection.runtime?.version || "unknown"}`,
+        monorepo: detection.monorepo?.isMonorepo
+          ? { type: detection.monorepo.type, packages: detection.monorepo.workspaces?.length || 0 }
+          : null,
+        ci: detection.ci?.detected ? { systems: detection.ci.systems?.map((s) => s.key) || [] } : null,
+      },
+      created,
+      warnings,
+      nextCommand: next.cmd,
+      dryRun: opts.dryRun,
+    });
+  }
+
+  if (warnings.length > 0) {
+    return outputWarning(projectName, detection, warnings, next, elapsed, opts);
+  }
+
+  return outputSuccess(projectName, detection, next, elapsed, opts);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = { runLink };