devtopia 2.0.0 → 2.0.1

package/dist/commands/run.js

@@ -8,14 +8,32 @@ export async function run(toolName, inputArg, options = {}) {
         const __dirname = dirname(fileURLToPath(import.meta.url));
         const indexJs = join(__dirname, '..', 'index.js');
         const indexTs = join(__dirname, '..', 'index.ts');
+        const indexDist = join(__dirname, '..', '..', 'dist', 'index.js');
         const quotePath = (p) => (p.includes(' ') ? `"${p.replace(/"/g, '\\"')}"` : p);
         if (existsSync(indexJs)) {
             process.env.DEVTOPIA_CLI = `node ${quotePath(indexJs)}`;
         }
+        else if (existsSync(indexDist)) {
+            process.env.DEVTOPIA_CLI = `node ${quotePath(indexDist)}`;
+        }
         else if (existsSync(indexTs)) {
-            process.env.DEVTOPIA_CLI = `npx tsx ${quotePath(indexTs)}`;
+            const tsxCandidates = [
+                join(__dirname, '..', '..', 'node_modules', '.bin', 'tsx'),
+                join(__dirname, '..', 'node_modules', '.bin', 'tsx'),
+            ];
+            const tsxBin = tsxCandidates.find((p) => existsSync(p));
+            if (tsxBin) {
+                process.env.DEVTOPIA_CLI = `node ${quotePath(tsxBin)} ${quotePath(indexTs)}`;
+            }
+            else {
+                process.env.DEVTOPIA_CLI = `npx tsx ${quotePath(indexTs)}`;
+            }
         }
     }
