@ahmednawaz/crank 0.1.2

package/lib/init.js

@@ -0,0 +1,435 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  exists,
+  readJson,
+  writeJson,
+  detectEnvironment,
+  findViteConfig
+} = require('./detect');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const { resolveUrls } = require('./urls');
+
+function ensureGitignore(projectRoot) {
+  const file = path.join(projectRoot, '.gitignore');
+  const lines = [
+    '.env',
+    '.env.local',
+    '.crank/secrets.json',
+    '.crank/runtime.json',
+    'node_modules/'
+  ];
+  let current = exists(file) ? fs.readFileSync(file, 'utf8') : '';
+  let changed = false;
+  for (const line of lines) {
+    if (!current.split(/\r?\n/).includes(line)) {
+      current = `${current.trimEnd()}\n${line}\n`;
+      changed = true;
+    }
+  }
+  if (changed || !exists(file)) {
+    fs.writeFileSync(file, current.endsWith('\n') ? current : `${current}\n`);
+  }
+}
+
+function mcpServerEntry(projectRoot) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const companionUrl = `http://127.0.0.1:${process.env.CRANK_PORT || '3344'}`;
+  const envBlock = {
+    CRANK_COMPANION_URL: companionUrl,
+    CRANK_MCP_MODE: 'stdio',
+    CRANK_PROJECT_ROOT: root
+  };
+
+  const localBin = path.join(root, 'node_modules', 'crank', 'bin', 'crank.js');
+  if (exists(localBin)) {
+    return {
+      command: 'node',
+      args: [localBin, 'mcp'],
+      env: envBlock
+    };
+  }
+
+  // Retune-style — npx resolves @ahmednawaz/crank from npm (no git clone).
+  return {
+    command: 'npx',
+    args: ['-y', '@ahmednawaz/crank', 'mcp'],
+    env: envBlock
+  };
+}
+
+function mergeMcpServers(file, serverKey = 'crank', projectRoot) {
+  const existing = readJson(file, { mcpServers: {} }) || { mcpServers: {} };
+  if (!existing.mcpServers) {
+    existing.mcpServers = {};
+  }
+  existing.mcpServers[serverKey] = mcpServerEntry(projectRoot);
+  writeJson(file, existing);
+  return file;
+}
+
+/** VS Code / Copilot style uses `servers` in some versions; write both shapes safely. */
+function mergeVsCodeMcp(file, projectRoot) {
+  const existing = readJson(file, {}) || {};
+  if (!existing.servers && !existing.mcpServers) {
+    existing.servers = {};
+  }
+  const entryBase = mcpServerEntry(projectRoot);
+  const entry = {
+    type: 'stdio',
+    command: entryBase.command,
+    args: entryBase.args,
+    env: entryBase.env
+  };
+  if (existing.servers) {
+    existing.servers.crank = entry;
+  } else {
+    existing.mcpServers = existing.mcpServers || {};
+    existing.mcpServers.crank = entryBase;
+  }
+  writeJson(file, existing);
+  return file;
+}
+
+function patchViteConfig(projectRoot) {
+  const configPath = findViteConfig(projectRoot);
+  if (!configPath) {
+    return { patched: false, reason: 'no-vite-config' };
+  }
+  let source = fs.readFileSync(configPath, 'utf8');
+  if (/(\bcrank)\s*\(/.test(source) && /plugins/.test(source)) {
+    return { patched: false, reason: 'already-present', file: configPath };
+  }
+
+  // Copy plugin into the project so Vite can resolve a relative import everywhere.
+  const localPluginDir = path.join(projectRoot, '.crank');
+  fs.mkdirSync(localPluginDir, { recursive: true });
+  const localPlugin = path.join(localPluginDir, 'vite-plugin.cjs');
+  fs.copyFileSync(path.join(PACKAGE_ROOT, 'vite.js'), localPlugin);
+
+  const rel = './.crank/vite-plugin.cjs';
+  const isEsm =
+    configPath.endsWith('.mjs') ||
+    (/^import\s/m.test(source) && !configPath.endsWith('.cjs'));
+  const importLine = isEsm
+    ? `import { crank } from '${rel}';\n`
+    : `const { crank } = require('${rel}');\n`;
+
+  if (!/vite-plugin\.cjs|from ['"]crank/.test(source)) {
+    source = importLine + source;
+  }
+
+  if (/plugins\s*:\s*\[\s*\]/.test(source)) {
+    source = source.replace(/plugins\s*:\s*\[\s*\]/, 'plugins: [crank()]');
+  } else if (/plugins\s*:\s*\[/.test(source)) {
+    source = source.replace(/plugins\s*:\s*\[/, 'plugins: [crank(), ');
+  } else if (/defineConfig\s*\(\s*\{/.test(source)) {
+    source = source.replace(
+      /defineConfig\s*\(\s*\{/,
+      'defineConfig({\n  plugins: [crank()],'
+    );
+  } else if (/export\s+default\s+\{/.test(source)) {
+    source = source.replace(
+      /export\s+default\s+\{/,
+      'export default {\n  plugins: [crank()],'
+    );
+  } else if (/module\.exports\s*=\s*\{/.test(source)) {
+    source = source.replace(
+      /module\.exports\s*=\s*\{/,
+      'module.exports = {\n  plugins: [crank()],'
+    );
+  } else {
+    return { patched: false, reason: 'unrecognized-vite-shape', file: configPath };
+  }
+
+  fs.writeFileSync(configPath, source);
+  return { patched: true, file: configPath, plugin: localPlugin };
+}
+
+function writeProjectEnvExample(projectRoot) {
+  const dest = path.join(projectRoot, '.env.crank.example');
+  const src = path.join(PACKAGE_ROOT, '.env.example');
+  if (exists(src) && !exists(dest)) {
+    fs.copyFileSync(src, dest);
+  }
+  // If package root has a real .env (dev machine), do NOT copy secrets into target repos.
+}
+
+/**
+ * Install crank-apply-changes skill like `npx retune setup`:
+ * user-level ~/.cursor/skills + project .cursor/skills when present.
+ */
+function installCrankSkill(projectRoot, results) {
+  const skillSrc = path.join(PACKAGE_ROOT, 'skill', 'SKILL.md');
+  if (!exists(skillSrc)) {
+    results.skillError = 'skill/SKILL.md missing from crank package';
+    return;
+  }
+  const targets = [];
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  if (home) {
+    targets.push(
+      path.join(home, '.cursor', 'skills', 'crank-apply-changes', 'SKILL.md')
+    );
+    targets.push(
+      path.join(home, '.claude', 'skills', 'crank-apply-changes', 'SKILL.md')
+    );
+  }
+  if (projectRoot) {
+    targets.push(
+      path.join(
+        projectRoot,
+        '.cursor',
+        'skills',
+        'crank-apply-changes',
+        'SKILL.md'
+      )
+    );
+  }
+  for (const dest of targets) {
+    try {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(skillSrc, dest);
+      results.wrote.push(dest);
+    } catch (err) {
+      results.skillError = (results.skillError ? results.skillError + '; ' : '') +
+        `${dest}: ${err.message}`;
+    }
+  }
+}
+
+/**
+ * Also merge crank into user ~/.cursor/mcp.json (Retune setup parity).
+ */
+function mergeUserCursorMcp(projectRoot, results) {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  if (!home) return;
+  const userMcp = path.join(home, '.cursor', 'mcp.json');
+  try {
+    if (!exists(path.dirname(userMcp))) {
+      fs.mkdirSync(path.dirname(userMcp), { recursive: true });
+    }
+    mergeMcpServers(userMcp, 'crank', projectRoot);
+    results.wrote.push(userMcp);
+  } catch (err) {
+    results.userMcpError = err.message;
+  }
+}
+
+/**
+ * Retune-style: add crank to devDependencies so `npx crank` works with no path.
+ */
+function ensureCrankDependency(projectRoot, results) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (!exists(pkgPath)) {
+    return;
+  }
+  if (path.resolve(projectRoot) === path.resolve(PACKAGE_ROOT)) {
+    return;
+  }
+
+  const pkg = readJson(pkgPath, {});
+  const crankPkg = readJson(path.join(PACKAGE_ROOT, 'package.json'), {});
+  pkg.devDependencies = pkg.devDependencies || {};
+
+  let spec;
+  if (process.env.CRANK_NPM_SPEC) {
+    spec = process.env.CRANK_NPM_SPEC;
+  } else {
+    spec = `@ahmednawaz/crank@^${crankPkg.version || '0.1.0'}`;
+  }
+
+  if (pkg.devDependencies.crank === spec) {
+    return;
+  }
+  pkg.devDependencies.crank = spec;
+  writeJson(pkgPath, pkg);
+  results.wrote.push('package.json#devDependencies.crank');
+  results.crankDependencyAdded = spec;
+}
+
+function writeConfig(projectRoot, env) {
+  const dir = path.join(projectRoot, '.crank');
+  const configPath = path.join(dir, 'config.json');
+  fs.mkdirSync(dir, { recursive: true });
+  if (exists(configPath)) {
+    const existing = readJson(configPath, {}) || {};
+    existing.projectRoot = projectRoot;
+    existing.packageRoot = PACKAGE_ROOT;
+    writeJson(configPath, existing);
+    return existing;
+  }
+  const config = {
+    version: 1,
+    packageRoot: PACKAGE_ROOT,
+    projectRoot,
+    createdAt: new Date().toISOString(),
+    environment: {
+      isReplit: env.isReplit,
+      hasVite: env.hasVite
+    }
+  };
+  writeJson(configPath, config);
+  return config;
+}
+
+/**
+ * One-shot init into the target repo. Idempotent.
+ */
+function initProject(projectRoot, options = {}) {
+  const env = detectEnvironment(projectRoot);
+  const results = {
+    projectRoot,
+    environment: env,
+    wrote: []
+  };
+
+  ensureGitignore(projectRoot);
+  results.wrote.push('.gitignore');
+
+  writeConfig(projectRoot, env);
+  results.wrote.push('.crank/config.json');
+
+  writeProjectEnvExample(projectRoot);
+  if (exists(path.join(projectRoot, '.env.crank.example'))) {
+    results.wrote.push('.env.crank.example');
+  }
+
+  // Cursor project MCP
+  if (options.mcp !== false) {
+    ensureCrankDependency(projectRoot, results);
+
+    const cursorMcp = path.join(projectRoot, '.cursor', 'mcp.json');
+    mergeMcpServers(cursorMcp, 'crank', projectRoot);
+    results.wrote.push('.cursor/mcp.json');
+
+    // VS Code / Copilot MCP
+    const vsMcp = path.join(projectRoot, '.vscode', 'mcp.json');
+    mergeVsCodeMcp(vsMcp, projectRoot);
+    results.wrote.push('.vscode/mcp.json');
+
+    if (options.userMcp !== false) {
+      mergeUserCursorMcp(projectRoot, results);
+    }
+
+    if (env.hasClaudeDesktop && options.claude !== false) {
+      try {
+        mergeMcpServers(env.claudeConfig, 'crank', projectRoot);
+        results.wrote.push(env.claudeConfig);
+      } catch (err) {
+        results.claudeError = err.message;
+      }
+    }
+  }
+
+  if (options.skill !== false) {
+    installCrankSkill(projectRoot, results);
+  }
+
+  if (env.hasVite && options.vite !== false) {
+    const viteResult = patchViteConfig(projectRoot);
+    results.vite = viteResult;
+    if (viteResult.patched) {
+      results.wrote.push(path.relative(projectRoot, viteResult.file));
+    }
+  }
+
+  // package.json script convenience
+  if (env.hasPackageJson && options.scripts !== false) {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    const pkg = readJson(pkgPath, {});
+    pkg.scripts = pkg.scripts || {};
+    if (!pkg.scripts.crank) {
+      pkg.scripts.crank = `node ${JSON.stringify(
+        path.join(PACKAGE_ROOT, 'bin', 'crank.js')
+      )}`;
+      writeJson(pkgPath, pkg);
+      results.wrote.push('package.json#scripts.crank');
+    }
+  }
+
+  if (env.isReplit) {
+    patchReplitConfig(projectRoot, results);
+    writeReplitGuide(projectRoot, env, results);
+  }
+
+  if (results.crankDependencyAdded && options.install !== false) {
+    try {
+      const { execSync } = require('child_process');
+      execSync('npm install', { cwd: projectRoot, stdio: 'inherit' });
+      results.installed = true;
+    } catch (err) {
+      results.installError = err.message;
+    }
+  }
+
+  return results;
+}
+
+function patchReplitConfig(projectRoot, results) {
+  const replitFile = path.join(projectRoot, '.replit');
+  const companionPort = Number(process.env.CRANK_PORT || 3344);
+  const mcpPort = Number(process.env.CRANK_MCP_HTTP_PORT || 3345);
+  let source = exists(replitFile) ? fs.readFileSync(replitFile, 'utf8') : '';
+
+  if (!/localPort\s*=\s*3344/.test(source)) {
+    source += `\n[[ports]]\nlocalPort = ${companionPort}\nexternalPort = 80\n`;
+  }
+  if (!/localPort\s*=\s*3345/.test(source)) {
+    source += `\n[[ports]]\nlocalPort = ${mcpPort}\nexternalPort = 80\n`;
+  }
+
+  if (!/^run\s*=/m.test(source)) {
+    source = `run = "npx crank"\n\n${source}`;
+    results.replitRun = 'npx crank';
+  }
+
+  fs.writeFileSync(replitFile, source.trimEnd() + '\n');
+  results.wrote.push('.replit');
+}
+
+function writeReplitGuide(projectRoot, detectEnv, results, runtime) {
+  const urls = runtime ? null : resolveUrls(detectEnv);
+  const mcpEndpoint =
+    runtime?.mcp?.endpoint || urls?.mcpEndpoint || 'https://3345-<repl-host>/mcp';
+  const companionUrl =
+    runtime?.companion?.publicUrl || urls?.companionPublic || 'https://3344-<repl-host>';
+  const hint = path.join(projectRoot, '.crank', 'replit.md');
+  const apiKeyLine = process.env.CRANK_MCP_API_KEY
+    ? '3. Header: `X-API-Key` = your `CRANK_MCP_API_KEY` secret.'
+    : '3. Optional: set `CRANK_MCP_API_KEY` in Secrets and pass `X-API-Key` in MCP headers.';
+  fs.writeFileSync(
+    hint,
+    [
+      '# Crank on Replit',
+      '',
+      'One command: `npx crank setup` then `npx crank` — no paths required.',
+      '',
+      '## Replit Agent MCP',
+      '',
+      'Integrations → MCP Servers → Add custom server:',
+      `- URL: \`${mcpEndpoint}\``,
+      apiKeyLine,
+      '',
+      '## Panel in preview',
+      '',
+      `- Companion: ${companionUrl}`,
+      '- Vite apps: panel auto-loads in the webview.',
+      '- Other stacks: open the companion URL and use the bookmarklet on your preview tab.',
+      ''
+    ].join('\n')
+  );
+  results.wrote.push('.crank/replit.md');
+}
+
+module.exports = {
+  initProject,
+  PACKAGE_ROOT,
+  mcpServerEntry,
+  installCrankSkill,
+  writeReplitGuide,
+  patchReplitConfig
+};

package/lib/load-team-env.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Load team-wide defaults shipped in the npm tarball (team.env) or maintainer .env.
+ * Never commit real keys to git — `npm run publish:team` bundles team.env at publish time.
+ */
+function loadTeamEnvFile(packageRoot) {
+  const candidates = [
+    path.join(packageRoot, 'team.env'),
+    path.join(packageRoot, '.env')
+  ];
+  for (const file of candidates) {
+    if (!fs.existsSync(file)) {
+      continue;
+    }
+    for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) {
+        continue;
+      }
+      const eq = trimmed.indexOf('=');
+      if (eq < 1) {
+        continue;
+      }
+      const key = trimmed.slice(0, eq).trim();
+      let value = trimmed.slice(eq + 1).trim();
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+      if (process.env[key] == null) {
+        process.env[key] = value;
+      }
+    }
+  }
+}
+
+module.exports = { loadTeamEnvFile };

package/lib/resolve-project.js

@@ -0,0 +1,203 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { exists, readJson } = require('./detect');
+
+const APP_DIR_CANDIDATES = [
+  '.',
+  'app',
+  'client',
+  'web',
+  'frontend',
+  'packages/app',
+  'packages/web',
+  'apps/web',
+  'apps/frontend'
+];
+
+const FRAMEWORK_FILES = [
+  'vite.config.ts',
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.cjs',
+  'next.config.js',
+  'next.config.mjs',
+  'next.config.ts',
+  'nuxt.config.ts',
+  'nuxt.config.js',
+  'angular.json',
+  'svelte.config.js',
+  'astro.config.mjs',
+  'astro.config.ts'
+];
+
+function hasFrameworkMarker(dir) {
+  return FRAMEWORK_FILES.some((name) => exists(path.join(dir, name)));
+}
+
+function readCrankConfig(startDir) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 12; i++) {
+    const configPath = path.join(dir, '.crank', 'config.json');
+    if (exists(configPath)) {
+      const config = readJson(configPath, null);
+      if (config?.projectRoot && exists(config.projectRoot)) {
+        return { config, root: path.resolve(config.projectRoot), from: configPath };
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function gitRoot(startDir) {
+  try {
+    const out = execSync('git rev-parse --show-toplevel', {
+      cwd: startDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    if (out && exists(out)) {
+      return path.resolve(out);
+    }
+  } catch {
+    // not a git repo
+  }
+  return null;
+}
+
+function gitRemote(root) {
+  try {
+    return execSync('git remote get-url origin', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function findPackageRoot(startDir) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 12; i++) {
+    if (exists(path.join(dir, 'package.json'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.resolve(startDir);
+}
+
+/**
+ * Retune-style: find the app directory inside a repo (app/, client/, web/, …).
+ */
+function findAppDirectory(repoRoot) {
+  const root = path.resolve(repoRoot);
+  if (hasFrameworkMarker(root)) {
+    return { appRoot: root, reason: 'framework at repo root' };
+  }
+
+  for (const rel of APP_DIR_CANDIDATES) {
+    if (rel === '.') continue;
+    const candidate = path.join(root, rel);
+    if (exists(candidate) && hasFrameworkMarker(candidate)) {
+      return { appRoot: candidate, reason: `framework in ${rel}/` };
+    }
+  }
+
+  for (const rel of APP_DIR_CANDIDATES) {
+    const candidate = path.join(root, rel === '.' ? '' : rel);
+    if (exists(candidate) && exists(path.join(candidate, 'package.json'))) {
+      return { appRoot: candidate, reason: `package.json in ${rel === '.' ? 'root' : rel + '/'}` };
+    }
+  }
+
+  return { appRoot: root, reason: 'repo root (fallback)' };
+}
+
+/**
+ * Resolve where the user's app code lives — no manual path required.
+ * Priority: CRANK_PROJECT_ROOT → .crank/config → git root + app dir → package.json walk → cwd.
+ */
+function resolveProjectRoot(startDir = process.cwd()) {
+  const explicit = process.env.CRANK_PROJECT_ROOT;
+  if (explicit) {
+    const resolved = path.resolve(explicit);
+    const { appRoot, reason } = findAppDirectory(resolved);
+    return {
+      projectRoot: appRoot,
+      repoRoot: gitRoot(appRoot) || resolved,
+      source: 'CRANK_PROJECT_ROOT',
+      reason
+    };
+  }
+
+  const crankConfig = readCrankConfig(startDir);
+  if (crankConfig) {
+    const { appRoot, reason } = findAppDirectory(crankConfig.root);
+    return {
+      projectRoot: appRoot,
+      repoRoot: gitRoot(appRoot) || crankConfig.root,
+      source: '.crank/config.json',
+      reason
+    };
+  }
+
+  const git = gitRoot(startDir);
+  if (git) {
+    const { appRoot, reason } = findAppDirectory(git);
+    return {
+      projectRoot: appRoot,
+      repoRoot: git,
+      source: 'git root',
+      reason
+    };
+  }
+
+  const pkgRoot = findPackageRoot(startDir);
+  const { appRoot, reason } = findAppDirectory(pkgRoot);
+  return {
+    projectRoot: appRoot,
+    repoRoot: pkgRoot,
+    source: 'cwd / package.json',
+    reason
+  };
+}
+
+function describeEnvironment(projectRoot) {
+  const env = process.env;
+  const isReplit = Boolean(
+    env.REPL_ID || env.REPL_SLUG || env.REPLIT_DEV_DOMAIN || env.REPLIT_DB_URL
+  );
+  const isCodespaces = Boolean(env.CODESPACES);
+  const isCloudShell = Boolean(env.CLOUD_SHELL);
+  const resolved = resolveProjectRoot(projectRoot || process.cwd());
+  return {
+    ...resolved,
+    gitRemote: gitRemote(resolved.repoRoot),
+    runtime: {
+      isReplit,
+      isCodespaces,
+      isCloudShell,
+      isVirtual: isReplit || isCodespaces || isCloudShell,
+      replitDomain: env.REPLIT_DEV_DOMAIN || null,
+      cwd: process.cwd()
+    }
+  };
+}
+
+module.exports = {
+  resolveProjectRoot,
+  findAppDirectory,
+  describeEnvironment,
+  gitRoot,
+  gitRemote,
+  hasFrameworkMarker
+};