carto-md 1.0.17 → 1.0.19

package/README.md

@@ -135,14 +135,13 @@ npx carto-md init
 # 1. Go to your project
 cd your-project
 
-# 2. Generate AGENTS.md (run once)
+# 2. Run once — like git init
 carto init
-
-# 3. Keep it live while you work
-carto watch
 ```
 
-Leave `carto watch` running in a background terminal. Every file save updates AGENTS.md automatically.
+That's it. Carto installs a git hook. Every `git commit` syncs AGENTS.md automatically — no watching, no manual runs, nothing to remember.
+
+Want live updates on every file save too? Run `carto watch` in a background terminal.
 
 ---
 
@@ -150,16 +149,17 @@ Leave `carto watch` running in a background terminal. Every file save updates AG
 
 | Command | What it does |
 |---------|-------------|
-| `carto init` | Detect stack, generate AGENTS.md, install git hook |
-| `carto watch` | Watch files, update AGENTS.md on every save |
-| `carto sync` | One-time refresh, no watcher |
+| `carto init` | Detect stack, generate AGENTS.md, install git hook — auto-syncs on every commit |
+| `carto watch` | Live updates on every file save — optional, for between commits |
+| `carto sync` | One-time manual refresh |
 | `carto impact <file>` | Show blast radius before touching a file |
+| `carto remove` | Remove AGENTS.md and .carto/ from this project |
 | `carto --version` | Show version |
 
 **When to use each:**
-- `init` — once, when you add Carto to a project
-- `watch` — every work session, leave it running
-- `sync` — skipped watch and need a fresh snapshot
+- `init` — once per project, sets everything up
+- `watch` — optional, if you want updates between commits
+- `sync` — if you skipped watch and need a fresh snapshot
 - `impact` — before editing anything critical
 
 ---
@@ -171,6 +171,7 @@ Leave `carto watch` running in a background terminal. Every file save updates AG
 | Python | FastAPI, Pydantic |
 | JavaScript | Express, Next.js |
 | TypeScript | Express, Next.js, Prisma |
+| R | Plumber, Shiny |
 | HTML | fetch() calls |
 
 More languages via community — open an issue or see [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -248,7 +249,7 @@ Carto never writes secrets into AGENTS.md. `.cartoignore` blocks `.env` files, s
 
 ## Contributing
 
-Python and JS/TS today. Want Go, Ruby, Django, Rails? Open an issue — or read [CONTRIBUTING.md](CONTRIBUTING.md) to add it yourself.
+Python, JS/TS, and R today. Want Go, Ruby, Django, Rails? Open an issue — or read [CONTRIBUTING.md](CONTRIBUTING.md) to add it yourself.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carto-md",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "The context layer for AI-native development.",
   "bin": {
     "carto": "src/cli/index.js"

package/src/cli/init.js

@@ -17,11 +17,13 @@ async function run(projectRoot) {
   // Count files for reporting
   const pyCount = files.routeFiles.filter(f => f.endsWith('.py')).length;
   const jsCount = files.routeFiles.filter(f => /\.(js|ts|jsx|tsx)$/.test(f)).length;
+  const rCount = files.routeFiles.filter(f => /\.[rR]$/.test(f)).length;
   const htmlCount = files.frontendFiles.length;
 
   const parts = [];
   if (pyCount > 0) parts.push(`${pyCount} Python files`);
   if (jsCount > 0) parts.push(`${jsCount} JS/TS files`);
+  if (rCount > 0) parts.push(`${rCount} R files`);
   if (htmlCount > 0) parts.push(`${htmlCount} HTML files`);
   console.log(`[CARTO] Found ${parts.join(', ') || '0 files'}`);
 

package/src/detector/files.js

@@ -9,6 +9,7 @@ const BASE_UTILITY_BUDGET = 20;
 const PYTHON_IGNORE = new Set(['__pycache__', '.venv', 'venv', 'migrations', 'node_modules', '.git', '.carto']);
 const JS_IGNORE = new Set(['node_modules', '.git', 'dist', 'build', '.carto', '.next', '.turbo', 'coverage', 'out', '.cache', 'generated', '__generated__', 'storybook-static', 'public', 'static']);
 const HTML_IGNORE = new Set(['node_modules', '.git', '.carto']);
+const R_IGNORE = new Set(['.Rhistory', '.RData', 'packrat', 'renv', 'node_modules', '.git', '__pycache__', '.carto']);
 
 /**
  * discoverFiles(projectRoot, framework, isIgnored, secondaryFramework) → { routeFiles, modelFiles, frontendFiles }
@@ -60,6 +61,20 @@ function discoverForFramework(projectRoot, framework, ignoreFn) {
     return smartSelect(jsFiles, htmlFiles, projectRoot);
   }
 
+  if (['plumber', 'shiny', 'r-generic'].includes(framework)) {
+    const rFiles = findFilesRecursive(projectRoot, ['.r'], R_IGNORE, ignoreFn)
+      .filter(f => {
+        const lbase = path.basename(f).toLowerCase();
+        return !lbase.startsWith('test_') && !lbase.startsWith('test-') && !lbase.endsWith('_test.r');
+      });
+
+    if (rFiles.length <= MAX_FILES_TOTAL) {
+      return { routeFiles: rFiles, modelFiles: rFiles, frontendFiles: [] };
+    }
+
+    return smartSelect(rFiles, [], projectRoot);
+  }
+
   // Unknown framework
   const allCode = findFilesRecursive(projectRoot, ['.py', '.js', '.ts'], new Set(['node_modules', '.git', '__pycache__', '.venv', 'venv', '.carto']), ignoreFn);
   const htmlFiles = findFilesRecursive(projectRoot, ['.html'], HTML_IGNORE, ignoreFn);

package/src/detector/framework.js

@@ -6,6 +6,7 @@ const IGNORE_DIRS = new Set(['node_modules', '.git', '__pycache__', '.venv', 've
 // Priority order: lower index = higher priority
 const PYTHON_PRIORITY = ['fastapi', 'django', 'flask', 'python-generic'];
 const JS_PRIORITY = ['nextjs', 'express', 'react', 'node-generic'];
+const R_PRIORITY = ['plumber', 'shiny', 'r-generic'];
 
 /**
  * detectFramework(projectRoot) → { framework, language, confidence, secondaryFramework?, secondaryLanguage? }
@@ -16,36 +17,37 @@ const JS_PRIORITY = ['nextjs', 'express', 'react', 'node-generic'];
  * (primary = highest priority overall, secondary = the other language).
  */
 function detectFramework(projectRoot) {
-  const candidates = findFile(projectRoot, ['requirements.txt', 'package.json', 'pyproject.toml'], 3);
+  const candidates = findFile(projectRoot, ['requirements.txt', 'package.json', 'pyproject.toml', 'DESCRIPTION'], 3);
 
   const pythonDetections = new Set();
   const jsDetections = new Set();
+  const rDetections = new Set();
 
-  // Check requirements.txt
   for (const f of candidates.filter(f => path.basename(f) === 'requirements.txt')) {
-    const results = detectAllFromPythonDeps(f);
-    for (const r of results) pythonDetections.add(r);
+    for (const r of detectAllFromPythonDeps(f)) pythonDetections.add(r);
   }
 
-  // Check pyproject.toml
   for (const f of candidates.filter(f => path.basename(f) === 'pyproject.toml')) {
-    const results = detectAllFromPythonDeps(f);
-    for (const r of results) pythonDetections.add(r);
+    for (const r of detectAllFromPythonDeps(f)) pythonDetections.add(r);
   }
 
-  // Check package.json
   for (const f of candidates.filter(f => path.basename(f) === 'package.json')) {
-    const results = detectAllFromPackageJson(f);
-    for (const r of results) jsDetections.add(r);
+    for (const r of detectAllFromPackageJson(f)) jsDetections.add(r);
+  }
+
+  for (const f of candidates.filter(f => path.basename(f) === 'DESCRIPTION')) {
+    for (const r of detectAllFromRDescription(f)) rDetections.add(r);
+  }
+
+  if (rDetections.size === 0) {
+    for (const r of detectAllFromRFiles(projectRoot)) rDetections.add(r);
   }
 
-  // Pick best Python framework by priority
   const bestPython = PYTHON_PRIORITY.find(fw => pythonDetections.has(fw)) || null;
-  // Pick best JS framework by priority
   const bestJS = JS_PRIORITY.find(fw => jsDetections.has(fw)) || null;
+  const bestR = R_PRIORITY.find(fw => rDetections.has(fw)) || null;
 
   if (bestPython && bestJS) {
-    // Both detected — Python is primary (higher priority in the global list)
     return {
       framework: bestPython,
       language: 'python',
@@ -63,6 +65,10 @@ function detectFramework(projectRoot) {
     return { framework: bestJS, language: 'javascript', confidence: 'high' };
   }
 
+  if (bestR) {
+    return { framework: bestR, language: 'r', confidence: 'high' };
+  }
+
   return { framework: 'unknown', language: 'unknown', confidence: 'none' };
 }
 
@@ -135,4 +141,43 @@ function detectAllFromPackageJson(filePath) {
   return detected;
 }
 
+function detectAllFromRDescription(filePath) {
+  const detected = [];
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf-8').toLowerCase();
+  } catch {
+    return detected;
+  }
+  if (content.includes('plumber')) detected.push('plumber');
+  if (content.includes('shiny')) detected.push('shiny');
+  if (!detected.length) detected.push('r-generic');
+  return detected;
+}
+
+function detectAllFromRFiles(projectRoot) {
+  const detected = [];
+  let files;
+  try {
+    files = fs.readdirSync(projectRoot).filter(f => f.endsWith('.R') || f.endsWith('.r'));
+  } catch {
+    return detected;
+  }
+  if (!files.length) return detected;
+
+  for (const file of files.slice(0, 5)) {
+    let content;
+    try {
+      content = fs.readFileSync(path.join(projectRoot, file), 'utf-8').toLowerCase();
+    } catch {
+      continue;
+    }
+    if (/library\s*\(\s*["']?plumber["']?\s*\)/.test(content)) detected.push('plumber');
+    if (/library\s*\(\s*["']?shiny["']?\s*\)/.test(content)) detected.push('shiny');
+  }
+
+  if (!detected.length) detected.push('r-generic');
+  return detected;
+}
+
 module.exports = { detectFramework };

package/src/extractors/imports.js

@@ -20,6 +20,10 @@ const fs = require('fs');
  *   from app.module import X     (local package — resolved if file exists)
  *   import .module               (relative)
  *
+ * R patterns:
+ *   library(pkg) / require(pkg)  (package name recorded as-is)
+ *   source("./file.R")           (resolved if file exists)
+ *
  * Only includes paths that resolve to actual files in the project.
  * Skips: node_modules, non-code files, anything that doesn't resolve.
  */
@@ -33,6 +37,8 @@ function extractImports(content, filePath, projectRoot) {
     rawImports = extractJSImports(content);
   } else if (ext === '.py') {
     rawImports = extractPythonImports(content, filePath, projectRoot);
+  } else if (ext === '.r') {
+    return extractRImports(content, filePath, projectRoot);
   }
 
   // Resolve and deduplicate
@@ -72,6 +78,32 @@ function extractJSImports(content) {
   return imports;
 }
 
+/**
+ * Extract imports from R content.
+ * library(pkg) / require(pkg) → package name recorded directly.
+ * source("./file.R") → resolved relative path if the file exists.
+ */
+function extractRImports(content, filePath, projectRoot) {
+  const results = new Set();
+  const fileDir = path.dirname(filePath);
+
+  const pkgRe = /(?:library|require)\s*\(\s*["']?(\w[\w.]+)["']?\s*\)/g;
+  let m;
+  while ((m = pkgRe.exec(content)) !== null) {
+    results.add(m[1]);
+  }
+
+  const sourceRe = /source\s*\(\s*["']([^"']+)["']\s*\)/g;
+  while ((m = sourceRe.exec(content)) !== null) {
+    const abs = path.resolve(fileDir, m[1]);
+    if (fs.existsSync(abs)) {
+      results.add(path.relative(projectRoot, abs));
+    }
+  }
+
+  return [...results].sort();
+}
+
 /**
  * Extract import paths from Python content. Relative imports only.
  */

package/src/extractors/languages/r.js

@@ -0,0 +1,255 @@
+function pathToIdentifier(routePath) {
+  const segments = routePath.split('/').filter(Boolean);
+  const last = segments[segments.length - 1] || 'handler';
+  return last.replace(/[^a-zA-Z0-9_]/g, '_').replace(/^(\d)/, '_$1') || 'handler';
+}
+
+function descToIdentifier(desc) {
+  const words = desc.trim().split(/\s+/);
+  if (words.length === 1 && /^[a-zA-Z_]\w*$/.test(words[0])) return words[0];
+  return words
+    .map((w, i) => i === 0 ? w.toLowerCase() : w[0].toUpperCase() + w.slice(1).toLowerCase())
+    .join('')
+    .replace(/[^a-zA-Z0-9_]/g, '')
+    .replace(/^(\d)/, '_$1') || null;
+}
+
+function extractRoutes(content) {
+  const routes = [];
+  const lines = content.split('\n');
+  const routePattern = /^#\*\s+@(get|post|put|delete|patch|options|head)\s+(\S+)/i;
+  const descPattern = /^#\*\s+(?!@)(.+)/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const routeMatch = lines[i].match(routePattern);
+    if (!routeMatch) continue;
+
+    const method = routeMatch[1].toUpperCase();
+    const routePath = routeMatch[2].trim();
+
+    let functionName = pathToIdentifier(routePath);
+    for (let j = i - 1; j >= Math.max(0, i - 10); j--) {
+      const line = lines[j].trim();
+      if (!line.startsWith('#')) break;
+      const descMatch = line.match(descPattern);
+      if (descMatch) {
+        const derived = descToIdentifier(descMatch[1]);
+        if (derived) functionName = derived;
+        break;
+      }
+    }
+
+    routes.push({ method, path: routePath, functionName });
+  }
+  return routes;
+}
+
+function extractFunctions(content) {
+  const functions = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!/^\w+\s*<-\s*function\s*\(/.test(line)) continue;
+
+    const nameMatch = line.match(/^(\w+)\s*<-\s*function\s*\(/);
+    if (!nameMatch) continue;
+
+    const name = nameMatch[1];
+    if (name.startsWith('.')) continue;
+
+    let combined = line;
+    let depth = 0;
+    for (const ch of line) {
+      if (ch === '(') depth++;
+      else if (ch === ')') depth--;
+    }
+
+    let safety = 0;
+    while (depth > 0 && safety < 15 && i + 1 < lines.length) {
+      i++;
+      safety++;
+      const next = lines[i].trim();
+      combined += ' ' + next;
+      for (const ch of next) {
+        if (ch === '(') depth++;
+        else if (ch === ')') depth--;
+      }
+    }
+
+    const paramMatch = combined.match(/function\s*\(([^)]*)\)/);
+    if (!paramMatch) continue;
+
+    const params = paramMatch[1]
+      .split(',')
+      .map(p => p.split('=')[0].trim())
+      .filter(p => p.length > 0)
+      .join(', ');
+
+    functions.push({ name, params: params || '—', returnType: '—' });
+  }
+  return functions;
+}
+
+function collapseParens(content) {
+  const lines = content.split('\n');
+  const result = [];
+  let i = 0;
+  while (i < lines.length) {
+    let depth = 0;
+    for (const ch of lines[i]) {
+      if (ch === '(') depth++;
+      else if (ch === ')') depth--;
+    }
+    if (depth <= 0) {
+      result.push(lines[i]);
+      i++;
+      continue;
+    }
+    let combined = lines[i];
+    let safety = 0;
+    while (depth > 0 && safety < 20 && i + 1 < lines.length) {
+      i++;
+      safety++;
+      const next = lines[i].trim();
+      combined += ' ' + next;
+      for (const ch of next) {
+        if (ch === '(') depth++;
+        else if (ch === ')') depth--;
+      }
+    }
+    result.push(combined);
+    i++;
+  }
+  return result.join('\n');
+}
+
+function findBalancedEnd(str, openPos) {
+  let depth = 1;
+  let pos = openPos + 1;
+  while (depth > 0 && pos < str.length) {
+    if (str[pos] === '(') depth++;
+    else if (str[pos] === ')') depth--;
+    pos++;
+  }
+  return pos - 1;
+}
+
+function extractModels(content) {
+  const models = [];
+  const collapsed = collapseParens(content);
+
+  const setClassRe = /setClass\s*\(\s*["'](\w+)["']/g;
+  let m;
+  while ((m = setClassRe.exec(collapsed)) !== null) {
+    const className = m[1];
+    const slotsIdx = collapsed.indexOf('slots', m.index);
+    if (slotsIdx === -1 || slotsIdx > m.index + 300) continue;
+    const listIdx = collapsed.indexOf('list(', slotsIdx);
+    if (listIdx === -1) continue;
+    const openPos = listIdx + 4;
+    const closePos = findBalancedEnd(collapsed, openPos);
+    const slotsContent = collapsed.slice(openPos + 1, closePos);
+    const fields = [];
+    const slotRe = /(\w+)\s*=\s*["']([^"']+)["']/g;
+    let sm;
+    while ((sm = slotRe.exec(slotsContent)) !== null) {
+      fields.push({ name: sm[1], type: sm[2] });
+    }
+    models.push({ className, fields });
+  }
+
+  const dfRe = /^(\w+)\s*<-\s*data\.frame\s*\(/gm;
+  while ((m = dfRe.exec(collapsed)) !== null) {
+    const className = m[1];
+    const openPos = m.index + m[0].length - 1;
+    const closePos = findBalancedEnd(collapsed, openPos);
+    const innerContent = collapsed.slice(openPos + 1, closePos);
+    const fields = [];
+    const colRe = /\b(\w+)\s*=\s*(\w+)\s*\(/g;
+    let cm;
+    while ((cm = colRe.exec(innerContent)) !== null) {
+      fields.push({ name: cm[1], type: cm[2] });
+    }
+    if (fields.length > 0) {
+      models.push({ className, fields });
+    }
+  }
+
+  const r6Re = /^(\w+)\s*<-\s*(?:R6::)?R6Class\s*\(\s*["'](\w+)["']/gm;
+  while ((m = r6Re.exec(collapsed)) !== null) {
+    const className = m[2];
+    const publicIdx = collapsed.indexOf('public', m.index);
+    if (publicIdx === -1 || publicIdx > m.index + 600) continue;
+    const listIdx = collapsed.indexOf('list(', publicIdx);
+    if (listIdx === -1) continue;
+    const openPos = listIdx + 4;
+    const closePos = findBalancedEnd(collapsed, openPos);
+    const publicContent = collapsed.slice(openPos + 1, closePos);
+    const fields = [];
+    const fieldRe = /\b(\w+)\s*=\s*(?!function\s*\()(\w+|["'][^"']*["'])/g;
+    let fm;
+    while ((fm = fieldRe.exec(publicContent)) !== null) {
+      const name = fm[1];
+      const rawVal = fm[2].trim();
+      let type = 'any';
+      if (/^["']/.test(rawVal)) type = 'character';
+      else if (/^\d/.test(rawVal)) type = 'numeric';
+      else if (rawVal === 'TRUE' || rawVal === 'FALSE') type = 'logical';
+      fields.push({ name, type });
+    }
+    models.push({ className, fields });
+  }
+
+  const s7Re = /^(\w+)\s*<-\s*(?:S7::)?new_class\s*\(\s*(?:name\s*=\s*)?["'](\w+)["']/gm;
+  while ((m = s7Re.exec(collapsed)) !== null) {
+    const className = m[2];
+    const propsIdx = collapsed.indexOf('properties', m.index);
+    if (propsIdx === -1 || propsIdx > m.index + 400) continue;
+    const listIdx = collapsed.indexOf('list(', propsIdx);
+    if (listIdx === -1) continue;
+    const openPos = listIdx + 4;
+    const closePos = findBalancedEnd(collapsed, openPos);
+    const propsContent = collapsed.slice(openPos + 1, closePos);
+    const fields = [];
+    const propRe = /(\w+)\s*=\s*(?:S7::)?class_(\w+)/g;
+    let pm;
+    while ((pm = propRe.exec(propsContent)) !== null) {
+      fields.push({ name: pm[1], type: pm[2] });
+    }
+    models.push({ className, fields });
+  }
+
+  return models;
+}
+
+function extractEnvVars(content) {
+  const vars = new Set();
+  const re = /Sys\.getenv\s*\(\s*["']([A-Z_][A-Z0-9_]*)["']\s*\)/g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    vars.add(m[1]);
+  }
+  return [...vars].sort();
+}
+
+module.exports = {
+  name: 'r',
+  extensions: ['.r', '.R'],
+  extract(content, filename) {
+    try {
+      return {
+        routes:      extractRoutes(content),
+        models:      extractModels(content),
+        functions:   extractFunctions(content),
+        envVars:     extractEnvVars(content),
+        dbTables:    [],
+        fetches:     [],
+        storageKeys: [],
+      };
+    } catch (err) {
+      console.warn(`[CARTO] r plugin error on ${filename}: ${err.message}`);
+      return { routes: [], models: [], functions: [], envVars: [], dbTables: [], fetches: [], storageKeys: [] };
+    }
+  }
+};

package/src/extractors/routes.js

@@ -43,6 +43,7 @@ function extractRoutes(content) {
   const lines = collapsed.split('\n');
 
   for (let i = 0; i < lines.length; i++) {
+    if (/^\s*#/.test(lines[i])) { decoratorPattern.lastIndex = 0; continue; }
     const match = decoratorPattern.exec(lines[i]);
     if (match) {
       // Look ahead up to 5 lines for the function definition