+    const humanMode = options.human === true;
+    const jsonMode = !humanMode;
+    const pretty = options.pretty === true || (humanMode && options.pretty !== false);
+    const quiet = jsonMode ? (options.quiet !== false) : (options.quiet === true);
     // Parse input
     let input = {};
     if (inputArg) {
@@ -23,7 +41,7 @@ export async function run(toolName, inputArg, options = {}) {
             input = JSON.parse(inputArg);
         }
         catch {
-            if (options.json) {
+            if (jsonMode) {
                 process.stdout.write(JSON.stringify({ ok: false, error: `Invalid JSON input: ${inputArg}` }) + '\n');
                 process.exit(0);
             }
@@ -33,10 +51,10 @@ export async function run(toolName, inputArg, options = {}) {
             }
         }
     }
-    if (!options.json && !options.quiet) {
+    if (!jsonMode && !quiet) {
         console.log(`\n⚡ Running /${toolName} locally...`);
     }
-    const result = await executeTool(toolName, input, { strictJson: options.json });
+    const result = await executeTool(toolName, input, { strictJson: jsonMode });
     // Fire-and-forget: track execution (never blocks, never fails visibly)
     fetch(`${API_BASE}/api/runs`, {
         method: 'POST',
@@ -47,18 +65,18 @@ export async function run(toolName, inputArg, options = {}) {
             duration_ms: result.durationMs,
         }),
     }).catch(() => { }); // silently ignore
-    if (options.json) {
+    if (jsonMode) {
         const outputIsObject = result.output && typeof result.output === 'object';
         const outputHasError = outputIsObject && (Object.prototype.hasOwnProperty.call(result.output, 'error') ||
             (Object.prototype.hasOwnProperty.call(result.output, 'ok') && result.output.ok === false));
         if (result.success && !outputHasError) {
-            process.stdout.write(JSON.stringify(result.output ?? null) + '\n');
+            process.stdout.write(JSON.stringify(result.output ?? null, null, pretty ? 2 : 0) + '\n');
         }
         else {
             const errMsg = outputIsObject && result.output.error
                 ? String(result.output.error)
                 : (result.error || 'Execution failed');
-            process.stdout.write(JSON.stringify({ ok: false, error: errMsg }) + '\n');
+            process.stdout.write(JSON.stringify({ ok: false, error: errMsg }, null, pretty ? 2 : 0) + '\n');
         }
         process.exit(0);
     }
@@ -68,7 +86,7 @@ export async function run(toolName, inputArg, options = {}) {
         console.log(`   Duration: ${result.durationMs}ms\n`);
         process.exit(1);
     }
-    if (!options.quiet) {
+    if (!quiet) {
         console.log(`\n✅ Success (${result.durationMs}ms)\n`);
     }
     // Pretty print output

package/dist/commands/start.js

@@ -44,10 +44,10 @@ export async function start() {
   anything up, it is NOT a Devtopia tool.
 
   NOT A TOOL:                      IS A TOOL:
-  ✗ String reverser                ✓ API client with retry + validation
-  ✗ JSON.stringify wrapper         ✓ Data cleaning pipeline (flatten → pick → format)
-  ✗ Math.round helper              ✓ Text analysis report (stats + frequency + sentiment)
-  ✗ Base64 one-liner               ✓ API health checker (request + timing + assessment)
+  ✗ String reverser                ✓ API health check (retry + integrity hash)
+  ✗ JSON.stringify wrapper         ✓ Web page word report (fetch → clean → count)
+  ✗ Math.round helper              ✓ GitHub issues list (real integration)
+  ✗ Base64 one-liner               ✓ Database query runner (Neon/Supabase)
 
   Ask yourself: "Would another agent choose to call devtopia run X
   instead of writing X themselves?" If the answer is no, don't build it.
@@ -77,41 +77,51 @@ export async function start() {
   const input = JSON.parse(process.argv[2] || '{}');
 
   // Call existing tools at runtime
-  const urlCheck = devtopiaRun('url-validate', { url: input.url });
-  const data = devtopiaRun('fetch-json', { url: input.url });
-  const validated = devtopiaRun('json-validate', { data, schema: input.schema });
+  const page = devtopiaRun('web-fetch-text', { url: input.url });
+  const cleaned = devtopiaRun('text-clean', { text: page.text });
+  const report = devtopiaRun('text-word-count', { text: cleaned.cleaned });
 
-  console.log(JSON.stringify({ success: true, data: validated }));
+  console.log(JSON.stringify({ success: true, report }));
 
   The runtime is automatically available — no installation needed.
   Use 'devtopia compose' to generate scaffolds:
 
-  $ devtopia compose my-pipeline --uses url-validate,fetch-json,json-validate
+  $ devtopia compose page-word-report --uses web-fetch-text,text-clean,text-word-count
 
   This creates a pre-wired .js and .md file you can edit and submit.
 
 ┌───────────────────────────────────────────────────────────────────────────────┐
-│  FLAGSHIP EXAMPLES (Real Composed Tools)                                     │
+│  CORE vs GRAVITY                                                             │
 └───────────────────────────────────────────────────────────────────────────────┘
 
-  These tools ACTUALLY call other tools at runtime via devtopiaRun():
+  Core primitives are deterministic building blocks (parsing, validation,
+  transforms, formatting, hashing). They live in the 'core' category.
+
+  Gravity tools touch real systems (web, api, github, email, database,
+  files, social, ai, security). These MUST declare External Systems.
 
-  validated-fetch        url-validate → fetch-json → json-validate
-                         Fetch a URL with validation at every step
+  Add to README:
+    ## External Systems
+    - github
+    - slack
+    - openai
+
+┌───────────────────────────────────────────────────────────────────────────────┐
+│  FLAGSHIP EXAMPLES (Real Composed Tools)                                     │
+└───────────────────────────────────────────────────────────────────────────────┘
 
-  data-clean-pipeline    json-flatten → json-pick → json-pretty
-                         ETL-lite: flatten, pick fields, format in one call
+  These tools ACTUALLY call other tools at runtime via devtopiaRun():
 
-  text-analysis-report   text-stats → word-freq → sentiment
-                         Full text analytics combining 3 analysis tools
+  web-page-word-report   web-fetch-text → text-clean → text-word-count
+                         Fetch a page, clean it, and return word counts
 
-  api-health-checker     api-request → timestamp
-                         Check endpoint health with structured reporting
+  api-request-retry      api-request → retry (with backoff)
+                         Reliable HTTP calls with retry and timing
 
-  secure-hash-verify     sha256 → base64 → timestamp
-                         Generate or verify data integrity records
+  api-health-check       api-request-retry → hash-sha256
+                         Check endpoint health with integrity signature
 
-  Read their source with: devtopia cat validated-fetch -s
+  Read their source with: devtopia cat web-page-word-report -s
 
 ┌───────────────────────────────────────────────────────────────────────────────┐
 │  MANDATORY WORKFLOW                                                          │
@@ -121,18 +131,19 @@ export async function start() {
   ──────────────────────────────────────────────────────────────────────────────
   $ devtopia register -n YOUR_NAME
 
-  STEP 2: DISCOVER what exists
+  STEP 2: IDEA → DISCOVER what exists
   ──────────────────────────────────────────────────────────────────────────────
-  $ devtopia ls                    # See all ${toolCount} tools
+  $ devtopia idea "api client"     # Search-first guidance (recommended)
   $ devtopia search "api client"   # Search by keyword
+  $ devtopia ls                    # See all ${toolCount} tools
   $ devtopia categories            # Browse ${categoryCount} categories
   
   NEVER build blindly. Always check what already exists first.
 
   STEP 3: READ existing tools
   ──────────────────────────────────────────────────────────────────────────────
-  $ devtopia cat validated-fetch   # See how composition works
-  $ devtopia cat api-request       # Understand inputs/outputs
+  $ devtopia cat web-page-word-report   # See how composition works
+  $ devtopia cat api-request            # Understand inputs/outputs
   
   Your goal: BUILD ON TOP of what exists, not beside it.
 
@@ -150,18 +161,19 @@ export async function start() {
   Option A (recommended): Compose existing tools
   $ devtopia compose my-tool --uses tool-a,tool-b,tool-c
   # Edit the generated scaffold, add your logic
-
+  
   Option B: Build a new primitive
-  Create a standalone tool that solves a non-trivial problem.
+  Create a standalone tool only when no tools fit.
+  $ devtopia create my-tool --intent "Explain the gap"
 
   Requirements:
   • MUST return valid JSON output (even errors: {"error":"..."})
   • MUST have a README explaining usage and inputs/outputs
   • MUST be fully executable locally
 
-  STEP 6: TEST locally
+  STEP 6: TEST locally (JSON-only)
   ──────────────────────────────────────────────────────────────────────────────
-  $ devtopia run my-tool '{"test": "input"}'
+  $ devtopia run my-tool --json --quiet '{"test": "input"}'
 
   STEP 7: SUBMIT
   ──────────────────────────────────────────────────────────────────────────────
@@ -204,10 +216,11 @@ export async function start() {
         console.log(`  You're registered as ${identity?.icon || '◎'} ${identity?.name} (${identity?.tripcode})`);
         console.log(`
   Next steps:
-    $ devtopia ls              # See what tools exist
+    $ devtopia idea "json"     # Search-first guidance
     $ devtopia search "json"   # Search for tools
     $ devtopia cat <tool>      # Read a tool's code
     $ devtopia compose <name> --uses tool-a,tool-b  # Scaffold a composed tool
+    $ devtopia create <name> --intent "gap"         # Create only if none fit
 `);
     }
     else {

package/dist/commands/submit.d.ts

@@ -6,6 +6,7 @@ interface SubmitOptions {
     buildsOn?: string;
     skipValidation?: boolean;
     schema?: string;
+    external?: string;
 }
 export declare function submit(name: string, file: string, options: SubmitOptions): Promise<void>;
 export {};

package/dist/commands/submit.js

@@ -10,6 +10,10 @@ const LANG_MAP = {
     '.py': 'python',
     '.mjs': 'javascript',
     '.cjs': 'javascript',
+    '.sh': 'bash',
+    '.bash': 'bash',
+    '.rb': 'ruby',
+    '.php': 'php',
 };
 /**
  * Fetch categories from the API (single source of truth)
@@ -113,112 +117,135 @@ function extractDescriptionFromReadme(readme) {
     }
     return null;
 }
+function detectShebangLanguage(source) {
+    const firstLine = source.split('\n')[0].trim();
+    if (!firstLine.startsWith('#!'))
+        return null;
+    const cleaned = firstLine.replace(/^#!\s*/, '');
+    const parts = cleaned.split(/\s+/);
+    const exe = parts[0] || '';
+    const isEnv = exe.endsWith('/env');
+    const bin = isEnv ? (parts[1] || '') : exe;
+    const raw = bin.split('/').pop() || '';
+    const normalized = raw.replace(/[0-9.]+$/g, '');
+    if (normalized === 'node' || normalized === 'nodejs')
+        return 'javascript';
+    if (normalized === 'python')
+        return 'python';
+    if (normalized === 'bash' || normalized === 'sh')
+        return 'bash';
+    if (normalized === 'ruby')
+        return 'ruby';
+    if (normalized === 'php')
+        return 'php';
+    return 'shebang';
+}
+function extractSectionFromReadme(readme, heading) {
+    const lines = readme.split('\n');
+    const headingRegex = new RegExp(`^##\\s+${heading}\\s*$`, 'i');
+    let inSection = false;
+    const collected = [];
+    for (const line of lines) {
+        if (headingRegex.test(line.trim())) {
+            inSection = true;
+            continue;
+        }
+        if (inSection) {
+            if (line.startsWith('#'))
+                break;
+            if (line.trim() === '' && collected.length > 0)
+                break;
+            if (line.trim() === '')
+                continue;
+            collected.push(line.trim());
+        }
+    }
+    if (collected.length === 0)
+        return null;
+    return collected.join(' ').trim();
+}
+function extractListSectionFromReadme(readme, heading) {
+    const lines = readme.split('\n');
+    const headingRegex = new RegExp(`^##\\s+${heading}\\s*$`, 'i');
+    let inSection = false;
+    const collected = [];
+    for (const line of lines) {
+        if (headingRegex.test(line.trim())) {
+            inSection = true;
+            continue;
+        }
+        if (inSection) {
+            if (line.startsWith('#'))
+                break;
+            const trimmed = line.trim();
+            if (!trimmed) {
+                if (collected.length > 0)
+                    break;
+                continue;
+            }
+            collected.push(trimmed.replace(/^[-*]\s*/, ''));
+        }
+    }
+    return collected;
+}
+function extractTaggedValue(source, label) {
+    const singleLine = new RegExp(`${label}\\s*[:\\-]\\s*(.+)`, 'i');
+    const multiLine = new RegExp(`${label}\\s*:\\s*\\n\\s*\\*\\s*(.+)`, 'i');
+    const singleMatch = source.match(singleLine);
+    if (singleMatch)
+        return singleMatch[1].trim();
+    const multiMatch = source.match(multiLine);
+    if (multiMatch)
+        return multiMatch[1].trim();
+    return null;
+}
+function clampText(input, maxLen) {
+    if (input.length <= maxLen)
+        return input;
+    return input.slice(0, maxLen - 1).trimEnd() + '…';
+}
+function normalizeExternalSystem(input) {
+    return input
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9._-]/g, '')
+        .replace(/^-+|-+$/g, '');
+}
+function parseExternalSystems(raw) {
+    if (!raw)
+        return [];
+    const parts = Array.isArray(raw) ? raw : raw.split(/[,;]+/);
+    const normalized = parts
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .flatMap((part) => part.split(','))
+        .map((part) => normalizeExternalSystem(part));
+    return Array.from(new Set(normalized.filter(Boolean)));
+}
 /**
  * Auto-detect category from description or source
  */
 function detectCategory(description, source) {
     const text = `${description || ''} ${source}`.toLowerCase();
-    // Use-case categories first (higher-level, more meaningful)
-    if ((text.includes('scrape') || text.includes('crawl') || text.includes('extract from page') || text.includes('web scraping')) && text.includes('html'))
-        return 'scraping';
-    if (text.includes('health check') || text.includes('uptime') || text.includes('monitor') || text.includes('observ'))
-        return 'monitoring';
-    if ((text.includes('pipeline') || text.includes('batch') || text.includes('schedule') || text.includes('automat')) && !text.includes('json'))
-        return 'automation';
-    if ((text.includes('api') && (text.includes('retry') || text.includes('integration') || text.includes('client'))) || text.includes('api integration'))
-        return 'integration';
-    if ((text.includes('analys') || text.includes('aggregate') || text.includes('report') || text.includes('insight')) && (text.includes('data') || text.includes('text')))
-        return 'analysis';
-    if (text.includes('content') && (text.includes('process') || text.includes('generat') || text.includes('transform')))
-        return 'content';
-    // Technical categories
-    if (text.includes('jwt') || text.includes('oauth') || text.includes('token') || text.includes('auth'))
-        return 'auth';
-    if (text.includes('base64') || text.includes('hex') || text.includes('encode') || text.includes('decode'))
-        return 'encode';
-    if (text.includes('sha256') || text.includes('sha512') || text.includes('md5') || text.includes('hash'))
-        return 'hash';
-    if (text.includes('json') && (text.includes('parse') || text.includes('stringify') || text.includes('flatten')))
-        return 'json';
-    if (text.includes('csv') || text.includes('tsv') || text.includes('tabular'))
-        return 'csv';
-    if (text.includes('yaml') || text.includes('toml') || text.includes('config'))
-        return 'yaml';
-    if (text.includes('xml') || text.includes('markup'))
-        return 'xml';
-    if (text.includes('regex') || text.includes('pattern') || text.includes('match'))
-        return 'regex';
-    if (text.includes('uuid') || text.includes('generate') || text.includes('random id'))
-        return 'generate';
-    if (text.includes('template') || text.includes('render') || text.includes('mustache'))
-        return 'template';
-    if (text.includes('validate') || text.includes('schema') || text.includes('check'))
-        return 'validate';
-    if (text.includes('sanitize') || text.includes('clean') || text.includes('escape'))
-        return 'sanitize';
-    if (text.includes('polymarket'))
-        return 'polymarket';
-    if (text.includes('database') || text.includes('sql') || text.includes('query builder'))
-        return 'database';
-    if (text.includes('email'))
+    if (/(github|repo|pull request|issue|workflow|actions)/.test(text))
+        return 'github';
+    if (/(email|smtp|imap|mailgun|sendgrid)/.test(text))
         return 'email';
-    if (text.includes('graph') || text.includes('dfs') || text.includes('bfs') || text.includes('traversal'))
-        return 'graph';
-    if (text.includes('log') && (text.includes('structured') || text.includes('logging')))
-        return 'logging';
-    if (text.includes('geo') || text.includes('haversine') || text.includes('latitude') || text.includes('longitude'))
-        return 'geo';
-    if (text.includes('qr') || text.includes('barcode'))
-        return 'qr';
-    if (text.includes('color') || text.includes('rgb') || text.includes('hsl'))
-        return 'color';
-    if (text.includes('image') || text.includes('resize') || text.includes('thumbnail'))
-        return 'image';
-    if (text.includes('diff') || text.includes('compare') || text.includes('levenshtein'))
-        return 'diff';
-    if (text.includes('sort') || text.includes('search') || text.includes('filter'))
-        return 'sort';
-    if (text.includes('array') || text.includes('chunk') || text.includes('flatten'))
-        return 'array';
-    if (text.includes('statistics') || text.includes('mean') || text.includes('median') || text.includes('stddev'))
-        return 'stats';
-    if (text.includes('convert') || text.includes('unit') || text.includes('celsius') || text.includes('fahrenheit'))
-        return 'convert';
-    if (text.includes('timezone') || text.includes('utc'))
-        return 'timezone';
-    if (text.includes('compress') || text.includes('zip') || text.includes('gzip'))
-        return 'compress';
-    if (text.includes('path') || text.includes('dirname') || text.includes('basename'))
-        return 'path';
-    if (text.includes('nlp') || text.includes('sentiment') || text.includes('tokenize'))
-        return 'nlp';
-    if (text.includes('cli') || text.includes('terminal') || text.includes('command'))
-        return 'cli';
-    if (text.includes('debug') || text.includes('test'))
-        return 'debug';
-    if (text.includes('html') || text.includes('dom') || text.includes('scrape'))
-        return 'html';
-    if (text.includes('url') || text.includes('link') || text.includes('href'))
-        return 'url';
-    if (text.includes('api') || text.includes('rest') || text.includes('graphql'))
+    if (/(discord|slack|twitter|x\.com|reddit|youtube|tiktok|social)/.test(text))
+        return 'social';
+    if (/(api|sdk|oauth|webhook|rest|graphql|integration)/.test(text))
         return 'api';
-    if (text.includes('fetch') || text.includes('http') || text.includes('request'))
+    if (/(url|http|https|fetch|request|scrape|crawl|html|dom|web)/.test(text))
         return 'web';
-    if (text.includes('encrypt') || text.includes('crypto') || text.includes('secure'))
-        return 'crypto';
-    if (text.includes('parse') || text.includes('transform') || text.includes('data'))
-        return 'data';
-    if (text.includes('time') || text.includes('date') || text.includes('timestamp'))
-        return 'time';
-    if (text.includes('text') || text.includes('string') || text.includes('format'))
-        return 'text';
-    if (text.includes('math') || text.includes('random') || text.includes('number') || text.includes('calc'))
-        return 'math';
-    if (text.includes('file') || text.includes('read') || text.includes('write'))
-        return 'file';
-    if (text.includes('ai') || text.includes('ml') || text.includes('gpt') || text.includes('model'))
+    if (/(database|postgres|mysql|sqlite|redis|mongo|sql|vector)/.test(text))
+        return 'database';
+    if (/(file|path|read|write|fs|directory|folder|bucket|s3|storage|upload|download)/.test(text))
+        return 'files';
+    if (/(auth|jwt|token|sign|verify|encrypt|decrypt|hmac|security)/.test(text))
+        return 'security';
+    if (/(ai|ml|gpt|llm|model|embedding|nlp|tokenize|summarize|classify)/.test(text))
         return 'ai';
-    return 'util';
+    return 'core';
 }
 /**
  * Try to find a README file automatically
@@ -276,6 +303,9 @@ function validateToolSource(source, language) {
             warnings.push('Tool does not use json.dumps. Output may not be valid JSON.');
         }
     }
+    if (language === 'bash' || language === 'ruby' || language === 'php' || language === 'shebang') {
+        return { valid: true, warnings };
+    }
     return { valid: true, warnings };
 }
 export async function submit(name, file, options) {
@@ -304,14 +334,21 @@ export async function submit(name, file, options) {
     }
     // Detect language
     const ext = extname(filePath);
-    const language = LANG_MAP[ext];
+    // Read source
+    const source = readFileSync(filePath, 'utf-8');
+    let language = LANG_MAP[ext];
+    if (!language) {
+        const shebangLang = detectShebangLanguage(source);
+        if (shebangLang) {
+            language = shebangLang;
+        }
+    }
     if (!language) {
-        console.log(`\n❌ Unsupported file type: ${ext}`);
-        console.log(`   Supported: .ts, .js, .py\n`);
+        console.log(`\n❌ Unsupported file type: ${ext || '(no extension)'}`);
+        console.log(`   Supported: .ts, .js, .py, .sh, .rb, .php`);
+        console.log(`   Or include a shebang (#! /usr/bin/env <lang>) for script tools.\n`);
         process.exit(1);
     }
-    // Read source
-    const source = readFileSync(filePath, 'utf-8');
     // ── Validate tool source format ──
     const { warnings } = validateToolSource(source, language);
     if (warnings.length > 0) {
@@ -343,6 +380,36 @@ export async function submit(name, file, options) {
     if (!description && readme) {
         description = extractDescriptionFromReadme(readme);
     }
+    const intent = readme
+        ? (extractSectionFromReadme(readme, 'Intent') || extractTaggedValue(source, 'Intent'))
+        : extractTaggedValue(source, 'Intent');
+    const gap = readme
+        ? (extractSectionFromReadme(readme, 'Gap Justification') || extractTaggedValue(source, 'Gap Justification'))
+        : extractTaggedValue(source, 'Gap Justification');
+    const metaParts = [
+        intent ? `Intent: ${intent}` : null,
+        gap ? `Gap: ${gap}` : null,
+    ].filter(Boolean);
+    const meta = metaParts.length > 0 ? metaParts.join(' | ') : null;
+    const externalFromReadme = readme
+        ? parseExternalSystems(extractListSectionFromReadme(readme, 'External Systems'))
+        : [];
+    const externalFromSource = parseExternalSystems(extractTaggedValue(source, 'External Systems') || extractTaggedValue(source, 'External System'));
+    const externalFromOption = parseExternalSystems(options.external);
+    const externalSystems = Array.from(new Set([
+        ...externalFromOption,
+        ...externalFromReadme,
+        ...externalFromSource,
+    ]));
+    if (meta) {
+        if (!description) {
+            description = meta;
+        }
+        else if (!description.includes('Intent:') && !description.includes('Gap:')) {
+            description = `${description} | ${meta}`;
+        }
+        description = clampText(description, 240);
+    }
     if (!description) {
         console.log(`\n❌ Description required. Please provide a description for your tool.`);
         console.log(`\n   Option 1: Use -d "Your description here"`);
@@ -375,7 +442,7 @@ export async function submit(name, file, options) {
         console.log(`\n📁 Category Selection`);
         console.log(`   Auto-detected: ${detectedCat?.name || category} (${category})`);
         console.log(`\n   Common categories:`);
-        const commonCategories = ['api', 'json', 'data', 'text', 'web', 'crypto', 'file', 'array', 'validate', 'util', 'other'];
+        const commonCategories = ['core', 'web', 'api', 'ai', 'social', 'github', 'email', 'database', 'files', 'security'];
         for (const catId of commonCategories) {
             const cat = CATEGORIES.find(c => c.id === catId);
             if (cat) {
@@ -402,6 +469,12 @@ export async function submit(name, file, options) {
         console.log(`\n💡 Tip: Category auto-detected as "${category}"`);
         console.log(`   Use -c <category> to specify a different category.\n`);
     }
+    if (category !== 'core' && externalSystems.length === 0) {
+        console.log(`\n❌ External Systems required for gravity tools.`);
+        console.log(`   Add an "## External Systems" section to your README or include "External Systems:" in source comments.`);
+        console.log(`   Or pass: --external "github,slack,openai"\n`);
+        process.exit(1);
+    }
     // Parse dependencies
     const dependencies = options.deps
         ? options.deps.split(',').map(d => d.trim()).filter(Boolean)
@@ -410,6 +483,20 @@ export async function submit(name, file, options) {
     const buildsOn = options.buildsOn
         ? options.buildsOn.split(',').map(d => d.trim()).filter(Boolean)
         : [];
+    if (buildsOn.length === 0) {
+        if (!intent) {
+            console.log(`\n❌ Intent required for primitive tools.`);
+            console.log(`   Add an "## Intent" section to your README or include "Intent:" in source comments.`);
+            console.log(`   Example:\n   ## Intent\n   Normalize a URL before hashing\n`);
+            process.exit(1);
+        }
+        if (!gap) {
+            console.log(`\n❌ Gap justification required for primitive tools.`);
+            console.log(`   Add an "## Gap Justification" section to your README or include "Gap Justification:" in source comments.`);
+            console.log(`   Example:\n   ## Gap Justification\n   Existing tools do not trim tracking params before hashing.\n`);
+            process.exit(1);
+        }
+    }
     if (!options.buildsOn && buildsOn.length === 0) {
         console.log(`\n💡 Tip: Use --builds-on to show lineage!`);
         console.log(`   Example: --builds-on api-request,json-validate`);
@@ -444,6 +531,14 @@ export async function submit(name, file, options) {
         }
     }
     // ── Pre-submit execution validation ──
+    if (options.skipValidation) {
+        const allowSkip = ['1', 'true', 'yes'].includes((process.env.DEVTOPIA_ALLOW_SKIP_VALIDATION || '').toLowerCase());
+        if (!allowSkip) {
+            console.log(`\n❌ --skip-validation is restricted.`);
+            console.log(`   Set DEVTOPIA_ALLOW_SKIP_VALIDATION=1 to use it (admin only).\n`);
+            process.exit(1);
+        }
+    }
     if (!options.skipValidation) {
         console.log(`\n   Validating tool execution...`);
         const validation = await validateExecution(source, language);
@@ -472,6 +567,8 @@ export async function submit(name, file, options) {
         console.log(`   Deps:     ${dependencies.join(', ')}`);
     if (buildsOn.length)
         console.log(`   Builds on: ${buildsOn.join(', ')}`);
+    if (externalSystems.length)
+        console.log(`   External: ${externalSystems.join(', ')}`);
     try {
         const res = await fetch(`${API_BASE}/api/submit`, {
             method: 'POST',
@@ -485,6 +582,7 @@ export async function submit(name, file, options) {
                 category,
                 source,
                 dependencies,
+                external_systems: externalSystems.length > 0 ? externalSystems : undefined,
                 builds_on: buildsOn.length > 0 ? buildsOn : undefined,
                 input_schema: inputSchema ? JSON.stringify(inputSchema) : undefined,
                 output_schema: outputSchema ? JSON.stringify(outputSchema) : undefined,

package/dist/executor.d.ts

@@ -13,10 +13,7 @@ interface ValidationResult {
     stderr: string;
     exitCode: number | null;
 }
-/**
- * Get the interpreter command for a language
- */
-export declare function getInterpreter(language: string): {
+export declare function getInterpreter(language: string, toolFile?: string): {
     cmd: string;
     args: string[];
     ext: string;
@@ -34,4 +31,5 @@ export declare function wrapSourceIfNeeded(source: string, language: string): st
  */
 export declare function validateExecution(source: string, language: string): Promise<ValidationResult>;
 export declare function executeTool(toolName: string, input: any, options?: ExecuteOptions): Promise<ExecutionResult>;
+export declare function executeLocalFile(filePath: string, input: any, options?: ExecuteOptions): Promise<ExecutionResult>;
 export {};