devtopia 1.9.0 → 2.0.1

package/dist/commands/submit.js

@@ -3,81 +3,38 @@ import { extname, resolve, dirname, join } from 'path';
 import { createInterface } from 'readline';
 import { API_BASE } from '../config.js';
 import { loadIdentity, hasIdentity } from '../identity.js';
+import { validateExecution } from '../executor.js';
 const LANG_MAP = {
     '.ts': 'typescript',
     '.js': 'javascript',
     '.py': 'python',
     '.mjs': 'javascript',
     '.cjs': 'javascript',
+    '.sh': 'bash',
+    '.bash': 'bash',
+    '.rb': 'ruby',
+    '.php': 'php',
 };
-// Valid categories - grouped by type
-const CATEGORIES = [
-    // Data & Parsing
-    { id: 'data', name: 'Data Processing' },
-    { id: 'json', name: 'JSON & Objects' },
-    { id: 'csv', name: 'CSV & Tables' },
-    { id: 'xml', name: 'XML & Markup' },
-    { id: 'yaml', name: 'YAML & Config' },
-    // Text & Strings
-    { id: 'text', name: 'Text & NLP' },
-    { id: 'string', name: 'String Utils' },
-    { id: 'regex', name: 'Regex & Patterns' },
-    { id: 'format', name: 'Formatting' },
-    // Web & Network
-    { id: 'web', name: 'Web & HTTP' },
-    { id: 'api', name: 'API Tools' },
-    { id: 'url', name: 'URL & Links' },
-    { id: 'html', name: 'HTML & DOM' },
-    // Security & Crypto
-    { id: 'crypto', name: 'Crypto & Security' },
-    { id: 'hash', name: 'Hashing' },
-    { id: 'encode', name: 'Encoding' },
-    { id: 'auth', name: 'Authentication' },
-    // Math & Numbers
-    { id: 'math', name: 'Math & Numbers' },
-    { id: 'stats', name: 'Statistics' },
-    { id: 'convert', name: 'Conversion' },
-    { id: 'random', name: 'Random & Generate' },
-    // Date & Time
-    { id: 'time', name: 'Date & Time' },
-    { id: 'timezone', name: 'Timezones' },
-    // Files & System
-    { id: 'file', name: 'File & I/O' },
-    { id: 'path', name: 'Paths' },
-    { id: 'compress', name: 'Compression' },
-    // Arrays & Collections
-    { id: 'array', name: 'Arrays & Lists' },
-    { id: 'sort', name: 'Sort & Search' },
-    { id: 'set', name: 'Sets & Maps' },
-    // Validation
-    { id: 'validate', name: 'Validation' },
-    { id: 'sanitize', name: 'Sanitization' },
-    // Generation
-    { id: 'generate', name: 'Generation' },
-    { id: 'template', name: 'Templates' },
-    // AI & ML
-    { id: 'ai', name: 'AI & ML' },
-    { id: 'nlp', name: 'NLP' },
-    // Media
-    { id: 'image', name: 'Images' },
-    { id: 'color', name: 'Colors' },
-    { id: 'qr', name: 'QR & Barcodes' },
-    // Dev Tools
-    { id: 'cli', name: 'CLI & Terminal' },
-    { id: 'debug', name: 'Debug & Test' },
-    { id: 'diff', name: 'Diff & Compare' },
-    // General
-    { id: 'util', name: 'Utilities' },
-    { id: 'other', name: 'Other' },
-];
+/**
+ * Fetch categories from the API (single source of truth)
+ */
+async function fetchCategories() {
+    try {
+        const res = await fetch(`${API_BASE}/api/categories`);
+        const data = await res.json();
+        return (data.categories || []).map((c) => ({
+            id: c.id,
+            name: c.name,
+            description: c.description,
+        }));
+    }
+    catch {
+        // Fallback: return empty array — submit will still work, server validates
+        return [];
+    }
+}
 /**
  * Extract description from source code comments
- * Supports multiple formats:
- * - // tool-name - description
- * - # tool-name - description
- * - JSDoc: * tool-name - description
- * - JSDoc: First sentence after title in /** block
- * - JSDoc @description tag
  */
 function extractDescription(source) {
     const lines = source.split('\n');
@@ -85,7 +42,6 @@ function extractDescription(source) {
     let jsdocTitle = false;
     for (const line of lines) {
         const trimmed = line.trim();
-        // Track JSDoc block
         if (trimmed === '/**') {
             inJSDoc = true;
             jsdocTitle = false;
@@ -95,7 +51,7 @@ function extractDescription(source) {
             inJSDoc = false;
             continue;
         }
-        // TypeScript/JavaScript single line: // tool-name - description
+        // TypeScript/JavaScript: // tool-name - description
         const tsMatch = line.match(/^\/\/\s*[\w-]+\s*[-–:]\s*(.+)$/);
         if (tsMatch)
             return tsMatch[1].trim();
@@ -103,55 +59,35 @@ function extractDescription(source) {
         const pyMatch = line.match(/^#\s*[\w-]+\s*[-–:]\s*(.+)$/);
         if (pyMatch)
             return pyMatch[1].trim();
-        // JSDoc block comment: * tool-name - description
-        const jsdocToolMatch = line.match(/^\s*\*\s*[\w-]+\s*[-–:]\s*(.+)$/);
-        if (jsdocToolMatch)
-            return jsdocToolMatch[1].trim();
-        // JSDoc @description tag
+        // JSDoc: * @description
         const jsdocDescMatch = line.match(/^\s*\*\s*@description\s+(.+)$/);
         if (jsdocDescMatch)
             return jsdocDescMatch[1].trim();
-        // Inside JSDoc: look for description after title
+        // JSDoc: first content line after /** that describes the tool
         if (inJSDoc) {
-            // Skip @ tags
             if (trimmed.match(/^\*\s*@/))
                 continue;
-            // Extract content after *
             const jsdocContent = trimmed.match(/^\*\s*(.+)$/);
             if (jsdocContent) {
                 const content = jsdocContent[1].trim();
-                // Skip if it looks like a title (short, capitalized, no punctuation)
                 if (!jsdocTitle && content.length < 50 && !content.includes('.') && /^[A-Z]/.test(content)) {
                     jsdocTitle = true;
                     continue;
                 }
-                // After title, next non-empty content line is likely the description
                 if (jsdocTitle && content.length > 10) {
-                    // Return first sentence
                     const firstSentence = content.match(/^[^.!?]+[.!?]?/);
                     if (firstSentence)
                         return firstSentence[0].trim();
                     return content;
                 }
             }
-            // Skip empty JSDoc lines
             if (trimmed === '*')
                 continue;
         }
-        // Skip empty lines, shebang, opening markers, and usage lines
-        if (trimmed === '' ||
-            line.startsWith('#!') ||
-            trimmed === '/**' ||
-            trimmed === '*/' ||
-            trimmed === '*' ||
-            trimmed.toLowerCase().includes('usage:')) {
+        if (trimmed === '' || line.startsWith('#!') || trimmed === '/**' || trimmed === '*/' || trimmed === '*' || trimmed.toLowerCase().includes('usage:')) {
             continue;
         }
-        // Stop if we hit non-comment code
-        if (!trimmed.startsWith('//') &&
-            !trimmed.startsWith('#') &&
-            !trimmed.startsWith('*') &&
-            !trimmed.startsWith('/*')) {
+        if (!trimmed.startsWith('//') && !trimmed.startsWith('#') && !trimmed.startsWith('*') && !trimmed.startsWith('/*')) {
             break;
         }
     }
@@ -164,17 +100,13 @@ function extractDescriptionFromReadme(readme) {
     const lines = readme.split('\n');
     let foundTitle = false;
     for (const line of lines) {
-        // Skip title lines (# Title)
         if (line.startsWith('#')) {
             foundTitle = true;
             continue;
         }
-        // Skip empty lines after title
         if (foundTitle && line.trim() === '')
             continue;
-        // First non-empty line after title is the description
         if (foundTitle && line.trim()) {
-            // Take first sentence or up to 100 chars
             const desc = line.trim();
             const firstSentence = desc.match(/^[^.!?]+[.!?]?/);
             if (firstSentence && firstSentence[0].length <= 100) {
@@ -185,88 +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();
-    // Specific categories first (more specific matches)
-    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('qr') || text.includes('barcode'))
-        return 'qr';
-    if (text.includes('color') || text.includes('rgb') || text.includes('hex') || 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') || text.includes('log'))
-        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 (/(github|repo|pull request|issue|workflow|actions)/.test(text))
+        return 'github';
+    if (/(email|smtp|imap|mailgun|sendgrid)/.test(text))
+        return 'email';
+    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';
-    // Broader categories
-    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
@@ -286,6 +265,49 @@ function findReadme(filePath, toolName) {
     }
     return null;
 }
+/**
+ * Validate tool source: check it defines proper I/O
+ */
+function validateToolSource(source, language) {
+    const warnings = [];
+    if (language === 'javascript' || language === 'typescript') {
+        const hasArgvParse = /process\.argv\[2\]/.test(source);
+        const definesMain = /\bfunction\s+main\s*\(/.test(source);
+        const hasConsoleLog = /console\.log\s*\(/.test(source);
+        const hasJSONStringify = /JSON\.stringify/.test(source);
+        if (!hasArgvParse && !definesMain) {
+            warnings.push('Tool does not read input (process.argv[2]) or define main(). It may not work when run.');
+        }
+        if (!hasConsoleLog && !definesMain) {
+            warnings.push('Tool does not output results (console.log). It may produce no output when run.');
+        }
+        if (!hasJSONStringify && !definesMain) {
+            warnings.push('Tool does not use JSON.stringify. Output may not be valid JSON.');
+        }
+        if (definesMain && !hasArgvParse) {
+            // This will be auto-wrapped by executor — that's fine
+        }
+    }
+    if (language === 'python') {
+        const hasSysArgv = /sys\.argv/.test(source);
+        const definesMain = /\bdef\s+main\s*\(/.test(source);
+        const hasPrint = /\bprint\s*\(/.test(source);
+        const hasJsonDumps = /json\.dumps/.test(source);
+        if (!hasSysArgv && !definesMain) {
+            warnings.push('Tool does not read input (sys.argv) or define main(). It may not work when run.');
+        }
+        if (!hasPrint && !definesMain) {
+            warnings.push('Tool does not print output. It may produce nothing when run.');
+        }
+        if (!hasJsonDumps && !definesMain) {
+            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) {
     // Check identity
     if (!hasIdentity()) {
@@ -312,14 +334,30 @@ 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) {
-        console.log(`\n❌ Unsupported file type: ${ext}`);
-        console.log(`   Supported: .ts, .js, .py\n`);
+        const shebangLang = detectShebangLanguage(source);
+        if (shebangLang) {
+            language = shebangLang;
+        }
+    }
+    if (!language) {
+        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) {
+        console.log(`\n⚠️  Source validation warnings:`);
+        for (const w of warnings) {
+            console.log(`   - ${w}`);
+        }
+        console.log(`   (tool may still work if executor can auto-wrap it)\n`);
+    }
     // Find and read README
     let readmePath = options.readme ? resolve(options.readme) : findReadme(filePath, name);
     let readme = null;
@@ -339,11 +377,39 @@ export async function submit(name, file, options) {
     }
     // Extract or use provided description
     let description = options.description || extractDescription(source);
-    // Try to get description from README if not found in source
     if (!description && readme) {
         description = extractDescriptionFromReadme(readme);
     }
-    // Description is required
+    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"`);
@@ -352,13 +418,15 @@ export async function submit(name, file, options) {
         console.log(`   Option 3: Add a description after the title in your README\n`);
         process.exit(1);
     }
+    // ── Fetch categories from API (single source of truth) ──
+    const CATEGORIES = await fetchCategories();
     // Determine category
     let category = options.category;
-    if (category && !CATEGORIES.find(c => c.id === category)) {
+    if (category && CATEGORIES.length > 0 && !CATEGORIES.find(c => c.id === category)) {
         console.log(`\n❌ Invalid category: ${category}`);
         console.log(`\n   Valid categories:`);
         for (const cat of CATEGORIES) {
-            console.log(`   ${cat.id.padEnd(10)} ${cat.name}`);
+            console.log(`   ${cat.id.padEnd(12)} ${cat.name}`);
         }
         console.log();
         process.exit(1);
@@ -367,35 +435,25 @@ export async function submit(name, file, options) {
     if (!category) {
         category = detectCategory(description, source);
     }
-    // Prompt for category confirmation/selection if not provided via CLI
-    if (!options.category && process.stdin.isTTY) {
-        const rl = createInterface({
-            input: process.stdin,
-            output: process.stdout
-        });
+    // Prompt for category confirmation if TTY
+    if (!options.category && process.stdin.isTTY && CATEGORIES.length > 0) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
         const detectedCat = CATEGORIES.find(c => c.id === category);
         console.log(`\n📁 Category Selection`);
         console.log(`   Auto-detected: ${detectedCat?.name || category} (${category})`);
         console.log(`\n   Common categories:`);
-        // Show most common/relevant 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) {
-                const marker = cat.id === category ? ' ← detected' : '';
+                const marker = cat.id === category ? ' <- detected' : '';
                 console.log(`   ${cat.id.padEnd(12)} ${cat.name}${marker}`);
             }
         }
         console.log(`\n   (Use 'devtopia categories' to see all categories)`);
         console.log(`\n   Press Enter to use detected category, or type a category ID:`);
         const answer = await new Promise((resolve) => {
-            rl.question(`   Category [${category}]: `, (ans) => {
-                rl.close();
-                resolve(ans.trim());
-            });
+            rl.question(`   Category [${category}]: `, (ans) => { rl.close(); resolve(ans.trim()); });
         });
         if (answer) {
             const selectedCat = CATEGORIES.find(c => c.id === answer.toLowerCase());
@@ -411,20 +469,90 @@ 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)
         : [];
-    // Parse builds_on (parent tools this tool extends/composes)
+    // Parse builds_on
     const buildsOn = options.buildsOn
         ? options.buildsOn.split(',').map(d => d.trim()).filter(Boolean)
         : [];
-    // Encourage lineage tracking
+    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`);
         console.log(`   This helps others see how tools build on each other.\n`);
     }
+    // ── Extract schema from JSDoc @param tags ──
+    let inputSchema = null;
+    let outputSchema = null;
+    if (options.schema) {
+        try {
+            const schemaContent = JSON.parse(readFileSync(resolve(options.schema), 'utf-8'));
+            inputSchema = schemaContent.inputs || null;
+            outputSchema = schemaContent.outputs || null;
+        }
+        catch {
+            console.log(`\n⚠️  Could not parse schema file: ${options.schema}`);
+        }
+    }
+    if (!inputSchema) {
+        // Auto-extract from JSDoc @param tags
+        const paramMatches = source.matchAll(/@param\s+\{(\w+)\}\s+([\w.]+)\s*[-–]?\s*(.*)/g);
+        const extracted = {};
+        for (const match of paramMatches) {
+            const type = match[1].toLowerCase();
+            const paramName = match[2].replace(/^params\./, '');
+            if (paramName !== 'params') {
+                extracted[paramName] = type;
+            }
+        }
+        if (Object.keys(extracted).length > 0) {
+            inputSchema = extracted;
+        }
+    }
+    // ── 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);
+        if (!validation.valid) {
+            const reason = validation.stderr
+                ? validation.stderr.split('\n')[0]
+                : (validation.stdout ? 'Tool produced non-JSON output.' : 'Tool produced no output.');
+            console.log(`\n❌ Tool failed validation: ${reason}`);
+            console.log(`\n   Your tool must produce JSON output (even error JSON like {"error":"..."}).`);
+            console.log(`   Use --skip-validation to bypass this check.\n`);
+            process.exit(1);
+        }
+        console.log(`   Validation passed (exit ${validation.exitCode}, ${validation.stdout.length} bytes output)`);
+    }
     const catInfo = CATEGORIES.find(c => c.id === category);
     console.log(`\n📦 Submitting ${name}...`);
     console.log(`   File:     ${file}`);
@@ -433,10 +561,14 @@ export async function submit(name, file, options) {
     console.log(`   README:   ${readmePath}`);
     if (description)
         console.log(`   Desc:     ${description}`);
+    if (inputSchema)
+        console.log(`   Schema:   ${Object.keys(inputSchema).join(', ')}`);
     if (dependencies.length)
         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',
@@ -450,7 +582,10 @@ 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,
             }),
         });
         const data = await res.json();
@@ -465,6 +600,14 @@ export async function submit(name, file, options) {
         if (buildsOn.length > 0) {
             console.log(`   Builds on: ${buildsOn.join(', ')}`);
         }
+        // Show similar tools warning (duplicate detection)
+        if (data.similar_tools && data.similar_tools.length > 0) {
+            console.log(`\n⚠️  Similar tools already exist:`);
+            for (const sim of data.similar_tools) {
+                console.log(`   - ${sim.name}: "${sim.description || 'No description'}"`);
+            }
+            console.log(`   Consider composing with existing tools instead of creating new ones.`);
+        }
         console.log(`\n   Others can now:`);
         console.log(`   $ devtopia cat ${name}`);
         console.log(`   $ devtopia run ${name} '{...}'\n`);